Шаблоны для работы с клиентом

Функциональность

• GET /health возвращает HTTP 200.
• GET /ready подтверждает Ollama и RAG-индекс.
• Эталонный evaluation-набор согласован с клиентом.
• Достигнут согласованный pass rate: ___%.
• Каждый RAG-ответ содержит разрешённый источник или честный отказ.

Безопасность

• Сервис слушает только согласованный сетевой интерфейс.
• Рабочие эндпоинты защищены API-ключом, если доступны не только локально.
• Секреты отсутствуют в Git и образе контейнера.
• Инструменты ограничены allowlist и проверяемыми аргументами.
• Внешние и изменяющие действия требуют подтверждения человека.

Эксплуатация

• Инструкция запуска проверена на компьютере клиента.
• Создана и проверена резервная копия.
• Восстановление выполнено в отдельную пустую папку.
• Назначены ответственные за документы, доступ и обновления.
• Зафиксирована процедура rollback.

Дата: __________ Клиент: __________ Исполнитель: __________

Анкета клиента

Задача

1. Какую одну задачу должен решать агент?
2. Кто будет им пользоваться?
3. Как выглядит правильный результат?
4. Какие ошибки недопустимы?

Данные

1. Какие документы и системы разрешено читать?
2. Есть ли персональные, коммерческие или другие защищаемые данные?
3. Где данные должны храниться и как долго?
4. Кто отвечает за актуальность исходных документов?

Действия и доступ

1. Какие инструменты разрешены?
2. Какие действия требуют подтверждения человека?
3. Должен ли сервис быть доступен за пределами одного компьютера?
4. Кто выдаёт и отзывает доступ?

Приёмка и эксплуатация

1. Какие контрольные вопросы войдут в evaluation-набор?
2. Какой минимальный pass rate принимается?
3. Кто следит за журналом ошибок и резервными копиями?
4. Какой срок поддержки нужен после передачи?

Чек-лист передачи

• Репозиторий или архив исходников передан клиенту.
• Версии Ollama, моделей, Docker и Python записаны.
• Модели скачаны на целевой компьютер.
• .env создан локально и не добавлен в Git.
• RAG-индекс построен из согласованных документов.
• Все тесты и evaluation пройдены.
• Клиент умеет запустить, проверить и остановить сервис.
• Клиент знает, где находятся логи и приватные данные.
• Создан backup; восстановление проверено отдельно.
• Ограничения и известные ошибки объяснены.
• Срок и канал поддержки согласованы.

Инцидент и rollback

Когда остановить сервис

• ответы систематически не соответствуют документам;
• обнаружена утечка секрета или приватных данных;
• агент вызывает неожиданные инструменты;
• повреждён индекс или база памяти;
• обновление ухудшило evaluation ниже согласованного порога.

Немедленные действия

1. Остановить контейнер: docker compose down.
2. Не удалять логи и повреждённые данные до анализа.
3. Отозвать скомпрометированный API-ключ и создать новый вне Git.
4. Зафиксировать время, симптомы и последние изменения.

Rollback кода

1. Найти последний принятый Git-коммит.
2. Создать отдельную ветку или рабочую копию на этом коммите.
3. Собрать образ и выполнить тесты/evaluation.
4. Переключить сервис только после успешной проверки.

Не используйте git reset --hard на единственной рабочей копии с несохранёнными данными.

Восстановление данных

Восстановление выполняется в новую пустую папку:

uv run python -m agent_lab.backup restore BACKUP.zip \
  --target data/private-restored

После проверки файлов путь RAG_DB_PATH меняется на восстановленную базу. Исходная база не перезаписывается автоматически.