AR 15 M4
6348d9a206
README переписан под текущее состояние — был TBD со времён init: - Статус: Спринты 1–2 и доработки (2.5) закрыты, что именно уже работает (RAG, многошаговый диалог, переиндексация, две страницы). - Запуск: команды для установки, старта, ручного наката миграций и создания новых. Автомиграции на старте отмечены. - Использование: табличка API-эндпоинтов (/documents, /query, /chat, /threads, /reindex), описание двух веб-страниц и правки системного промпта через prompts/system_prompt.md. - Структура: актуальное дерево директорий с назначением каждого модуля (db/, prompts/, routers/, services/, static/). SPRINTS.md: Спринт 2.5 помечен закрытым — все пять задач пройдены (логи, системный промпт в файле, markdown-рендер, чистка чанков + reindex, README). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
214 lines
12 KiB
Markdown
214 lines
12 KiB
Markdown
# Chat Agent for Patients (RAG) — инструмент настройки
|
||
|
||
**RAG-ядро + веб-инструмент для настройки пациентского чат-агента: загрузка wiki, редактирование промпта и правил, прогон сценариев.**
|
||
|
||
Подключение реальных каналов (чат в мобильном приложении, бот в МАКС) делает другой разработчик — этот проект отдаёт ему **готовое RAG-ядро и API** плюс согласованную конфигурацию (системный промпт, правила, снапшот базы знаний).
|
||
|
||
---
|
||
|
||
## Статус
|
||
|
||
🟢 **Active — Спринты 1–2 и доработки (2.5) закрыты, идём на Спринт 3.**
|
||
|
||
Что уже работает:
|
||
- RAG-ядро: FastAPI + ChromaDB + `intfloat/multilingual-e5-large` + DeepSeek.
|
||
- Загрузка документов (`.md`, `.txt`, `.pdf`, `.docx`), чанкинг с чисткой markdown-мусора (навигационные блоки, инлайн-ссылки), просмотр чанков с эмбеддингами.
|
||
- Многошаговый диалог с памятью треда (SQLAlchemy 2.0 async + Alembic + SQLite). История хранится навсегда.
|
||
- Переиндексация без повторной загрузки файла: сохранённый `raw_text` → новый чанкер.
|
||
- Две отладочные страницы: «Отладка» (одиночный вопрос, база знаний) и «Песочница» (чат с агентом, список тредов, переименование, удаление).
|
||
- Markdown-рендер ответов ассистента в «Песочнице».
|
||
- Системный промпт вынесен в `prompts/system_prompt.md` — правится без кода.
|
||
|
||
---
|
||
|
||
## Цель проекта
|
||
|
||
- Поднять RAG по wiki операторов и API диалога с агентом.
|
||
- Дать операторам веб-инструмент, в котором они в процессе настройки:
|
||
- загружают документы wiki (постепенно, по мере готовности — не пакетно);
|
||
- редактируют системный промпт и правила поведения агента;
|
||
- играют роль пациента в тестовом чате и смотрят, что отвечает агент;
|
||
- сохраняют проработанные диалоги как **сценарии** и перегоняют их после изменения настроек.
|
||
- Сама интеграция с реальными каналами (приложение, МАКС) — вне скоупа этого проекта.
|
||
|
||
---
|
||
|
||
## Что **не** входит в скоуп
|
||
|
||
- Реальная интеграция с чатом в мобильном приложении (`work-pcs-pt-mobile`).
|
||
- Реальная интеграция с ботом в МАКС (`work-pcs-pt-bots`).
|
||
- Очередь и UI оператора для живого переключения с агента на человека.
|
||
- Мультипользовательская прод-эксплуатация.
|
||
|
||
Всё это — задача смежного разработчика, который будет использовать API этого сервиса.
|
||
|
||
---
|
||
|
||
## Архитектура (черновик)
|
||
|
||
```
|
||
┌──────────────────────────────────┐ ┌──────────────────────┐
|
||
│ Web UI настройки (один экран) │ │ │
|
||
│ ┌────────────┐ ┌────────────┐ │ │ RAG (wiki) │
|
||
│ │ База знаний│ │ Промпт + │──┼─────▶│ ChromaDB + E5 │
|
||
│ │ (upload) │ │ правила │ │ └──────────────────────┘
|
||
│ └────────────┘ └────────────┘ │ ┌──────────────────────┐
|
||
│ ┌────────────┐ ┌────────────┐ │─────▶│ DeepSeek LLM API │
|
||
│ │ Песочница │ │ Сценарии │ │ └──────────────────────┘
|
||
│ │ (чат) │ │ (сохран.) │ │
|
||
│ └────────────┘ └────────────┘ │
|
||
└──────────────────────────────────┘
|
||
│
|
||
▼
|
||
Chat Agent API (FastAPI)
|
||
(тот же API, что потом получит
|
||
внешний разработчик для каналов)
|
||
```
|
||
|
||
**Ключевая идея:** веб-инструмент — это единственный клиент агента на время настройки. Когда конфигурация «устаканивается», её снапшот отдаётся внешнему разработчику вместе с документированным API.
|
||
|
||
---
|
||
|
||
## Технологический стек (предварительно)
|
||
|
||
| Слой | Технология | Назначение |
|
||
|------|-----------|-----------|
|
||
| API | FastAPI (Python 3.11–3.12) | HTTP-эндпоинты агента и настройки |
|
||
| Vector DB | ChromaDB | База эмбеддингов wiki |
|
||
| Embeddings | `intfloat/multilingual-e5-large` | Русскоязычные эмбеддинги |
|
||
| LLM | DeepSeek API | Диалоговая модель |
|
||
| Хранилище конфигов и сценариев | SQLite | Промпты, правила, сценарии |
|
||
| Веб-UI | Vanilla JS / лёгкий фреймворк | Одностраничное приложение настройки |
|
||
| Контейнеризация | Docker | Изолированный запуск |
|
||
|
||
> База опыта — [`work-pcs-dr-cdss`](../work-pcs-dr-cdss) (RAG-сервис для врачей). Переиспользуем паттерн сервисов `embeddings.py / vectorstore.py / document_processor.py / llm_client.py`.
|
||
|
||
---
|
||
|
||
## План (спринты)
|
||
|
||
См. [`SPRINTS.md`](./SPRINTS.md).
|
||
|
||
---
|
||
|
||
## Запуск
|
||
|
||
### Требования
|
||
- Python 3.12
|
||
- Ключ DeepSeek API
|
||
|
||
### Установка
|
||
|
||
```bash
|
||
python3.12 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
cp .env.example .env # и вписать DEEPSEEK_API_KEY
|
||
```
|
||
|
||
### Старт
|
||
|
||
```bash
|
||
.venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8003
|
||
```
|
||
|
||
Миграции Alembic применяются автоматически на старте. Первая загрузка
|
||
embedding-модели E5-large занимает ~15–20 секунд.
|
||
|
||
### Вручную накатить миграции
|
||
|
||
```bash
|
||
.venv/bin/alembic upgrade head
|
||
```
|
||
|
||
### Создать новую миграцию после изменения моделей
|
||
|
||
```bash
|
||
.venv/bin/alembic revision --autogenerate -m "описание изменений"
|
||
.venv/bin/alembic upgrade head
|
||
```
|
||
|
||
---
|
||
|
||
## Использование
|
||
|
||
### Веб-страницы
|
||
|
||
- `http://localhost:8003/` — **Отладка**: загрузка документов, просмотр чанков со scores и эмбеддингами, одиночный тест-вопрос с 3-колоночным ответом (чанки / промпт / ответ LLM).
|
||
- `http://localhost:8003/sandbox.html` — **Песочница**: чат с агентом. Слева список сохранённых диалогов, в центре сам чат, справа отладка последнего ответа (найденные чанки + собранный промпт).
|
||
|
||
### API
|
||
|
||
| Метод | Путь | Назначение |
|
||
|-------|------|-----------|
|
||
| GET | `/health` | Статус, кол-во документов и чанков, модель эмбеддингов |
|
||
| POST | `/documents/upload` | Загрузить файл (`.md`, `.txt`, `.pdf`, `.docx`), сохраняет `raw_text` в SQLite и чанки в Chroma |
|
||
| GET | `/documents` | Список документов |
|
||
| GET | `/documents/{id}/chunks` | Чанки документа + их эмбеддинги |
|
||
| DELETE | `/documents/{id}` | Удалить документ (из Chroma и SQLite) |
|
||
| POST | `/documents/{id}/reindex` | Переразметить документ с актуальными правилами чанкера |
|
||
| POST | `/documents/reindex-all` | Переразметить всю базу |
|
||
| POST | `/query` | Одиночный вопрос (Отладка) |
|
||
| POST | `/chat` | Отправить реплику в тред (создаёт тред, если `thread_id` не передан) |
|
||
| GET | `/threads` | Список всех диалогов |
|
||
| GET | `/threads/{id}` | Тред целиком с историей |
|
||
| PATCH | `/threads/{id}` | Переименовать |
|
||
| DELETE | `/threads/{id}` | Удалить тред со всеми сообщениями |
|
||
|
||
### Правка системного промпта
|
||
|
||
`prompts/system_prompt.md` — читается при старте сервиса. После правки — рестарт.
|
||
|
||
---
|
||
|
||
## Структура
|
||
|
||
```
|
||
.
|
||
├── config.py # настройки (Pydantic BaseSettings)
|
||
├── main.py # FastAPI app, lifespan, авто-миграции
|
||
├── alembic.ini # конфиг Alembic
|
||
├── migrations/ # миграции БД
|
||
├── prompts/
|
||
│ └── system_prompt.md # системный промпт (правится без кода)
|
||
├── db/
|
||
│ ├── base.py # DeclarativeBase
|
||
│ ├── session.py # async engine + sessionmaker
|
||
│ └── models/
|
||
│ ├── thread.py # диалоги
|
||
│ ├── message.py # сообщения
|
||
│ └── document.py # raw_text документов для reindex
|
||
├── models/ # Pydantic-модели API
|
||
│ ├── requests.py
|
||
│ └── responses.py
|
||
├── routers/
|
||
│ ├── health.py
|
||
│ ├── documents.py # upload / list / chunks / delete / reindex
|
||
│ ├── query.py # /query (одиночный вопрос)
|
||
│ ├── chat.py # /chat (диалог с памятью)
|
||
│ └── threads.py # CRUD тредов
|
||
├── services/
|
||
│ ├── embeddings.py # E5-large
|
||
│ ├── vectorstore.py # ChromaDB
|
||
│ ├── document_processor.py # парсер + чанкер
|
||
│ ├── text_cleanup.py # чистка markdown-мусора
|
||
│ ├── document_service.py # SQLite-слой для raw_text
|
||
│ ├── llm_client.py # DeepSeek
|
||
│ ├── rag_pipeline.py # /query pipeline
|
||
│ └── chat_service.py # диалоги: создание треда, сборка контекста
|
||
├── static/
|
||
│ ├── index.html # страница «Отладка»
|
||
│ └── sandbox.html # страница «Песочница»
|
||
└── data/
|
||
├── chroma/ # векторная БД (gitignored)
|
||
└── sqlite/ # реляционная БД (gitignored)
|
||
```
|
||
|
||
---
|
||
|
||
## Связанные проекты
|
||
|
||
- [`work-pcs-dr-cdss`](../work-pcs-dr-cdss) — RAG для врачей, источник технических паттернов.
|
||
- [`work-pcs-pt-mobile`](../work-pcs-pt-mobile) — мобильное приложение пациента (канал подключит другой разработчик).
|
||
- [`work-pcs-pt-bots`](../work-pcs-pt-bots) — пациентские боты МАКС (канал подключит другой разработчик).
|