454 lines
14 KiB
Markdown
454 lines
14 KiB
Markdown
TZ_LLM_Normalizer_v2.0.1.md
|
||
|
||
Ниже даю **ТЗ на `Normalizer v2.0.1`** — именно на снижение лишних `clarification`, без отката к старой хрупкой схеме.
|
||
|
||
---
|
||
|
||
# ТЗ: `Normalizer v2.0.1`
|
||
|
||
## Снижение избыточных clarification в decomposition-first схеме
|
||
|
||
---
|
||
|
||
## 1. Контекст
|
||
|
||
На `normalizer_v2` новая архитектура показала правильное направление:
|
||
|
||
* `schema_validation_pass_rate = 100`
|
||
* `scope_in_scope_rate = 100`
|
||
* `out_of_scope_fragment_rate = 0`
|
||
* `routed_fragment_rate = 100`
|
||
|
||
Но при этом:
|
||
|
||
* `clarification_required_rate = 80%`
|
||
|
||
Комментарий:
|
||
Это означает, что система уже умеет:
|
||
|
||
* не путать контур,
|
||
* не ломать схему,
|
||
* не раздувать сообщения на лишние фрагменты,
|
||
|
||
но пока **слишком часто боится исполнять нормальные in-scope вопросы без уточнения**.
|
||
|
||
---
|
||
|
||
## 2. Цель этапа
|
||
|
||
Сделать так, чтобы `v2`:
|
||
|
||
1. сохранял текущие сильные свойства:
|
||
|
||
* стабильную schema;
|
||
* корректный scope filter;
|
||
* decomposition-first архитектуру;
|
||
* безопасное поведение;
|
||
2. но реже уходил в unnecessary clarification на одноходовых бухгалтерских вопросах;
|
||
3. различал:
|
||
|
||
* реально неисполняемый вопрос,
|
||
* и вопрос, который можно исполнить с мягкими допущениями.
|
||
|
||
---
|
||
|
||
## 3. Главный принцип этапа
|
||
|
||
### Сейчас
|
||
|
||
Логика, похоже, такая:
|
||
|
||
> если вопрос не идеально конкретен, лучше clarification.
|
||
|
||
### Что нужно
|
||
|
||
Новая логика:
|
||
|
||
> если вопрос в контуре и уже достаточно понятен для выбора рабочего маршрута, его надо исполнять без clarification.
|
||
|
||
То есть `clarification` должен быть:
|
||
|
||
* не дефолтным safe fallback,
|
||
* а **редким и оправданным режимом**.
|
||
|
||
---
|
||
|
||
## 4. Что нужно ввести
|
||
|
||
---
|
||
|
||
## 4.1. Новый статус исполнимости
|
||
|
||
Вместо бинарной схемы:
|
||
|
||
* `executable`
|
||
* `needs_clarification`
|
||
|
||
нужно ввести три уровня:
|
||
|
||
### A. `executable`
|
||
|
||
Вопрос достаточно определён. Можно сразу идти дальше.
|
||
|
||
### B. `executable_with_soft_assumptions`
|
||
|
||
Вопрос не идеален, но:
|
||
|
||
* контур понятен,
|
||
* объектный узел понятен,
|
||
* тип задачи понятен,
|
||
* маршрут понятен,
|
||
* уточнение не критично для старта.
|
||
|
||
В этом случае **clarification не нужен**.
|
||
|
||
### C. `needs_clarification`
|
||
|
||
Вопрос слишком неопределённый, чтобы надёжно:
|
||
|
||
* выбрать маршрут,
|
||
* определить объект/период,
|
||
* или понять, какая именно задача ставится.
|
||
|
||
Комментарий:
|
||
Это главное изменение всей версии `v2.0.1`.
|
||
|
||
---
|
||
|
||
## 4.2. Новый флаг в `normalized_query_v2`
|
||
|
||
Добавить fragment-level поле:
|
||
|
||
```json
|
||
{
|
||
"execution_readiness": "executable | executable_with_soft_assumptions | needs_clarification",
|
||
"clarification_reason": "string | null"
|
||
}
|
||
```
|
||
|
||
Комментарий:
|
||
Сейчас у вас, судя по поведению, этого промежуточного уровня не хватает.
|
||
|
||
---
|
||
|
||
# 5. Правила, когда НЕ надо спрашивать уточнение
|
||
|
||
Нужно жёстко зафиксировать случаи, когда система должна **идти в исполнение**, даже если вопрос не идеально формален.
|
||
|
||
---
|
||
|
||
## 5.1. Вопрос уже in-scope и понятен по бизнес-узлу
|
||
|
||
Если вопрос:
|
||
|
||
* явно относится к текущей компании;
|
||
* относится к бухгалтерскому контуру;
|
||
* содержит бухгалтерский объект или проблемный узел;
|
||
* понятен по типу задачи,
|
||
|
||
то clarification не нужен.
|
||
|
||
Примеры:
|
||
|
||
* “зависшие авансы”
|
||
* “подозрительные остатки по 10”
|
||
* “хвосты по реализации”
|
||
* “подозрительные банковские движения”
|
||
* “записи по 97, которые повисли”
|
||
* “объекты ОС с кривой логикой начисления”
|
||
|
||
Комментарий:
|
||
Даже если человек говорит неидеально, **это уже нормальный рабочий запрос**.
|
||
|
||
---
|
||
|
||
## 5.2. Если хватает для route, не надо просить идеальную конкретику
|
||
|
||
Если уже можно определить:
|
||
|
||
* это rule-based,
|
||
* это anomaly,
|
||
* это cross-entity,
|
||
* это heavy overview,
|
||
|
||
то clarification не нужен только потому, что вопрос сформулирован “по-человечески”.
|
||
|
||
То есть:
|
||
|
||
* “выглядит подозрительно”
|
||
* “висит”
|
||
* “криво”
|
||
* “не сходится”
|
||
* “повисло”
|
||
* “аукнется позже”
|
||
|
||
не должны автоматически вести к clarification.
|
||
|
||
---
|
||
|
||
## 5.3. Если период можно взять из контекста сеанса — не спрашивать лишнее
|
||
|
||
Если в сессии уже есть:
|
||
|
||
* активный период,
|
||
* или дефолтный рабочий месяц,
|
||
* или системный `current_analysis_period`,
|
||
|
||
то fragment может идти как `executable_with_soft_assumptions`.
|
||
|
||
Комментарий:
|
||
Не надо мучить юзера вопросом “уточните период”, если в рабочем контуре и так есть активный месяц.
|
||
|
||
---
|
||
|
||
## 5.4. Если вопрос явно просит “найди проблемные места”, clarification не нужен
|
||
|
||
Вопросы вида:
|
||
|
||
* “где проблема”
|
||
* “покажи подозрительные”
|
||
* “что висит”
|
||
* “что не сходится”
|
||
* “что аукнется”
|
||
* “что требует проверки”
|
||
|
||
должны идти без уточнения, если:
|
||
|
||
* понятен участок учета,
|
||
* понятен тип проблемы,
|
||
* и нет конфликтующих предметных смыслов.
|
||
|
||
---
|
||
|
||
# 6. Когда clarification действительно нужен
|
||
|
||
Нужно сузить этот режим до реально сложных случаев.
|
||
|
||
Clarification нужен, если:
|
||
|
||
### 6.1.
|
||
|
||
Непонятно, вопрос вообще про бухгалтерский контур или нет.
|
||
|
||
### 6.2.
|
||
|
||
Непонятно, про какой объект/участок учёта идёт речь вообще.
|
||
|
||
Пример:
|
||
|
||
* “чекни, что там у нас не так”
|
||
|
||
### 6.3.
|
||
|
||
В сообщении несколько задач, но они конфликтуют и не раскладываются надёжно.
|
||
|
||
### 6.4.
|
||
|
||
Для исполнения критично не хватает периода, а его нельзя безопасно вывести из контекста.
|
||
|
||
### 6.5.
|
||
|
||
Вопрос смешивает:
|
||
|
||
* данные компании,
|
||
* и общую бухгалтерскую теорию / законы / абстрактные советы.
|
||
|
||
---
|
||
|
||
# 7. Что нужно поменять в prompt’ах
|
||
|
||
---
|
||
|
||
## 7.1. Developer prompt
|
||
|
||
Добавить блок:
|
||
|
||
```text
|
||
If a fragment is clearly in-scope, maps to a recognizable accounting problem area, and provides enough information to choose a working route, do not mark it as clarification-required.
|
||
|
||
Use `execution_readiness = executable_with_soft_assumptions` when the request is operationally understandable even if some details are implicit.
|
||
|
||
Only use `needs_clarification` when missing information blocks reliable execution or routing.
|
||
```
|
||
|
||
---
|
||
|
||
## 7.2. Отдельно прописать мягкие рабочие запросы
|
||
|
||
Добавить правило:
|
||
|
||
```text
|
||
Questions phrased in human, vague, or colloquial accounting language (for example: “what is hanging”, “what looks suspicious”, “what may blow up later”, “what does not converge”, “what is crooked here”) should still be executable if the accounting area and business problem are understandable.
|
||
```
|
||
|
||
---
|
||
|
||
## 7.3. Не требовать лишней формальности
|
||
|
||
Добавить правило:
|
||
|
||
```text
|
||
Do not require document IDs, exact periods, or exact objects when the user is clearly asking for a scan, review, anomaly search, rule check, or problem-area analysis.
|
||
```
|
||
|
||
---
|
||
|
||
# 8. Что поменять в коде
|
||
|
||
---
|
||
|
||
## 8.1. Добавить `execution_readiness`
|
||
|
||
Новый enum:
|
||
|
||
* `executable`
|
||
* `executable_with_soft_assumptions`
|
||
* `needs_clarification`
|
||
|
||
---
|
||
|
||
## 8.2. Clarification policy runner
|
||
|
||
Сделать отдельную функцию:
|
||
|
||
```text
|
||
decide_fragment_execution_policy(fragment, session_context) -> execution_policy
|
||
```
|
||
|
||
Она должна проверять:
|
||
|
||
* in-scope ли фрагмент;
|
||
* понятен ли бизнес-узел;
|
||
* можно ли выбрать route;
|
||
* есть ли активный период/контекст;
|
||
* критична ли недосказанность.
|
||
|
||
---
|
||
|
||
## 8.3. Clarification не должен срабатывать напрямую из prompt без post-check
|
||
|
||
То есть:
|
||
|
||
* LLM может пометить `needs_clarification`,
|
||
* но код должен ещё раз проверить:
|
||
|
||
* а правда ли вопрос неисполняемый?
|
||
* или это просто мягкий человеческий запрос, который можно обработать?
|
||
|
||
Комментарий:
|
||
Это важно, чтобы не возвращать system behavior обратно в “LLM испугалась — всё, стоп”.
|
||
|
||
---
|
||
|
||
# 9. Что нужно в GUI
|
||
|
||
Добавить в output:
|
||
|
||
### A. `execution_readiness`
|
||
|
||
По каждому фрагменту.
|
||
|
||
### B. `clarification_reason`
|
||
|
||
Чтобы видеть, почему система решила тормозить.
|
||
|
||
### C. `soft_assumption_used`
|
||
|
||
Например:
|
||
|
||
* `period_from_session_context`
|
||
* `company_scope_defaulted`
|
||
* `problem_scan_mode_enabled`
|
||
|
||
Это поможет отлаживать поведение без гадания.
|
||
|
||
---
|
||
|
||
# 10. Новый eval для `v2.0.1`
|
||
|
||
Нужен отдельный маленький eval-набор:
|
||
не на multi-intent, а на **clarification policy**.
|
||
|
||
## Размер
|
||
|
||
15–20 кейсов.
|
||
|
||
## Состав
|
||
|
||
* 10 одноходовых in-scope вопросов, которые **не должны** требовать clarification;
|
||
* 5 реально ambiguous вопросов, которые **должны** требовать clarification;
|
||
* 3–5 смешанных или out-of-scope вопросов.
|
||
|
||
## Метрики
|
||
|
||
Добавить:
|
||
|
||
* `clarification_precision`
|
||
* `clarification_recall`
|
||
* `false_clarification_rate`
|
||
* `executable_with_soft_assumptions_rate`
|
||
|
||
---
|
||
|
||
# 11. Целевые показатели этапа
|
||
|
||
Минимально приемлемо:
|
||
|
||
* `clarification_required_rate <= 50%` на таких одноходовых бухгалтерских вопросах
|
||
* `false_clarification_rate` заметно ниже текущего
|
||
* scope/schema не деградируют
|
||
|
||
Хорошо:
|
||
|
||
* `clarification_required_rate <= 35%`
|
||
|
||
Очень хорошо:
|
||
|
||
* `clarification_required_rate <= 25%`
|
||
|
||
Комментарий:
|
||
Не надо ставить сразу “0 clarification”.
|
||
Clarification нужен, просто не должен быть режимом по умолчанию.
|
||
|
||
---
|
||
|
||
# 12. Что нельзя делать
|
||
|
||
Codex запрещено:
|
||
|
||
1. возвращать старую route-first схему `v1.x`;
|
||
2. выключать clarification совсем;
|
||
3. снова делать один большой `intent_class` центром мира;
|
||
4. жёстко захардкодить эти 10 вопросов;
|
||
5. тюнить только под конкретную десятку вместо общей policy.
|
||
|
||
---
|
||
|
||
# 13. Артефакты
|
||
|
||
Codex должен выдать:
|
||
|
||
1. `docs/normalizer_v2_0_1_spec.md`
|
||
2. `prompts/developer/normalizer_v2_0_1.txt`
|
||
3. `schemas/normalized_query_v2_0_1.json`
|
||
4. `docs/clarification_policy.md`
|
||
5. `reports/v2_0_1_clarification_eval_plan.md`
|
||
|
||
---
|
||
|
||
# 14. Короткий смысл этапа
|
||
|
||
`v2.0.1` — это не улучшение “понимания бухгалтерии”.
|
||
Это **настройка порога между**:
|
||
|
||
* “вопрос уже можно исполнять”
|
||
* и
|
||
* “надо тормознуть и спросить уточнение”
|
||
|
||
Сейчас система слишком часто тормозит.
|
||
Нужно сделать её **осторожной, но рабочей**, а не просто осторожной.
|
||
|
||
---
|
||
|
||
Если хочешь, я следующим сообщением дам ещё **ультра-короткий job prompt для Codex** на этот этап.
|