Памагчык з дакументамі RAG з тэставанымі сэрвісамі і чатом на Next.js

Асістэнт для дакументаў на базе RAG з падзеямі HTTP аддзеленымі ад сэрвісаў на чыстай Python, дакументы індэксаваныя з цітаванымі фрагментамі, FastAPI як аднойчынная база, а таксама чат з роздзельнымі панелямі на базе Next.js.

Выдавец: REACTAPP.TOPДададзена на сайт 26 вер 202618 хв чытання4200 слоў

Крыніцы: Building a RAG-Powered Document Assistant from Scratch

Дапаможнік з документацыяй, які апіляецца на своіяы істочнікі, ўжоўвае тэхналогію RAG, а не ёсць проста версія чат-бота. У гэтым варыянце маршруты HTTP аддзеляюцца ад сэрвісаў на Python, зберагаюцься эмбедынгі для запрашэння даных, а інтэрфейс чату на Next.js прадстаўляецца з роздзеламі для транскрыпцыі і цітатаў.

Цялі

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

Структура бэкенду

Маршруты API апрацоўваюць толькі HTTP-запыткі; сэрвісы адпавядаюць за прыему даных, ўтворэнне эмбедынгаў, запрашэння і генераванне рэзультатаў. Такое раздзелення дазволяе практыкуваць тэсты ранжыравання даных за дапамогою pytest без вікорыстоўвання ASGI.

Структура фронтэнду

Next.js у поўнасці з Tailwind: чат у роздзелах, тэмы «тэмная»/«яскравая», якія выкарыстоўваюць аднаковы кліент API, а таксама элементы для цітатаў, якія веду на конкрэтыя фрагменты дакументаў.

from pypdf import PdfReader, errors
from fastapi import HTTPException, UploadFile

@router.post("/ingest")
async def ingest_pdf(file: UploadFile, settings: Settings = Depends(get_settings)):
    if file.content_type != "application/pdf":
        raise HTTPException(400, "Only PDF files accepted")
    contents = await file.read()
    try:
        reader = PdfReader(BytesIO(contents))
    except errors.DocumentLoadError:
        # If PDF is an image-scanned file, pypdf may fail here
        raise HTTPException(400, "Failed to load PDF (maybe it's scanned/image-only)")
    text = ""
    for page in reader.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"
    if not text.strip():
        raise HTTPException(400, "PDF contained no extractable text")
    # Now text holds the raw content to index...

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

import tiktoken

ENCODING = tiktoken.get_encoding("cl100k_base")
CHUNK_SIZE = 500
CHUNK_OVERLAP = 50

def chunk_text(text: str) -> list[str]:
    tokens = ENCODING.encode(text)
    chunks = []
    for i in range(0, len(tokens), CHUNK_SIZE - CHUNK_OVERLAP):
        chunk_tokens = tokens[i : i + CHUNK_SIZE]
        # Decode back to string; words may split, but overlap handles continuity
        chunks.append(ENCODING.decode(chunk_tokens))
        if i + CHUNK_SIZE >= len(tokens):
            break
    return chunks

Інтэгруйце гэты крок прыяўшы да розгортання інтэрфейса; багі, зв’язаныя з выкарыстоўванням дадзеных, легча знайсці за дапамогою танкаго кліента.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
# (In actual code, we'd use a singleton or lru_cache to avoid re-loading)

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

chunk_vectors = model.encode(chunks, show_progress_bar=False)

import httpx

HF_API_URL = "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2"

async def embed_texts(texts: list[str], api_key: str) -> list[list[float]]:
    headers = {"Authorization": f"Bearer {api_key}"}
    async with httpx.AsyncClient() as client:
        response = await client.post(
            HF_API_URL,
            headers=headers,
            json={"inputs": texts, "options": {"wait_for_model": True}}
        )
        response.raise_for_status()
        return response.json()

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, PointStruct

qdrant = QdrantClient(url=settings.QDRANT_URL, api_key=settings.QDRANT_API_KEY)
# Recreate the collection for a clean slate (or check if exists)
qdrant.recreate_collection(
    collection_name="documents",
    vector_size=384,
    distance=Distance.COSINE
)

from qdrant_client.models import Filter, FieldCondition, MatchValue

qdrant.delete_points(
    collection_name="documents",
    filter=Filter(must=[FieldCondition(key="source", match=MatchValue(value=source_id))])
)

from uuid import uuid4

points = []
for chunk_text, vector in zip(chunks, chunk_vectors):
    points.append(
        PointStruct(
            id=str(uuid4()),
            vector=vector,
            payload={"text": chunk_text, "source": source_id}
        )
    )
qdrant.upsert(collection_name="documents", points=points)

question_vec = model.encode([question])[0]
search_result = qdrant.search(
    collection_name="documents",
    query_vector=question_vec,
    limit=5
)

