Files
RAG_helper/routers/documents.py
T
AR 15 M4 52b46bc53e feat(sprint6c+sprint7): терминология, сверка примеров с кодом, мульти-RAG (часть A)
Спринт 6c — терминология и сверка документации с реальным кодом:
- Словарь терминов в static/docs.html: «маршрутизатор» вместо «роутер»,
  «защитное условие» вместо «guard», «пошаговая ветка» вместо «многошаговая».
  Разделены концепты «намерение» (intent) и «ветка» (branch) с пометкой,
  что в коде они хранятся как одна сущность 1:1.
- Песочница: «Решение маршрутизатора» виден всегда (зелёный/жёлтый),
  счётчик переключений «N из 3» отдельной плашкой, бейджи под словарь.
- Настройки: «Условия перехода» → «Защитные условия (guards, JSON)».
- GRAPH_ARCHITECTURE_v4.md: имена полей thread_state и слоты приведены
  к реальной БД (db/models/thread_state.py) и таксономии промптов шагов
  (prompts/intents/new_booking/steps/). Ссылки на *_v2 примеры. На v3
  поставлена шапка «устарело».
- 4 примера переписаны как *_v2: реальные current_intent_code/
  current_step_code/slots_json, реальные allowed_next без двойных переходов,
  реальная таксономия слотов name/reason/specialist/preferred_time/confirmed.
  Удалены вымышленные CRM tool calls и слоты, которых нет в коде.
- static/example.html — параметризованная страница с навигацией между
  4 примерами; роут GET /api/docs/examples/{name} в main.py отдаёт
  markdown без дублирования файлов.
- Редактирование документов в Отладке: GET/PUT /documents/{id}/raw,
  textarea с переразметкой и обновлением Chroma при сохранении.

Спринт 7, часть A — мульти-RAG через подписку ветка↔документы:
- Миграция: таблица intent_documents (M:N), модель IntentDocument,
  индекс по document_id для обратного поиска.
- API: GET/PUT /intents/{code}/documents и GET/PUT /documents/{id}/intents
  с PUT-семантикой «полный список», атомарно. Сервис
  services/intent_document_service.py.
- Retrieval-фильтр в chat_service: подтягивает document_ids активной
  ветки и передаёт в vectorstore.query(). Дефолт пустой подписки —
  document_ids=[] (= 0 чанков), не «вся коллекция»: пустая подписка
  означает «ветка не настроена», подмешивать случайное хуже, чем
  ничего. vectorstore.query() различает None (нет фильтра) и [] (0).
- UI Настроек: блок «Документы базы знаний» в правом сайдбаре,
  всегда видим независимо от вкладки, сортировка по имени, счётчик
  «N из M», PUT при сохранении.
- UI Отладки: третья кнопка «привязка» рядом с «удалить» —
  раскрывашка со списком веток (галочки), быстрая привязка прямо
  на странице загрузки.
- Песочница: блок «Срез RAG» с подпиской/найдено, ворнинг при пустой
  подписке. Поле rag_subscription в QueryResponse и ChatResponse.
- Системный промпт страницы Отладки переехал в обычную ветку _debug
  («Страница отладки»). Удалён prompts/system_prompt.md и логика
  DEFAULT_SYSTEM_PROMPT в llm_client. routers/query.py подтягивает
  активный конфиг ветки _debug и её подписки. Дефолт пустой подписки
  для _debug — None (вся коллекция), не [] как для пациентских — чтобы
  Отладка работала «из коробки». На странице Отладки info-bar показывает
  активную версию и счётчик подписок, ссылка → Настройки.
- Тест-блок «Тест-вопрос» в центре Настроек: расширил /query
  параметрами intent_code (default _debug), system_prompt (override
  для теста черновика из textarea), disable_rag (для _router).
  Редактор промпта обёрнут в <details open> — можно свернуть до
  одной строки. Под ним — три колонки результата (RAG / промпт /
  ответ). Для _router показывается подсказка про отсутствие RAG.

