AR 15 M4
f348570b1b
- SPRINTS.md → docs/SPRINTS.md - GRAPH_ARCHITECTURE.md → docs/architecture/GRAPH_ARCHITECTURE_v1.md - GRAPH_ARCHITECTURE_v2.md → docs/architecture/GRAPH_ARCHITECTURE_v2.md - Новый docs/architecture/GRAPH_ARCHITECTURE_v3.md (билингв. термины + ссылки на примеры) - Новые docs/examples/: 01 базовая запись, 02 цена во время записи (soft vs hard), 03 запись ребёнка (guard), 04 простой general_info - README обновлён: ссылки на новые пути + раздел «Документация» Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
231 lines
14 KiB
Markdown
231 lines
14 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`.
|
||
|
||
---
|
||
|
||
## План (спринты)
|
||
|
||
См. [`docs/SPRINTS.md`](./docs/SPRINTS.md). Архитектурные документы и разобранные примеры — в [`docs/architecture/`](./docs/architecture/) и [`docs/examples/`](./docs/examples/).
|
||
|
||
---
|
||
|
||
## Запуск
|
||
|
||
### Требования
|
||
- 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` — читается при старте сервиса. После правки — рестарт.
|
||
|
||
---
|
||
|
||
## Структура
|
||
|
||
```
|
||
.
|
||
├── README.md # этот файл
|
||
├── docs/ # проектная документация (см. ниже)
|
||
├── 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)
|
||
```
|
||
|
||
### Документация (`docs/`)
|
||
|
||
```
|
||
docs/
|
||
├── SPRINTS.md # план и статус спринтов
|
||
├── architecture/
|
||
│ ├── GRAPH_ARCHITECTURE_v1.md # черновик при развороте 2026-04-23
|
||
│ ├── GRAPH_ARCHITECTURE_v2.md # уточнения 2026-04-24
|
||
│ └── GRAPH_ARCHITECTURE_v3.md # текущая (билингв. термины + ссылки на примеры)
|
||
└── examples/
|
||
├── 01_basic_booking.md # happy path записи (линейный)
|
||
├── 02_price_during_booking.md # soft-insertion vs. hard-handoff
|
||
└── 03_child_patient_guard.md # guard в шаге qualify (запись ребёнка)
|
||
```
|
||
|
||
---
|
||
|
||
## Связанные проекты
|
||
|
||
- [`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) — пациентские боты МАКС (канал подключит другой разработчик).
|