Зберагаеце канфігурацыю чытабайнаю — назвы элементаў убудовкі, шляхі індэксаў і ID-ы модэляў павінны знаходзіцца ў аб’екце env, а не як стрынгі з жорсткай канфігурацыяй.

from groq import Groq

client = Groq()
system_msg = (
    "You are a knowledgeable assistant. Answer the user's question using **only** the provided context. "
    "Include citations like [source:chunk_id] for any statements."
)
messages = [
    {"role": "system", "content": system_msg},
    {"role": "user", "content": user_question}
]
response = client.chat.completions.create(
    model="llama-3.1-8b-instant",
    messages=messages,
    temperature=0.1
)
answer = response.choices[0].message.content

Інтэгруйце гэты крок перад расшырэнням інтэрфейсу; багі, зв’язаныя з выкарыстоўванням дадзеных, легча знайсці за дапамогою танкаго кліента.

from fastapi import FastAPI, Depends

app = FastAPI()

@app.post("/api/v1/ingest")
async def ingest(files: list[UploadFile], settings: Settings = Depends(get_settings)):
    # For each PDF: parse -> chunk -> embed -> upsert (as shown above).
    return {"success": True, "indexed": len(files)}

@app.post("/api/v1/query")
async def query(q: QueryRequest, settings: Settings = Depends(get_settings)):
    # q.question is the string from the user
    chunks = retrieve_top_chunks(q.question)   # search Qdrant
    answer = call_llm(q.question, chunks)      # prompt Llama
    return {"answer": answer, "sources": [c["source"] for c in chunks], "chunks": chunks}

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",
        "https://rag-banking-health-assistant-c8f7.vercel.app",
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

curl -X POST "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2" \
  -H "Authorization: Bearer $HF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["test sentence"]}'

# Before (dead)
HF_API_URL = f"https://api-inference.huggingface.co/pipeline/feature-extraction/{MODEL_NAME}"

# After (working)
HF_API_URL = f"https://router.huggingface.co/hf-inference/models/{MODEL_NAME}/pipeline/feature-extraction"

class Settings(BaseSettings):
        QDRANT_URL: str
        QDRANT_API_KEY: str
        GROQ_API_KEY: str
        HF_API_KEY: str
        class Config:
            env_file = ".env"

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

Ацэнка

Зафіксавайце 20 запытанняў з прызначанымі ID сегментаў. Следзіце за практычным рэшэнням запытанняў і наявнасцю цітацый. Прадактны дызайн ніколі не можа выправіць неправільны выбор топ-к.

Прыметкі да развертвання

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

Заключанне

Чыстая структура — разлік маршрутаў і служб, процэсаў запытанняў і ўтворэння рэсультаатаў, прадакту і API — памагае ператворыць дэманстрацыю RAG на аб’ект, які команды можа тэставаць і аператывацыя.

Адкажыце версіі контрактав API разам з ID элементаў для вбудоввання.

Для тэстаў на елементарныя часткі выдзельвайце HTTP-обработчыкі ад чыстых служб.

Тэмы прадакту для тэмнага/светлага рэжыма не павінны змянюваць логіку адбірання дадзеных.

Зяўляйце логі з ID запытанняў разам з пунктамі чату для пазнейшага аналізу.

Паўтараць стварэнне індэксаў па тым жа рытму, як і змена кантэнту у вучыльным матэрыяле.

Адхіляць запыткі, калі найважлівейшыя сегменты выглядаюць слабкімі.

Версіяваць кантракты API разам з ідэнтыфікаторамі вбудоўвачаў.

Для тэстав аддзеліць хандлеры HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны перакладваць логіку адзысквання дадзеных.

Зяўляць логі з ідэнтыфікаторамі запыткаў разам з пунктамі чату для пазнейшага аналізу.

Паўтараць стварэнне індэксаў па тым жа рытму, як і змена кантэнту у вучыльным матэрыяле.

Адхіляць запыткі, калі найважлівейшыя сегменты выглядаюць слабкімі.

Версіяваць кантракты API разам з ідэнтыфікаторамі вбудоўвачаў.

Для тэстав аддзеліць хандлеры HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны перакладваць логіку адзысквання дадзеных.

Зяўляць логі з ідэнтыфікаторамі запыткаў разам з пунктамі чату для пазнейшага аналізу.

Паўтараць стварэнне індэксаў па тым жа рытму, як і змена кантэнту у вучыльным матэрыяле.

Адхіляць запыткі, калі найважлівейшыя сегменты выглядаюць слабкімі.

Версіяваць кантракты API разам з ідэнтыфікаторамі вбудоўвачаў.

Для тэстав аддзеліць хандлеры HTTP ад чыстых служб.

