Подготовить AI Lead Processor и проверить обработку заявок
This commit is contained in:
Stvponya committed
commit
634490174f
22 files changed
+1812
No files matched your search
@@ -0,0 +1,108 @@
|
||||
# AI Lead Processor
|
||||
|
||||
В ремонтной компании менеджер читает все обращения с сайта по очереди. Пока он готовит ответ на вопрос о цене, в почте может ждать сообщение о протечке. AI Lead Processor помогает оценить срочность при чтении обращения и подготовить ответ. Менеджер проверяет результат, сохраняет его в журнал и сам связывается с клиентом.
|
||||
|
||||
- Три категории с объяснением решения. Срочные обращения выделены красным, обычные зелёным, спам серым.
|
||||
- Редактирование категории и черновика перед записью. Спам сохраняется с пустым ответом.
|
||||
- Локальная история в Excel, скачивание книги и калькулятор экономии времени.
|
||||
- **REAL AI** обращается к OpenAI. **DEMO** работает локально по правилам и показывает тот же процесс проверки.
|
||||
|
||||
|
||||
|
||||
## Быстрый запуск
|
||||
|
||||
Требуются Git и Python 3.11 или новее. Выполните команды из корня проекта. Активация окружения необязательна.
|
||||
|
||||
**Windows PowerShell**
|
||||
|
||||
```powershell
|
||||
py -3.12 -m venv .venv
|
||||
.\.venv\Scripts\python -m pip install -r requirements.txt
|
||||
Copy-Item .env.example .env
|
||||
.\.venv\Scripts\python -m streamlit run app.py --server.address localhost
|
||||
```
|
||||
|
||||
Если установлен Python 3.11, замените `-3.12` на `-3.11`. Копировать пример нужно только при первом запуске.
|
||||
|
||||
**Linux / macOS**
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
.venv/bin/python -m pip install -r requirements.txt
|
||||
cp -n .env.example .env
|
||||
.venv/bin/python -m streamlit run app.py --server.address localhost
|
||||
```
|
||||
|
||||
Откройте [локальное приложение](http://localhost:8501). Для первого знакомства выберите **DEMO**. Введите пример ниже, нажмите «Обработать заявку», проверьте черновик и нажмите «Подтвердить и сохранить». Книга `data/processed_leads.xlsx` создаётся автоматически. После перезапуска история читается с диска.
|
||||
|
||||
## Настройка и ручная проверка REAL AI
|
||||
|
||||
В локальном `.env` укажите собственный ключ и доступную вашему проекту модель с поддержкой Responses API и структурированного вывода. Пример формата:
|
||||
|
||||
```dotenv
|
||||
OPENAI_API_KEY=your_api_key_here
|
||||
OPENAI_MODEL=gpt-5-mini
|
||||
```
|
||||
|
||||
Храните ключ локально. Публиковать его в репозитории или показывать во время демонстрации нельзя. После изменения файла перезапустите Streamlit. Переменные среды имеют приоритет над файлом.
|
||||
|
||||
1. Выберите REAL AI и обработайте синтетическое сообщение о протечке. Запрос расходует средства API-проекта. Проверьте категорию, объяснение и подтверждение получения без обещания времени приезда.
|
||||
2. Сверьте режим, модель и токены с результатом. Подтвердите запись, скачайте книгу и проверьте соответствующую строку. При неизвестном тарифе или отсутствии счётчиков оценка стоимости остаётся пустой.
|
||||
3. Повторите для вопроса о стоимости и рекламного предложения. Проверьте, что ответ не содержит выдуманной цены, а у спама отсутствует черновик. При ручной смене спама на целевую заявку заполните ответ.
|
||||
4. В отдельном запуске без ключа выберите REAL AI. Должно появиться сообщение о настройке ключа. Переключиться на DEMO можно вручную.
|
||||
|
||||
Отключение gpt-5-mini запланировано на 11 декабря 2026 года. Для дальнейшего пилота замените модель через OPENAI_MODEL, проверьте качество на контрольной выборке и обновите тариф в модуле экономики. [График отключений OpenAI](https://developers.openai.com/api/docs/deprecations)
|
||||
|
||||
## Примеры входа и результата
|
||||
|
||||
| Синтетическая заявка | Категория DEMO | Что увидит менеджер |
|
||||
|---|---|---|
|
||||
| Из стиральной машины течет вода. | Срочно | Причина со ссылкой на признак протечки и черновик с подтверждением получения |
|
||||
| Сколько стоит ремонт стиральной машины? | Не срочно | Уточнение марки, модели и неисправности |
|
||||
| Зарабатывайте миллион рублей за неделю, переходите по ссылке | Спам | Объяснение и пустой черновик |
|
||||
|
||||
Полная выборка включает неоднозначные случаи, попытку навязать категорию и пустой ввод. Ожидаемые категории заданы по правилам кейса. [Тестовые заявки](samples/sample_leads.csv)
|
||||
|
||||
## Архитектура
|
||||
|
||||
`app.py` принимает текст длиной от 1 до 4 000 символов. Модуль `src/llm_service.py` выбирает локальные правила или передаёт текст отдельным пользовательским сообщением в Responses API. Схема `src/schemas.py` задаёт допустимые поля и категории. Ответ и UUID операции хранятся в текущей сессии до подтверждения.
|
||||
|
||||
Менеджер видит исходную оценку и редактирует итог. Модуль `src/storage.py` под блокировкой добавляет строку в книгу через временный файл. Повтор того же сохранения распознаётся по UUID. Отдельная повторная обработка одинакового текста считается новой заявкой. Строки записываются с текстовым типом Excel, включая текст, начинающийся со знака равенства. `src/economics.py` рассчитывает время и оценочную стоимость.
|
||||
|
||||
## Экономический эффект
|
||||
|
||||
Иллюстративный сценарий на 120 обращений в неделю при 4 минутах вручную и 1,5 минуты с проверкой даёт 8 и 3 часа соответственно. Высвобождаются 5 часов в неделю. При 500 ₽/ч их оценка составляет 2 500 ₽. При допущении 600 входных и 250 выходных токенов один стандартный запрос стоит около $0,00065. [Допущения, формулы и тариф](docs/economics.md)
|
||||
|
||||
## Ограничения пилота
|
||||
|
||||
Менеджер переносит текст с сайта вручную. Обновление вкладки сбрасывает неподтверждённый результат. Excel рассчитан на небольшой локальный журнал, с доступом на уровне папки. Закройте книгу в настольном Excel перед записью. Для пилота назначьте владельца журнала и согласуйте резервное копирование, срок хранения и передачу обезличенного текста внешнему сервису. Проверку качества реальной модели и замеры времени проводят на пилоте.
|
||||
|
||||
## Проверка
|
||||
|
||||
В том же окружении выполните:
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python -m pytest -q
|
||||
```
|
||||
|
||||
На Linux/macOS используйте `.venv/bin/python -m pytest -q`. Тесты используют временные книги и моки API. Доля правильных ответов модели на реальных обращениях измеряется отдельно.
|
||||
|
||||
## Материалы тестового задания
|
||||
|
||||
- [Процессы до и после внедрения](docs/processes.md)
|
||||
- [План пилота и три бизнес-риска](docs/implementation_plan.md)
|
||||
- [Расчёт экономического эффекта](docs/economics.md)
|
||||
- [Журнал разработки и проверок](docs/ai_work_log.md)
|
||||
- [Исходное техническое задание](docs/assignment.md)
|
||||
|
||||
## Самостоятельная публикация в Gitea
|
||||
|
||||
Локальный проект уже содержит ветку `main`. Перед первой публикацией создайте пустой репозиторий `ai-lead-processor` в Gitea и скопируйте его адрес клонирования. В PowerShell выполните:
|
||||
|
||||
```powershell
|
||||
git status --short --branch
|
||||
git remote add origin (Read-Host 'Введите URL репозитория Gitea')
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Если `origin` уже настроен, сверьте адрес через `git remote get-url origin` и пропустите добавление remote. После публикации откройте README и схемы в Gitea с включённой поддержкой Mermaid.
|
||||
Reference in new issue
Block a user