Документы:
- data/datasets/*.md — наработки по 6 веткам (рабочие материалы оператора).
- docs/BRANCH_MAP_AND_PROMPTS_v1.md, docs/OPTIMIZATION_CONVERSION_v1.md,
  docs/guides/state_machine_and_slots.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 20:00:44 +05:00

374 lines
13 KiB
Python

import logging
from datetime import datetime, timezone
from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
from sqlalchemy.ext.asyncio import AsyncSession
from db.session import get_session
from models.requests import DocumentIntentsUpdateRequest, DocumentRawUpdateRequest
from models.responses import (
ChunkDetail,
ChunkPreview,
DocumentChunksResponse,
DocumentDeleteResponse,
DocumentInfo,
DocumentIntentsResponse,
DocumentListResponse,
DocumentUploadResponse,
)
from services import document_service, intent_document_service
from services.document_processor import process_document, rechunk_raw_text
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/documents", tags=["documents"])
ALLOWED_EXTENSIONS = {".pdf", ".docx", ".doc", ".txt", ".md"}
MAX_FILE_SIZE = 50 * 1024 * 1024 # 50 MB
@router.post("/upload", response_model=DocumentUploadResponse)
async def upload_document(
file: UploadFile = File(...),
document_name: str | None = Form(None),
session: AsyncSession = Depends(get_session),
):
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
filename = file.filename or "unknown"
ext = "." + filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
if ext not in ALLOWED_EXTENSIONS:
raise HTTPException(
status_code=400,
detail=f"Unsupported file format: {ext}. Allowed: {', '.join(ALLOWED_EXTENSIONS)}",
)
file_bytes = await file.read()
if len(file_bytes) > MAX_FILE_SIZE:
raise HTTPException(status_code=400, detail="File too large (max 50 MB)")
if len(file_bytes) == 0:
raise HTTPException(status_code=400, detail="Empty file")
display_name = document_name or filename
try:
document_id, raw_text, sections, chunks = process_document(file_bytes, filename)
except ValueError as e:
raise HTTPException(status_code=400, detail=str(e))
except Exception as e:
logger.exception("Failed to process document: %s", filename)
raise HTTPException(status_code=500, detail=f"Error processing document: {e}")
if not chunks:
raise HTTPException(status_code=400, detail="No content could be extracted from the document")
file_type = ext.lstrip(".")
await document_service.save_document_raw(
session=session,
document_id=document_id,
name=display_name,
file_type=file_type,
raw_text=raw_text,
)
chunks_count = vectorstore_service.add_document(
document_id=document_id,
document_name=display_name,
file_type=file_type,
chunks=[
{
"text": c.text,
"section": c.section,
"page_number": c.page_number,
"chunk_index": c.chunk_index,
}
for c in chunks
],
)
chunks_prev = [
ChunkPreview(
index=c.chunk_index,
section=c.section,
page_number=c.page_number,
text_preview=c.text[:300],
char_length=len(c.text),
)
for c in chunks[:3]
]
return DocumentUploadResponse(
document_id=document_id,
name=display_name,
chunks_count=chunks_count,
status="indexed",
created_at=datetime.now(timezone.utc).isoformat(),
chunks_preview=chunks_prev,
)
@router.get("", response_model=DocumentListResponse)
async def list_documents():
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
docs = vectorstore_service.list_documents()
return DocumentListResponse(
documents=[DocumentInfo(**d) for d in docs],
total=len(docs),
)
@router.get("/{document_id}/chunks", response_model=DocumentChunksResponse)
async def get_document_chunks(document_id: str):
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
raw_chunks = vectorstore_service.get_document_chunks(document_id)
if not raw_chunks:
raise HTTPException(status_code=404, detail="Document not found")
meta0 = raw_chunks[0]["metadata"]
chunks = [
ChunkDetail(
index=c["metadata"].get("chunk_index", 0),
section=c["metadata"].get("section", ""),
page_number=c["metadata"].get("page_number", 0),
text=c["text"],
char_length=len(c["text"]),
embedding=c.get("embedding", []),
embedding_dim=len(c.get("embedding", [])),
)
for c in raw_chunks
]
return DocumentChunksResponse(
document_id=document_id,
name=meta0.get("document_name", ""),
file_type=meta0.get("file_type", ""),
chunks_count=len(chunks),
chunks=chunks,
)
@router.delete("/{document_id}", response_model=DocumentDeleteResponse)
async def delete_document(document_id: str, session: AsyncSession = Depends(get_session)):
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
deleted = vectorstore_service.delete_document(document_id)
await document_service.delete_document_raw(session, document_id)
if deleted == 0:
raise HTTPException(status_code=404, detail="Document not found")
return DocumentDeleteResponse(ok=True, deleted_chunks=deleted)
@router.post("/{document_id}/reindex", response_model=DocumentUploadResponse)
async def reindex_document(document_id: str, session: AsyncSession = Depends(get_session)):
"""Переразметить документ с актуальными правилами чанкера на основе сохранённого raw_text."""
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
doc = await document_service.get_document_raw(session, document_id)
if doc is None:
raise HTTPException(status_code=404, detail="Document raw_text not found — reindex невозможен")
chunks = rechunk_raw_text(doc.raw_text)
if not chunks:
raise HTTPException(status_code=400, detail="После переразметки не осталось чанков")
vectorstore_service.delete_document(document_id)
chunks_count = vectorstore_service.add_document(
document_id=document_id,
document_name=doc.name,
file_type=doc.file_type,
chunks=[
{
"text": c.text,
"section": c.section,
"page_number": c.page_number,
"chunk_index": c.chunk_index,
}
for c in chunks
],
)
chunks_prev = [
ChunkPreview(
index=c.chunk_index,
section=c.section,
page_number=c.page_number,
text_preview=c.text[:300],
char_length=len(c.text),
)
for c in chunks[:3]
]
return DocumentUploadResponse(
document_id=document_id,
name=doc.name,
chunks_count=chunks_count,
status="reindexed",
created_at=datetime.now(timezone.utc).isoformat(),
chunks_preview=chunks_prev,
)
@router.get("/{document_id}/raw")
async def get_document_raw_text(document_id: str, session: AsyncSession = Depends(get_session)):
"""Отдать исходный текст документа — для редактирования в UI."""
doc = await document_service.get_document_raw(session, document_id)
if doc is None:
raise HTTPException(status_code=404, detail="Document not found")
return {
"document_id": doc.id,
"name": doc.name,
"file_type": doc.file_type,
"raw_text": doc.raw_text,
}
@router.put("/{document_id}/raw", response_model=DocumentUploadResponse)
async def update_document_raw_text(
document_id: str,
req: DocumentRawUpdateRequest,
session: AsyncSession = Depends(get_session),
):
"""Обновить raw_text + сразу переразметить и переиндексировать в Chroma.
Деструктивная операция: старые чанки удаляются, новые берут их место.
Имя и file_type не меняются.
"""
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
doc = await document_service.get_document_raw(session, document_id)
if doc is None:
raise HTTPException(status_code=404, detail="Document not found")
new_raw = req.raw_text.strip()
if not new_raw:
raise HTTPException(status_code=400, detail="raw_text не может быть пустым")
chunks = rechunk_raw_text(new_raw)
if not chunks:
raise HTTPException(status_code=400, detail="После переразметки не осталось чанков")
# 1) обновляем raw_text в SQLite
await document_service.save_document_raw(
session=session,
document_id=document_id,
name=doc.name,
file_type=doc.file_type,
raw_text=new_raw,
)
# 2) переиндексация в Chroma — те же шаги, что в /reindex
vectorstore_service.delete_document(document_id)
chunks_count = vectorstore_service.add_document(
document_id=document_id,
document_name=doc.name,
file_type=doc.file_type,
chunks=[
{
"text": c.text,
"section": c.section,
"page_number": c.page_number,
"chunk_index": c.chunk_index,
}
for c in chunks
],
)
chunks_prev = [
ChunkPreview(
index=c.chunk_index,
section=c.section,
page_number=c.page_number,
text_preview=c.text[:300],
char_length=len(c.text),
)
for c in chunks[:3]
]
return DocumentUploadResponse(
document_id=document_id,
name=doc.name,
chunks_count=chunks_count,
status="updated",
created_at=datetime.now(timezone.utc).isoformat(),
chunks_preview=chunks_prev,
)
@router.post("/reindex-all")
async def reindex_all(session: AsyncSession = Depends(get_session)):
"""Переразметить все документы, у которых есть raw_text в SQLite."""
from main import vectorstore_service
if vectorstore_service is None:
raise HTTPException(status_code=503, detail="Service not ready")
docs = await document_service.list_documents_raw(session)
results = []
for doc in docs:
chunks = rechunk_raw_text(doc.raw_text)
if not chunks:
results.append({"document_id": doc.id, "name": doc.name, "status": "empty"})
continue
vectorstore_service.delete_document(doc.id)
n = vectorstore_service.add_document(
document_id=doc.id,
document_name=doc.name,
file_type=doc.file_type,
chunks=[
{
"text": c.text,
"section": c.section,
"page_number": c.page_number,
"chunk_index": c.chunk_index,
}
for c in chunks
],
)
results.append({"document_id": doc.id, "name": doc.name, "status": "reindexed", "chunks_count": n})
return {"total": len(results), "results": results}
@router.get("/{document_id}/intents", response_model=DocumentIntentsResponse)
async def list_document_intents(document_id: str, session: AsyncSession = Depends(get_session)):
doc = await document_service.get_document_raw(session, document_id)
if doc is None:
raise HTTPException(status_code=404, detail="Document not found")
intent_codes = await intent_document_service.list_intents_for_document(session, document_id)
return DocumentIntentsResponse(document_id=document_id, intent_codes=intent_codes)
@router.put("/{document_id}/intents", response_model=DocumentIntentsResponse)
async def set_document_intents(
document_id: str,
req: DocumentIntentsUpdateRequest,
session: AsyncSession = Depends(get_session),
):
doc = await document_service.get_document_raw(session, document_id)
if doc is None:
raise HTTPException(status_code=404, detail="Document not found")
intent_codes = await intent_document_service.set_intents_for_document(
session, document_id, req.intent_codes,
)
return DocumentIntentsResponse(document_id=document_id, intent_codes=intent_codes)