Тэмы інтэрфейса для тэмнага/яскравага рэжыма не павінны выкарыстоўваць аднародную логіку запрашэння даных.

Зявіце логі з ідэамі запрашэння даных разам з паворотамі ў чаце для пазнейшага аналізу.

Перабудавайце індэксы за тым самым рытамам, які і змена выхадных даных.

Адмовіцеся, калі верхнія сегменты выглядаюць слабкімі.

Указвайце версіі контрактав API разам з ідэямі вбудоввання.

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

Тэмы інтэрфейса для тэмнага/яскравага рэжыма не павінны выкарыстоўваць аднародную логіку запрашэння даных.

Зявіце логі з ідэамі запрашэння даных разам з паворотамі ў чаце для пазнейшага аналізу.

Перабудавайце індэксы за тым самым рытамам, які і змена выхадных даных.

Адмовіцеся, калі верхнія сегменты выглядаюць слабкімі.

Указвайце версіі контрактав API разам з ідэямі вбудоввання.

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

Тэмы інтэрфейса для тэмнага/яскравага рэжыма не павінны выкарыстоўваць аднародную логіку запрашэння даных.

Зявіце логі з ідэамі запрашэння даных разам з паворотамі ў чаце для пазнейшага аналізу.

Перабудавайце індэксы за тым самым рытамам, які і змена выхадных даных.

Адмовіцеся, калі верхнія сегменты выглядаюць слабкімі.

Кантракты API разных версій палячыяся ля ідэнтыфікатораў embedder.

Для тэстав на елементарныя часткі неабходна аддзельна обработка запытак HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны выкарыстоўваць аднойчынную логіку запрашэння даных.

Зяўляйце логі з ідэнтыфікаторамі запрашэнняў разам з параграмі чату для пазнейшага аналізу.

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

Адмовіце, калі найважлівейшыя сегменты выглядаюць слабкімі.

Кантракты API разных версій палячыяся ля ідэнтыфікатораў embedder.

Для тэстав на елементарныя часткі неабходна аддзельна обработка запытак HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны выкарыстоўваць аднойчынную логіку запрашэння даных.

Зяўляйце логі з ідэнтыфікаторамі запрашэнняў разам з параграмі чату для пазнейшага аналізу.

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

Адмовіце, калі найважлівейшыя сегменты выглядаюць слабкімі.

Кантракты API разных версій палячыяся ля ідэнтыфікатораў embedder.

Для тэстав на елементарныя часткі неабходна аддзельна обработка запытак HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны выкарыстоўваць аднойчынную логіку запрашэння даных.

Зяўляйце логі з ідэнтыфікаторамі запрашэнняў разам з параграмі чату для пазнейшага аналізу.

Паўтараць стварэнне індэксаў па тым жа рытму, як і змена кантэнту у вучыльным матэрыяле.

Адхіляць запыткі, калі найважлівейшыя сегменты выглядаюць слабкімі.

Версіяваць кантракты API разам з ідэнтыфікаторамі вбудоўвачаў.

Для тэстав аддзеліць хандлеры HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны перакладваць логіку адзысквання дадзеных.

Зяўляць логі з ідэнтыфікаторамі запыткаў разам з пунктамі чату для пазнейшага аналізу.

Паўтараць стварэнне індэксаў па тым жа рытму, як і змена кантэнту у вучыльным матэрыяле.

Адхіляць запыткі, калі найважлівейшыя сегменты выглядаюць слабкімі.

Версіяваць кантракты API разам з ідэнтыфікаторамі вбудоўвачаў.

Для тэстав аддзеліць хандлеры HTTP ад чыстых служб.

Тэмы інтэрфейса «тэмная/яскравая» не павінны перакладваць логіку адзысквання дадзеных.

Зяўляць логі з ідэнтыфікаторамі запыткаў разам з пунктамі чату для пазнейшага аналізу.

Паўтараць стварэнне індэксаў па тым жа рытму, як і змена кантэнту у вучыльным матэрыяле.

Адхіляць запыткі, калі найважлівейшыя сегменты выглядаюць слабкімі.

Версіяваць кантракты API разам з ідэнтыфікаторамі вбудоўвачаў.

Для тэстав аддзеліць хандлеры HTTP ад чыстых служб.

Тэмныя/светлыя тэмы інтэрфейса не павінны змянюваць логіку запошуку.

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

Павтараць стварэнне індэксаў па тым жа рытму, як і змены у выхідных даных.

Адмовіцца, калі найважлівейшыя сегменты выглядаюць слабкімі.

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

Зберагаюце фікстуры, адміністратароў і прыметкі паўранення разам з процэсамі запрацоўкі і розпавесці змян.

Зберагаюце фікстуры, ўладальнікаў і прыметкі паўранення разам з працэсамі запрацоўкі і розгортання змян.

← Усе артыкулы Даслаць брыф