Практические советы: ваш проект RAG не должен представлять собой один огромный файл на Python.

В следующих заметках описывается практический подход к решению проблемы «Ваш проект RAG не должен представлять собой один огромный файл на Python». Основное внимание уделяется контрактам, проверкам и местам для вставки кода, а не мотивирующим формулировкам. При работе над обзором сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и последствия частичной неудачи. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные расходы при переходе от демо-версии к общедоступным средам.

Основная идея: разделить конвейер обработки данных от самого приложения

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

Чистая структура проекта RAG

Чистая структура проекта RAG работает наилучшим образом, когда рассматривается как измеримая основа. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Закрепите интерпретатор и файл блокировки зависимостей до того, как начнете использовать циклы. Различия между ноутбуком и средой CI являются наиболее распространенной причиной незаметных сбоев в демонстрациях API.

rag-project/
|-- README.md
|-- requirements.txt
|-- .env
|-- .gitignore
|-- config.yaml
|-- main.py
|-- src/
|   |-- ingestion/
|   |   |-- __init__.py
|   |   `-- loader.py
|   |-- chunking/
|   |   |-- __init__.py
|   |   `-- chunker.py
|   |-- embeddings/
|   |   |-- __init__.py
|   |   `-- embedder.py
|   |-- vectordb/
|   |   |-- __init__.py
|   |   `-- vector_store.py
|   |-- retrieval/
|   |   |-- __init__.py
|   |   `-- retriever.py
|   |-- prompts/
|   |   |-- __init__.py
|   |   `-- prompt_templates.py
|   |-- llm/
|   |   |-- __init__.py
|   |   `-- llm_client.py
|   |-- api/
|   |   |-- __init__.py
|   |   `-- routes.py
|   `-- utils/
|       |-- __init__.py
|       `-- helpers.py
|-- tests/
|   `-- test_app.py
`-- logs/
    `-- app.log

README.md: Объясните проект до того, как люди начнут задавать вопросы

README.md: Объясните проект до того, как люди начнут задавать вопросы работает наилучшим образом, если рассматриваться как объект с измеримыми показателями. Зафиксируйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию до расширения объёма проекта. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг срабатывает некорректно, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Заблокируйте версию интерпретатора и файл с информацией о зависимостях до того, как начнёте объяснять работу циклов. Различия в настройках между ноутбуком и средой CI являются наиболее распространённой причиной скрытых сбоев в демонстрациях API. README.md: Объясните проект до того, как люди начнут задавать вопросы работает наилучшим образом, если рассматриваться как объект с измеримыми показателями. Зафиксируйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию до расширения объёма проекта. Записывайте время выполнения и стоимость токенов или запросов вместе с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные расходы при переходе от демо-версии к совместным средам.

requirements.txt: Поддержание видимости зависимостей

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

fastapi
uvicorn
python-dotenv
pydantic
langchain
chromadb
sentence-transformers
openai
pypdf

pip install -r requirements.txt

.env: Хранение секретов локально

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

OPENAI_API_KEY=your_key_here
VECTOR_DB_URL=your_vector_db_url

.env
logs/
__pycache__/
*.pyc

config.yaml: Хранение настроек в одном месте

Для config.yaml: Хранение настроек в одном месте необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой обработки данных. Разделяйте процесс создания клиента и цикл обработки сообщений, чтобы можно было заменять поставщики без переписывания машины состояний обмена сообщениями. Для config.yaml: Хранение настроек в одном месте необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при

Путь изменяется с демо-среды на общедоступные среды.

chunking:
  chunk_size: 800
  chunk_overlap: 120

retrieval:
  top_k: 5

models:
  embedding_model: text-embedding-3-small
  llm_model: gpt-4.1-mini

vector_db:
  provider: chromadb
  collection_name: company_docs

ingestion/: Загрузка данных из разных источников

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

chunking/: Разделение документов на полезные части

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

embeddings/: Преобразование текста в векторы

При работе над embeddings/: Convert Text Into Vectors сначала запишите спецификацию: необходимые входные данные, сигнал о успешном выполнении и что происходит при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули вместо обширных скриптов. Когда какой-то шаг терпит неудачу, ошибка должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Записывайте идентификатор запроса, идентификатор модели и время задержки при каждом вызове. Без такой отслеживаемости периодические ошибки поставщика кажутся багами приложения. При работе над embeddings/: Convert Text Into Vectors сначала запишите спецификацию: необходимые входные данные, сигнал о успешном выполнении и что происходит при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-режима к общей среде.

vectordb/: Хранение и управление эмбеддингами работает наилучшим образом, когда рассматривается как измеримая поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Заблокируйте интерпретатор и файл с информацией о зависимостях перед тем, как использовать циклы. Различия между ноутбуком и средой CI являются наиболее распространенной причиной скрытых сбоев в демонстрациях API.

retrieval/: Поиск подходящего контекста

retrieval/: Поиск подходящего контекста работает наилучшим образом, когда рассматривается как измеримая величина. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Заблокируйте интерпретатор и файлы зависимостей до того, как начнете использовать циклы. Различия в работе на ноутбуке и в среде CI являются наиболее распространенной причиной незаметных сбоев в демонстрациях API.

prompts/: Избегайте включения шаблонов запросов в логику приложения

prompts/: Не включайте шаблоны запросов в логику приложения — этот принцип наилучшим образом работает, если рассматривать его как измеримую составляющую. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Закрепите интерпретатор и файл с информацией о зависимостях до того, как начнете использовать циклы. Различия в работе приложения на ноутбуке и в среде CI являются наиболее распространенной причиной скрытых сбоев в демонстрациях API. prompts/: Не включайте шаблоны запросов в логику приложения — этот принцип наилучшим образом работает, если рассматривать его как измеримую составляющую. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте время выполнения операций, а также стоимость использования токенов или запросов вместе с функциональными результатами. Отслеживание затрат на раннем этапе помогает избежать неожиданных расходов при переходе от демо-версии к общей среде разработки

You are a helpful assistant answering questions using the provided context.

Use only the context below. If the answer is not in the context, say you do not know.

Context:
{context}

Question:
{question}

Answer:

llm/: Централизованные вызовы моделей

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

api/: Открытие доступа к системе RAG

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

utils/: Общие вспомогательные функции

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

среды.

tests/: Проверка работы каждой части

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

logs/: Понимание произошедшего

При работе над разделом logs/: Understand What Happened сначала запишите спецификацию интерфейса: необходимые параметры входных данных, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки со стороны оператора и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки. Записывайте идентификатор запроса, идентификатор модели и время задержки при каждом вызове. Без такой записи периодические ошибки поставщика будут выглядеть как баги приложения.

main.py: Сохраняйте простоту точки входа

При работе над main.py: Keep the Entry Point Simple сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули большим скриптам. Если какой-то шаг не сработает, ошибка должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Записывайте идентификатор запроса, идентификатор модели и время задержки при каждом вызове. Без такой отчетности периодические ошибки поставщика могут выглядеть как баги приложения. При работе над main.py: Keep the Entry Point Simple сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение затрат с самого начала предотвращает неожиданные расходы при переходе от демо-режима к общей среде.

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

Простое правило для начинающих

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

Заключительные мысли

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

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

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

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

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

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

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

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

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

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