Практические заметки: контракты на быструю зарядку данных с использованием агента LangGraph RAG

Используйте это как переработанную версию идей из статьи «Data Contract Agent powered by LangGraph RAG», ориентированную на операторов: четкие этапы, упорядоченные блоки кода и записи о восстановлении, сохраняющиеся при передаче задач. Обзор работает лучше всего, когда рассматривается как измеримая структура. Сначала соберите один идеальный пример работы, один случай сбоя и записи о возврате к предыдущему состоянию, прежде чем расширять объем работы. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счета при переходе от демо-версии к общим средам.

LangChain

Для LangChain необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Указывайте те участки текста, которые фактически легли в основу ответа. Без цитат операторы не смогут отличить галлюцинации от пробелов в индексации.

Основные компоненты

Для основных компонентов необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Необходимо одновременно задокументировать успешный сценарий выполнения и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Указывайте конкретные фрагменты текста, на которых основан ответ. Без цитат операторы не смогут отличить галлюцинации от пробелов в индексации.

LangGraph

Для LangGraph необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной областью ответственности, а не с запутанной структурой обработки. Указывайте те части текста, которые легли в основу ответа. Без цитат операторы не смогут отличить галлюцинации от проблем с индексацией. Для LangGraph необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее помогает избежать неожиданных расходов при переходе с демо-среды в общедоступные среды.

Настройка

При работе над настройками сначала запишите условия контракта: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Измеряйте уровень воспроизведения ответов на фиксированном наборе вопросов перед настройкой подсказок. Изменение подсказок редко помогает улучшить качество поиска.

Узел 2 retrieve_contracts (поиск)

При работе над функцией Node 2 retrieve_contracts (поиск контрактов) сначала запишите информацию о контракте: необходимые входные данные, сигнал об успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Измеряйте степень воспроизведения результатов на фиксированном наборе вопросов перед настройкой подсказок. Частая смена подсказок редко помогает улучшить качество поиска.

Node 3 match_contract (выбор контракта)

При работе над модулем Node 3 match_contract (функция Выбор) сначала запишите условия работы контракта: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Оцените уровень воспроизводимости на фиксированном наборе вопросов перед настройкой подсказок. Частая смена подсказок редко помогает улучшить качество поиска. При работе над модулем Node 3 match_contract (функция Выбор) сначала запишите условия работы контракта: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость в использовании токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Почему RAG

RAG работает наилучшим образом, когда рассматривается как измеримая структура. Соберите один идеальный пример обработки данных, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Разделяйте политику разбиения данных на части и политику поиска. Изменение одной из них не должно приводить к переписыванию другой при изменении показателей качества.

Установка

Установка работает наилучшим образом, когда её рассматривают как измеримую поверхность. Соберите один пример успешной работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно путь успешной работы и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Разделяйте политику разбиения на части и политику извлечения данных. Изменение одной из них не должно приводить к переписыванию другой при изменении показателей качества.

git clone https://github.com/ajithshetty/data-contract-validator-agent.git

cp .env.example .env
# Set ANTHROPIC_API_KEY in .env

docker compose up qdrant -d

python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m backend.main

http://localhost:8000
http://localhost:8000/docs (Swagger)

curl -X POST http://localhost:8000/api/ingest \
-H "Content-Type: application/json" \
-d '{"contracts_dir": "./contracts/sample"}'

cd frontend
npm install && npm run dev

Быстрое начало работы с Docker

Быстрое начало работы с Docker будет наиболее эффективным, если рассматривать его как объект с измеримыми показателями. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Разделяйте политику разбиения на части и политику извлечения данных. Изменение одной из них не должно вынуждать переписывать другую при изменении показателей качества.

cp .env.example .env # set ANTHROPIC_API_KEY
docker compose up - build
cd frontend && npm install && npm run dev

Быстрое начало работы с Docker будет наиболее эффективным, если рассматривать его как объект с измеримыми показателями. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте время выполнения операций, а также стоимость токенов или запросов вместе с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные расходы при переходе от демо-среды к общедоступным средам.

Демо-версия

Для демонстрации определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Укажите те фрагменты текста, которые на самом деле легли в основу ответа. Без цитат операторы не смогут отличить галлюцинации от пробелов в индексации.

curl -X POST http://localhost:8000/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "raw_schema": "{\"identifier\": \"warehouse.fact_orders\", \"fields\": [{\"name\": \"order_id\", \"type\": \"bigint\", \"optional\": false}]}",
    "schema_type": "iceberg"
  }'

Краткое резюме

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

Справка

Для справки: определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной областью ответственности, а не с запутанной цепочкой операций. Указывайте те части текста, которые легли в основу ответа; без цитат операторы не смогут отличить вымысел от проблем с индексацией.

Чек-лист операций

При работе с чек-листом операций сначала запишите условия выполнения: необходимые входные данные, сигнал о успехе и действия при частичном сбое. Этот чек-лист поможет сохранять честность последующих изменений в коде.

Рассматривайте этот этап как договор между входными данными и проверенными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи.

Оцените уровень воспроизведения ответов на фиксированном наборе вопросов перед настройкой подсказок. Частая смена подсказок редко помогает улучшить слабую систему поиска информации.

Сохраняйте структуру графа простой и однородной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и нарушают целостность данных после прерываний.

При наличии бюджета добавьте тесты для проверки критического пути в процессе интеграционного тестирования с использованием фикстур, а не реальных платных API.

Документируйте как успешный, так и восстановительный пути работы системы. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

Перед внедрением новой структуры сохраните текущие версии, сделайте запись эталонного варианта работы для критического пути и уточните шаги возврата к предыдущей версии. В совместных средах необходимо использовать ограничения на частоту запросов, проверки принадлежности ресурсов и четкого ответственного за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.

Примечание к пакету 84f19eec2edd: не храните ключи поставщиков в репозитории, установите лимит токенов на сессию и сохраняйте транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.