Add full README
CI / lint_and_test (push) Successful in 2m30s
Details
CI / lint_and_test (push) Successful in 2m30s
Details
This commit is contained in:
parent
79b773f843
commit
9f616aaf1d
346
README.md
346
README.md
|
|
@ -6,3 +6,349 @@
|
|||
|
||||
Сервис для генерации персонализированных холодных писем с использованием RAG и LangGraph.
|
||||
|
||||
## О программе
|
||||
|
||||
- Персонализация писем под роль, индустрию и компанию лида
|
||||
- RAG-подход с базой знаний реальных кейсов
|
||||
- LangGraph пайплайн обработки запросов
|
||||
- Векторный поиск в ChromaDB
|
||||
- Поддержка OpenAI и Google Gemini
|
||||
- RESTful API для интеграции с CRM
|
||||
|
||||
### Логика работы
|
||||
|
||||
Система обрабатывает запросы через 10-этапный LangGraph пайплайн:
|
||||
|
||||
1. **Валидация входа** - проверка обязательных полей лида
|
||||
2. **Извлечение признаков** - нормализация роли, индустрии из входных данных
|
||||
3. **Построение запроса** - формирование поискового запроса на основе профиля лида
|
||||
4. **Векторный поиск** - поиск релевантных кейсов в ChromaDB (top-30)
|
||||
5. **Ранжирование контекста** - отбор лучших кейсов (top-6) и создание bullets
|
||||
6. **Построение промпта** - формирование системного и пользовательского промптов
|
||||
7. **LLM генерация** - создание письма через OpenAI/Gemini
|
||||
8. **Парсинг ответа** - извлечение JSON с темой и телом письма
|
||||
9. **Проверка качества** - валидация длины, структуры, наличия CTA
|
||||
10. **Формирование результата** - финальная структура ответа с метаданными
|
||||
|
||||
## Промпт-инжиниринг: обоснование подхода
|
||||
|
||||
### Почему именно такая структура письма?
|
||||
|
||||
Структура **Приветствие -> Хук -> Ценность -> Кейс -> CTA -> Подпись** выбрана на основе исследований конверсии холодных писем:
|
||||
|
||||
**1. Приветствие по имени**
|
||||
- Персонализация создает впечатление индивидуального подхода
|
||||
- Снижает восприятие письма как спама
|
||||
|
||||
**2. Хук-вопрос в первых строках**
|
||||
- Привлекает внимание и активирует любопытство
|
||||
- Касается специфики индустрии лида -> создает ощущение релевантности
|
||||
|
||||
**3. Конкретная ценность с цифрами**
|
||||
- Мозг лучше воспринимает конкретные числа vs абстракции
|
||||
- "15 минут" vs "быстро", "95%" vs "значительно"
|
||||
- Снижает скептицизм -> повышает доверие
|
||||
|
||||
**4. Социальное доказательство с кейсом**
|
||||
- Название реальной компании + численный результат
|
||||
- Психология: "если помогли похожей компании, помогут и нам"
|
||||
- Снижает воспринимаемый риск принятия решения
|
||||
|
||||
**5. Мягкий CTA без давления**
|
||||
- "Если интересно" vs "Давайте встретимся завтра"
|
||||
- Оставляет ощущение выбора -> снижает сопротивление
|
||||
- 15-минутный формат -> низкий барьер входа
|
||||
|
||||
**6. Эмоциональные триггеры**
|
||||
- "Спокойствие", "контроль" -> позитивные эмоции от решения проблем
|
||||
- "Избежите", "снизьте риски" -> страх потерь (loss aversion)
|
||||
- Комбинация мотивирует к действию
|
||||
|
||||
### Ограничения для максимальной эффективности
|
||||
|
||||
- **≤ 1000 символов**: оптимальная длина письма для цифрового потребления. Согласно Nielsen Norman Group, пользователи читают в среднем 20–28% текста на веб-странице и быстро теряют внимание после первых 200–250 слов (~1000–1200 символов).
|
||||
Источник: [How Users Read on the Web](https://www.nngroup.com/articles/how-users-read-on-the-web/)
|
||||
- **Микро-абзацы 1-2 предложения**: улучшают восприятие текста на экранах смартфонов. Люди сканируют информацию взглядом, и короткие абзацы помогают быстрее вычленять ключевые мысли.
|
||||
Источник: [F-Shaped Pattern of Reading Web Content](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/)
|
||||
- **1 конкретный CTA**: письма с одним призывом к действию получают на **371 % больше кликов** и могут увеличить доход на **1617 %** по сравнению с письмами с несколькими CTA.
|
||||
Источник: [Unlayer - Call to Action in Emails](https://unlayer.com/blog/call-to-action-in-emails)
|
||||
|
||||
### Настройка промптов
|
||||
|
||||
Системные промпты: `src/services/prompt_templates.py`
|
||||
|
||||
- Тон: деловой, лаконичный, дружелюбный
|
||||
- Длина: до 1000 символов
|
||||
- Структура: Приветствие -> Хук -> Ценность -> Кейс -> CTA -> Подпись
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### 1. Подготовка окружения
|
||||
|
||||
```bash
|
||||
git clone https://git.itqop.pw/itqop/ai-email-assistant.git
|
||||
cd ai-email-assistant
|
||||
|
||||
# Создание конфигурации
|
||||
cp .env.example .env
|
||||
# Или создайте .env файл сами
|
||||
```
|
||||
|
||||
### 2. Базовая конфигурация .env
|
||||
|
||||
```bash
|
||||
LLM_PROVIDER=openai
|
||||
OPENAI_API_KEY=your_openai_api_key_here
|
||||
API_SECRET_KEY=your_admin_token
|
||||
```
|
||||
|
||||
### 3. Запуск через Docker
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
### 4. Загрузка базы знаний
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/admin/ingest" \
|
||||
-H "Authorization: Bearer your_admin_token"
|
||||
```
|
||||
|
||||
### 5. Использование
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/generate_email" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"contact": "Помящий Никита",
|
||||
"position": "Технический директор",
|
||||
"company_name": "FIVE",
|
||||
"segment": "маркетинговое агентство"
|
||||
}'
|
||||
```
|
||||
|
||||
## Альтернативный запуск (без Docker)
|
||||
|
||||
```bash
|
||||
# Создание виртуального окружения
|
||||
python -m venv .venv
|
||||
.venv\Scripts\activate # Windows
|
||||
source .venv/bin/activate # Linux/Mac
|
||||
|
||||
# Установка зависимостей
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Загрузка данных
|
||||
python -m src.ingest.ingest_cli --data-dir articles_konsol_pro --recreate
|
||||
|
||||
# Запуск сервиса
|
||||
python -m src.app.main
|
||||
```
|
||||
|
||||
## API документация
|
||||
|
||||
### Основные эндпоинты
|
||||
|
||||
- `GET /healthz` - Проверка здоровья
|
||||
- `GET /readiness` - Готовность к работе
|
||||
- `GET /docs` - Swagger документация
|
||||
- `POST /api/v1/generate_email` - Генерация письма
|
||||
|
||||
### Формат запроса
|
||||
|
||||
**Обязательные поля:**
|
||||
```json
|
||||
{
|
||||
"contact": "string",
|
||||
"position": "string",
|
||||
"company_name": "string",
|
||||
"segment": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Полный формат:**
|
||||
```json
|
||||
{
|
||||
"contact": "Помящий Никита",
|
||||
"position": "Технический директор",
|
||||
"company_name": "FIVE",
|
||||
"segment": "маркетинговое агентство",
|
||||
"email": "nikita@five.agency",
|
||||
"locale": "ru",
|
||||
"notes": "Дополнительная информация"
|
||||
}
|
||||
```
|
||||
|
||||
### Формат ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"subject": "Как упростить работу с самозанятыми в FIVE?",
|
||||
"body": "Здравствуйте, Никита!....",
|
||||
"meta": {
|
||||
"locale": "ru",
|
||||
"lead_normalized": {
|
||||
"contact_name": "Помящий Никита",
|
||||
"contact_first_name": "Никита",
|
||||
"contact_last_name": "Помящий",
|
||||
"role_title": "Технический директор",
|
||||
"role_category": "tech",
|
||||
"company_name": "FIVE",
|
||||
"industry_segment": "маркетинговое агентство",
|
||||
"industry_tag": "marketing_agency",
|
||||
"email": null,
|
||||
"locale": "ru",
|
||||
"notes": null
|
||||
},
|
||||
"used_chunks": [
|
||||
"sds_podkluchenie_k_konsoli#sds_podkluchenie_k_konsoli#c7",
|
||||
"vysotnik_rental#vysotnik_rental#c2"
|
||||
],
|
||||
"model": "gpt-4o",
|
||||
"tokens_prompt": 1132,
|
||||
"tokens_completion": 289,
|
||||
"guardrails_violations": 0,
|
||||
"context_chunks_used": 5,
|
||||
"context_quality_score": 0.87
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Структура meta:**
|
||||
- `locale` - Язык, на котором сгенерировано письмо (например, ru)
|
||||
- `lead_normalized` - Объект с нормализованной и обогащенной информацией о лиде:
|
||||
- `contact_first_name/contact_last_name` - Распознанные имя и фамилия
|
||||
- `role_category/industry_tag` - Машинно-читаемые теги для должности и сегмента компании (например, tech, marketing_agency)
|
||||
- `used_chunks` - Массив с ID фрагментов из базы знаний, которые были использованы для генерации ответа
|
||||
- `model` - Использованная LLM модель
|
||||
- `tokens_prompt/tokens_completion` - Расход токенов на запрос и ответ для мониторинга затрат
|
||||
- `guardrails_violations` - Количество нарушений правил безопасности (guardrails). 0 означает, что все проверки пройдены
|
||||
- `context_chunks_used` - Общее количество фрагментов контекста, которые были использованы для генерации
|
||||
- `context_quality_score` - Оценка релевантности найденного контекста (0-1):
|
||||
- 1.0 - отличное качество контекста
|
||||
- 0.8+ - хорошее качество (высокая релевантность)
|
||||
- 0.6+ - приемлемое качество (достаточная релевантность)
|
||||
- <0.6 - низкое качество (слабая релевантность)
|
||||
|
||||
## Конфигурация
|
||||
|
||||
### Переменные окружения
|
||||
|
||||
| Параметр | Описание | По умолчанию |
|
||||
|----------|----------|--------------|
|
||||
| `LLM_PROVIDER` | openai или gemini | openai |
|
||||
| `LLM_MODEL` | Модель генерации | gpt-4o |
|
||||
| `EMBEDDING_MODEL` | Модель векторизации | text-embedding-3-large |
|
||||
| `TOP_K` | Чанков для поиска | 30 |
|
||||
| `TOP_N_CONTEXT` | Чанков в контексте | 6 |
|
||||
| `CHUNK_SIZE` | Размер чанка (токены) | 500 |
|
||||
| `CHUNK_OVERLAP` | Перекрытие чанков | 100 |
|
||||
|
||||
## Мониторинг
|
||||
|
||||
### Качество контекста
|
||||
|
||||
Метрика `context_quality_score` вычисляется на основе:
|
||||
- **Средний similarity score** (40%) - релевантность найденных кейсов
|
||||
- **Доля высококачественных chunks** (25%) - процент кейсов с similarity > 0.7
|
||||
- **Консистентность результатов** (20%) - равномерность качества chunks
|
||||
- **Фактор количества** (15%) - достаточность объема контекста
|
||||
|
||||
**Интерпретация для мониторинга:**
|
||||
- `context_quality_score < 0.5` - критически низкое качество, требует обновления базы знаний
|
||||
- `context_quality_score < 0.7` - предупреждение о качестве контекста
|
||||
- `context_quality_score >= 0.8` - хорошее качество генерации
|
||||
|
||||
### Логи
|
||||
|
||||
Все запросы логируются в JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "1641234567890",
|
||||
"method": "POST",
|
||||
"url": "http://localhost:8000/api/v1/generate_email",
|
||||
"status_code": 200,
|
||||
"process_time": 2.341
|
||||
}
|
||||
```
|
||||
|
||||
### Проверка состояния
|
||||
|
||||
```bash
|
||||
# Статус сервиса
|
||||
curl http://localhost:8000/healthz
|
||||
|
||||
# Статистика базы знаний
|
||||
curl -H "Authorization: Bearer secret" \
|
||||
http://localhost:8000/api/v1/admin/knowledge-base/stats
|
||||
|
||||
# Docker логи
|
||||
docker-compose logs -f ai-email-assistant
|
||||
```
|
||||
|
||||
## Устранение ошибок
|
||||
|
||||
### Частые проблемы
|
||||
|
||||
**404 No relevant knowledge found**
|
||||
```bash
|
||||
# Загрузите базу знаний
|
||||
curl -X POST -H "Authorization: Bearer secret" \
|
||||
"http://localhost:8000/api/v1/admin/ingest"
|
||||
```
|
||||
|
||||
**502 External service error**
|
||||
- Проверьте API ключи LLM провайдера в .env
|
||||
|
||||
**400 Validation failed**
|
||||
- Убедитесь что все обязательные поля заполнены
|
||||
|
||||
## Обновление базы знаний
|
||||
|
||||
### Добавление кейсов
|
||||
|
||||
1. Поместите `.md` файлы в `data`
|
||||
2. Файлы должны содержать:
|
||||
- Заголовки для структуры
|
||||
- Числовые метрики
|
||||
- Ключевые слова индустрии
|
||||
- Упоминания ролей
|
||||
|
||||
3. Дополните базу (инкрементально):
|
||||
```bash
|
||||
curl -X POST -H "Authorization: Bearer secret" \
|
||||
"http://localhost:8000/api/v1/admin/ingest"
|
||||
```
|
||||
4. (альтернативно) Пересоздайте базу:
|
||||
```bash
|
||||
curl -X POST -H "Authorization: Bearer secret" \
|
||||
"http://localhost:8000/api/v1/admin/ingest?recreate=true"
|
||||
```
|
||||
|
||||
### Формат кейсов
|
||||
|
||||
```markdown
|
||||
# Кейс компании FIVE
|
||||
|
||||
Маркетинговое агентство автоматизировало работу с подрядчиками.
|
||||
|
||||
## Результаты
|
||||
- Онбординг: с 2 дней до 15 минут
|
||||
- Снижение ошибок: на 95%
|
||||
- Выплаты: мгновенные
|
||||
|
||||
Технический директор Никита отмечает эффективность.
|
||||
```
|
||||
|
||||
## Тестирование
|
||||
|
||||
```bash
|
||||
# Все тесты
|
||||
pytest src/tests/
|
||||
|
||||
# Только API
|
||||
pytest src/tests/test_api.py
|
||||
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue