Практичні поради: Ваш проєкт 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/: Завантаження даних з різних джерел спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Фіксуйте ідентифікатор запиту, ідентифікатор моделі та час виконання кожного виклику. Без цих записів періодичні помилки постачальника виглядають як баги додатку.

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/: Shared Helpers необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних. Розділіть процес створення клієнта від циклу обробки повідомлень, щоб можна було замінювати постачальників без переписування машини станів розмови. Для utils/: Shared Helpers необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити разом із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам під час переходу від демо-режиму до спільного використання.

середовищ.

tests/: Перевірте роботу кожної частини

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

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: не включайте ключі постачальника до репозиторію, встановіть ліміт токенів на сеанс та зберігайте записи поруч із фіксами для оцінки, щоб подальша заміна моделей залишалася порівнянною.