Оценка документации для ИИ

Это руководство определяет версионированный контракт оценки использования самодостаточной документации FOnline Engine поисковыми системами и AI- ассистентами. Исходный набор находится в ai-evaluation.json, а текущий сгенерированный результат — в ai-evaluation-report.json.

Состояние контракта

Проверяемый gate доказывает детерминированный поиск и актуальность свидетельств для ответа, но сам по себе не доказывает успешность выполнения задач моделью. После доработки источников и harness два изолированных семейства моделей были повторно запущены и независимо проверены 2026-08-04. Оба выбрали все владеющие документы, достигли production-порога успешности для каждого семейства и не создали неподтверждённых safety-, migration-, compatibility- или release-заявлений. AI quality exit gate закрыт.

Текущий источник содержит 28 задач, 67 retrieval checks и 97 answer checks. Порог статического retrieval равен 100 процентам: каждый проверяемый запрос должен найти ожидаемого владельца не ниже объявленного максимального ранга.

Оценка использует только файлы из самодостаточного checkout Engine. Last Frontier, TLA, приватные репозитории, история чата и неуказанные соглашения проекта не допускаются как authoritative-источники ответа.

Категории оценки

Источник содержит не менее двух задач в каждой обязательной категории:

Сохраняйте категории стабильными, чтобы результаты оставались сопоставимыми. Добавляйте новую категорию только вместе с ревизией схемы, владеющей страницей документации и явным объяснением, почему существующие категории не представляют задачу.

Схема задачи

Каждая задача записывает:

• стабильный идентификатор задачи, категорию и вопрос в стиле пользователя;
• один основной владеющий документ и необязательные вспомогательные документы;
• не менее двух retrieval queries с ожидаемыми идентификаторами документов и максимальным рангом;
• не менее двух answer checks с актуальным идентификатором документа, якорем заголовка и терминами исходника, которые всё ещё должны существовать;
• запрещённые допущения, которые reviewer обязан отклонить, даже если остальная часть ответа выглядит правдоподобно.

Основные документы должны быть публичными, актуальными и направленными аудитории ai-agent. Вспомогательные документы также должны быть публичными и актуальными. Вопросы и описания answer checks не могут зависеть от названного embedding-проекта.

Термины ответа являются контрольными признаками свидетельств, а не заменой семантического ревью. Они доказывают, что записанные источник и раздел всё ещё содержат понятия, ожидаемые rubric, но не доказывают, что сгенерированный ответ использовал их правильно.

Запуск детерминированной проверки

Сначала сгенерируйте site search, поскольку оценка использует тот же компактный индекс, что и браузер:

python BuildTools/docs_site.py --write
python BuildTools/docs_ai_eval.py --write
python BuildTools/docs_ai_eval.py --check
python BuildTools/tests/test_docs_ai_eval.py

--write всегда записывает диагностический отчёт до возврата ошибки. Поэтому неудачные ранги, верхние идентификаторы документов, устаревшие якоря и отсутствующие термины остаются доступными для анализа. Затем --check требует побайтно идентичный committed output и долю успешного retrieval не ниже порогового значения из исходника.

Генератор сайта удаляет слишком частые body terms ради компактности индекса, кроме терминов, обозначающих заголовок или ID документа. Для них сохраняется полный список postings, включая совпадения в тексте: точный запрос Tools или Source не должен сводиться к редким составным словам вроде ToolsDir. Это правило генерации индекса; ранжирование браузера и Python продолжает использовать один сгенерированный индекс без отдельных исключений.

Текущий контракт ранжирования в браузере и Python:

1. токенизирует технические идентификаторы без перевода и стемминга;
2. сначала использует точные термины, затем ограниченные prefix matches;
3. учитывает каждый токен запроса не более одного раза для документа;
4. игнорирует токены запроса, отсутствующие в компактном индексе;
5. требует не менее 60 процентов эффективных токенов запроса;
6. ранжирует по числу совпавших токенов, взвешенному score документа и заголовку.

Реализация Python в docs_site.search_documents и браузерная реализация в assets/js/docs.js должны меняться вместе. Фокусные тесты закрепляют длинные запросы, отсутствующие токены, prefixes и маркеры статического layout.

Запуск оценки семейств моделей

Используйте сгенерированный отчёт только после зелёной детерминированной проверки. Для каждого семейства моделей:

1. начните с чистого самодостаточного checkout Engine на source_ref отчёта;
2. предоставьте только llms.txt, docs-manifest.json, чистые Markdown- endpoints и выбранные через эти точки входа машинно-читаемые модели;
3. выполните каждую задачу без проектных репозиториев и контекста предыдущей задачи;
4. сохраните точные model/provider/version, system prompt, результаты retrieval, выбранные идентификаторы документов, ответ, latency и token usage;
5. оцените каждый answer check как pass, fail или not-observable;
6. оцените каждое запрещённое допущение независимо;
7. запишите личность reviewer и примечания для safety-, migration-, compatibility- и support-заявлений;
8. сохраните необработанный запуск в Workspace/ai-evaluation/<run-id>.json и добавьте датированный совокупный результат в verification report.

Запустите не менее двух существенно различных семейств моделей. Второй alias, размер или deployment того же базового семейства не является независимым свидетельством. Не помещайте credentials провайдера или приватные prompts в репозиторий либо отчёт.

Необязательный локальный reference harness обращается к Ollama и не является CI- или сетевой зависимостью публичной документации. Он потоково получает ответ в пределах одного deadline, фиксирует temperature и seed равными нулю, записывает точный digest модели, версию провайдера, prompts, хеши исходников и входов, документы-кандидаты, необработанные попытки ответа, latency и число токенов, а после ошибки выгружает модель. При --resume завершённые совместимые задачи сохраняются, а прерванный запуск продолжается. Одна повторная попытка после недопустимого ответа сохраняет неудачный ответ и отключает thinking модели. После получения допустимого JSON один semantic-completion repair может выполниться только при объективном дефекте: отсутствии обязательного evidence token, недопустимом выбранном document ID, отсутствии primary owner или нуле допустимых citations. Все попытки сохраняются, скрытые рассуждения удаляются, а семантическое ревью остаётся независимым. Запускайте одно семейство с явным сохраняемым профилем:

python BuildTools/docs_ai_model_eval.py --model gpt-oss:20b --family gpt-oss --max-candidates 6 --max-document-bytes 24000 --max-context-bytes 60000 --num-context 32768 --num-predict 6000 --timeout 300 --output Workspace/ai-evaluation/2026-08-04-gpt-oss-20b-v2.json
python BuildTools/docs_ai_model_eval.py --model gpt-oss:20b --family gpt-oss --max-candidates 6 --max-document-bytes 24000 --max-context-bytes 60000 --num-context 32768 --num-predict 6000 --timeout 300 --resume --output Workspace/ai-evaluation/2026-08-04-gpt-oss-20b-v2.json

Harness передаёт вопрос и найденный корпус, но скрывает rubric ответа. Его наблюдения входа должны доказать, что каждый скрытый критерий действительно был доступен, прежде чем пропуск можно засчитать против модели. Для каждого кандидата с начальным decision-, route-, fast-convention- или purpose-summary harness повторяет этот дословный блок и столько query-relevant-разделов, сколько помещается в лимит quick evidence 14 000 байт на документ. Это слой представления retrieval, а не придуманное harness свидетельство ответа: raw prompt сохраняет document IDs, paths, точный текст и hashes, а скрытые answer checks не попадают в prompt.

--self-review является только диагностическим вторым проходом. Smoke-прогон двух задач не устранил существенно пропуски baseline от 2026-08-04. Owner-only excerpts также сократили ответы, но не закрыли составные критерии. Сохранённая стратегия quick evidence заметно улучшила пятизадачный maintainer smoke, особенно для AngelScript и layered release evidence, однако оценка smoke не заменяет полный прогон и независимое ревью.

Создайте компактное ревью, заполните его напрямую либо примените независимо полученное структурированное предложение, затем финализируйте и проверьте:

python BuildTools/docs_ai_model_review.py --write-template --run Workspace/ai-evaluation/2026-08-04-gpt-oss-20b-v2.json --reviewer REVIEWER_ID --output Docs/_meta/ai-evaluation/2026-08-04-gpt-oss-20b.review.json
python BuildTools/docs_ai_model_review.py --apply-suggestion --suggestion Workspace/ai-evaluation/2026-08-04-gpt-oss-20b.review-suggestion.json --output Docs/_meta/ai-evaluation/2026-08-04-gpt-oss-20b.review.json
python BuildTools/docs_ai_model_review.py --finalize --output Docs/_meta/ai-evaluation/2026-08-04-gpt-oss-20b.review.json
python BuildTools/docs_ai_model_review.py --check --require-run --output Docs/_meta/ai-evaluation/2026-08-04-gpt-oss-20b.review.json

Необработанные отчёты остаются в игнорируемом Workspace/; версионируйте только компактное внутреннее ревью. Обычный --check проверяет компактное свидетельство в checkout без raw-прогона. --require-run дополнительно требует raw-файл, проверяет его SHA-256 и сравнивает записанные модель, провайдера, параметры, источник, хеши входов и время завершения.

Текущий проверенный baseline

Оба финальных прогона 2026-08-04 использовали Ollama 0.32.5, явный профиль выше, одинаковые входы документации, SHA-256 harness 5fdd971f46898f789817c1f87531af862ec4ccd3b38e30f6a9ce987915f3aa09 и независимую семантическую проверку каждого ответа.

Сохранённый raw-прогон Qwen находится в Workspace/ai-evaluation/2026-08-04-qwen3.5-9b-v12-final.json, его SHA-256: 30acb42ee573e85176cbf3f58cbd34d922b21b4742b984713fa04f58e07ff466; компактное ревью находится в Docs/_meta/ai-evaluation/2026-08-04-qwen3.5-9b-v12-final.review.json, его SHA-256: c579f6d400f575b191c2a8f3c2ffad97848527046010465ba16a04f09fcc814d. Сохранённый raw-прогон GPT-OSS находится в Workspace/ai-evaluation/2026-08-04-gpt-oss-20b-v13-final.json, его SHA-256: 49b2706895a13c477e04669ea89df0dd82a3407ba3ab4af49c3d8de985611291; компактное ревью находится в Docs/_meta/ai-evaluation/2026-08-04-gpt-oss-20b-v13-final.review.json, его SHA-256: e58b5cad481fa0d9854d8f561fc30d7dce949945b3bb8c405fd9a8137983d8ec.

Общие хеши входов: dd3e5f83d17b2b5aafcf787f374446929f8d412db68ed6a193aaed0479d2e310 для Docs/ai-evaluation.json, b264cb916ab4690829502de18a9ca7328e252fd3adc587dec3362e1403bd4499 для Docs/generated/ai-evaluation-report.json, f14577a60f6d7e074bdbe24b890b927de8ed9797ddcc5f6e621353cc19865d30 для docs-manifest.json и 471a86233febdf79dd931d16ef077d854839266852682f500a2a0ee533c4407f для llms.txt.

Qwen прошёл все задачи. GPT-OSS провалил задачу focused viewer, потому что предписал Mapper screenshot API, явно запрещённые переданной границей свидетельств, и задачу полного обновления Engine, потому что повторил названия стадий без применимой процедуры защиты сохранённого состояния и валидации. Ни один из этих провалов не является неподтверждённым safety-, migration-, compatibility- или release-заявлением. Поэтому активная квалификация двух семейств превышает неизменённый порог 90 процентов. Предыдущие компактные ревью остаются неизменяемыми историческими свидетельствами и не переписываются как текущие результаты.

Оценивание

Показывайте эти измерения отдельно:

• выбор владеющего документа;
• успешность retrieval на объявленном ранге;
• покрытие answer checks;
• неподтверждённые или project-specific допущения;
• выбор version/source-ref;
• итоговый успех задачи.

Для answer check статус pass означает, что ответ семантически выполняет проверку. Для запрещённого допущения pass означает, что ответ не сделал это запрещённое утверждение. not-observable означает, что изолированный вход не содержал достаточно свидетельств для оценки критерия, поэтому задача не может считаться успешной.

Production-цель — не менее 90 процентов итогового успеха задач для каждого проверенного семейства при нуле неподтверждённых safety-, migration-, compatibility- и release-заявлений. Высокий совокупный score не может отменить release-blocking ошибку в одной из этих областей.

Статический retrieval намеренно строже production-цели для семейств моделей: каждый проверяемый запрос должен оставаться в пределах объявленного ранга. Снижение 100-процентного порога источника требует проверенного объяснения в плане и verification report, а не простой перегенерации результата.

Реакция на регрессию

До изменения весов проверьте top_document_ids задачи:

• Если другой результат является настоящим владельцем, исправьте владение задачей и навигацию.
• Если владельцу не хватает пользовательской лексики, улучшите его название, заголовки, prerequisites или терминологию без дублирования другой страницы.
• Если несколько страниц заявляют одно поведение, выберите одного владельца, а остальные превратите в ограниченные по области маршруты.
• Если запрос содержит только неподтверждённые допущения, измените задачу, а не обучайте поисковый индекс приватному термину проекта.
• Если свидетельство переместилось, осознанно обновите стабильный заголовок и сохраните любой уже зависящий от него публичный маршрут.

Никогда не добавляйте нерелевантные списки ключевых слов, скрытый текст или искусственные повторы ради зелёного ранга. Улучшение retrieval должно также помогать человеку выбирать правильную страницу.

Триггеры сопровождения

Перегенерируйте и проверьте оценку, когда:

• меняется идентификатор, название, путь, аудитория или заголовок документа- владельца задачи;
• меняется токенизация navigation/search, фильтрация по document frequency или ранжирование;
• меняется source_ref или политика версий документации;
• новый публичный workflow вытесняет существующую владеющую страницу;
• запуск модели обнаруживает неоднозначность, отсутствующий prerequisite или неподтверждённое допущение.

Запускайте docs_site.py, затем docs_ai_eval.py, затем docs_ai_delivery.py. AI delivery публикует evaluation report как машинно- читаемый справочник; validator отрендеренного сайта проверяет, что побайтно идентичный JSON endpoint пережил Jekyll.

Ограничения

Детерминированный gate не оценивает качество прозы, reasoning, выполнение команд, компиляцию кода, визуальное понимание или поведение провайдера. Он также не способен доказать, что модель игнорировала информацию вне предоставленного самодостаточного корпуса, если run harness не записывает и не изолирует входы.

Исследования удобства для людей, семантические compile/bake/execute- свидетельства для примеров, browser accessibility, паритет русского retrieval и мониторинг живого production endpoint остаются отдельными требованиями. Синтаксис fences и покрытие шаблонов принадлежат странице Проверка фрагментов документации.