Практычныя прытамулкі: ваш проект 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/: Разбіўка дакументаў на корыстныя часткі, спачатку запішыце контракт: неабходныя даны, сигнал успеху і тое, што відбываецца у разы частковага невдачы. Такі список пераканальвае ў тым, што пазнейшыя змены коду будуць чыстымі. Запісвайце адночасна шлях успеху і шлях відновлення. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў є частью продукту, а не пазнейшым допрацоўкам. Запісвайце ID запиту, ID моделі і час адпаведзення праз кожны вызов. Без такога сляда періодычныя проблэмы прадавца выглядаюць як багі прыкладнага програмнага забезпечэння.

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 неабяжна прадзефінавацыя вхідных дадзеных, адпраўніка крока і крэтарыяў выходу пры змены коду. Аператары должны магчымае перзапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Запісвайце час выконання і кост токенаў аб запытаў разам з функцыйнальнымі рэзултатамі. Відразы костаў з самага пачатку запобегае неспакойным рахункам, калі траекторыя перайходзіць з дэмаверсіі на спакульнае выкарыстоўванне.

< p>Сераўны.

< h3>tests/: Падтвердзіце, што кожная частка працюе < p>Калі працуеце над < strong>tests/: Падтвердзіце, што кожная частка працюе, спачатку запішыце умовы викорыстання: неабяжныя данні, сигнал успеху і тое, што выходзіць на падчасныя аберанцыі. Такі список дапамагае залічваць змяны ў кодзе чыста. Зберагайце настройкі паза кодам прыемліка. Файлы сераўна, храненні секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куда аператары можаць адбавіць аудыт без неабяжнага чытання всіх элементаў. Запішывайце ідэнтыфікатор запиту, ідэнтыфікатор моделі і час адпаведзення за кожны вызов. Без такога лісту прычыны аберанцый інтэрмітентных прадаўцоў выглядаюць як багі прыемліка. < h3>logs/: З’ясавайце, што сталося

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

main.py: Залічвайце вхідную точку простаю

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

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

Простая правіла для пачаткунаваў

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

Заключныя меркі

Заключныя заўважэнні работаюць наякша, калі іх спрыяваць як мерыемую паверхню. Зберагчыце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштаб. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, неудача должна вказваць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг задач. Зафіксавайце інтэрпретара і файл з правіламі залежнасцяў пры тым, як выучаеце цикл. Разніця ў роботе на ноутбуку і у сервісах CI — гэта самая частая непазначальная проблема пад час дэманстрацый API. Заключныя заўважэнні работаюць наякша, калі іх спрыяваць як мерыемую паверхню. Зберагчыце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштаб. Запісвайце часы выконання і косты токеноў або запытак разам з функцыйнальнымі рэзултатамі. Відразувыя даны пра косты запобегаюць неспакоўным рахункам, калі процес пераходзіць з дэмы на спяльныя среды.

Чек-ліст для эксплуатацыі

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

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

Раздзеліце стварэнне кліента ад циклу паведамленняў, каб было можна змяніць прадаўцоў без перапісвання машыны стану дыялогу.

Замерайце рэгрэт на фіксаваным наборы пытанняў прыштоя да налагоджэння запрошэнняў. Частае змяненне запрошэнняў рэдка калі выправляе слабыя аспекты адзысквання інформаціі.

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

Запісвайце адно часовы лянцюг успеху і лянцюг вярнення. Прабавы, людзкія контраліны і обработка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам.

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

Прыметкі для 34fcf7ceacae: не кладзіце ключы прадаўцоў у репазітарый, задаце ліміт токена на кожную сесыю і зберагачыце транскрыпты празаўседліва з фіксатамі для ацэнкі, каб пасляднія змены моделей заставаліся пораўнанневымі.