MPS — інформаційний чат-бот шкільного округу
AI-асистент відповідає працівникам і родинам на запитання про Millard Public Schools (Омаха, Небраска), використовуючи лише опубліковані сайти й документи округу.
Про проєкт
- Командний проєкт для Millard Public Schools District Office із системою пошуку та оцінювання відповідей. Близько 98 000 індексованих фрагментів сайтів, PDF, файлів Drive і календарів. Повторна збірка після завантаження — однією командою.
- Гібридний векторний пошук і BM25, розділи за школами, LLM-переранжування, відповіді з джерелами та перевірка фактів. Бот відповідає «не знаю», замість того щоб вгадувати.
- 162 тестові запитання з триразовою оцінкою LLM-суддею та обліком витрат. A/B-тест обрав переранжувальник із тією самою виміряною якістю, приблизно на 9% дешевший і вдвічі швидший.
Контекст
Командний проєкт для реального замовника — Millard Public Schools District Office. Інформація округу розміщена на 44 сайтах округу та шкіл, у PDF, файлах Google Drive, Google Sites і вбудованих календарях. Працівники не могли швидко знайти відповіді, а універсальний чат-бот міг їх вигадати.
Завдання — відповідати за власними джерелами округу, посилатися на них і казати «не знаю», коли відповіді немає.
Відтворювана обробка даних
- Краулер обходить сайти округу, шкіл і партнерських організацій. Автоматично пропускає сторінки «не знайдено», форми входу, кошики й помилки браузера.
- Вебсторінки перетворюються на чистий Markdown. Частотний фільтр прибирає навігацію без жорстких правил для окремих макетів.
- Підтримуються цифрові й скановані PDF: модель комп’ютерного зору розпізнає скани посторінково. Також обробляються файли Google Drive і Docs, документи Office та зображення.
- Повторювані події Google Calendar розгортаються в реальні дати навчального року з урахуванням свят, перенесень і скасувань.
- Парсери формують довідники працівників, картки шкіл, політики й дані про кількість учнів. Кількість перевіряється за підсумками вихідного звіту до запису.
- Після повторного завантаження все перебудовується однією командою без ручних виправлень. У ChromaDB зберігається близько 98 000 фрагментів із text-embedding-3-large, поряд — лексичний індекс BM25.
Пошук і відповіді
- Класифікатор визначає школу або кілька шкіл, обмеження джерел на кшталт «лише в PDF», запити повних списків і звичайну розмову. Переформулювання створює кілька варіантів пошуку.
- Векторний пошук і BM25 виконуються окремо для кожної школи, щоб невеликі школи не губилися. Критично важливі результати, наприклад власний довідник школи, оминають переранжувальник.
- LLM-переранжувальник фільтрує кандидатів, після чого генерується відповідь із посиланнями. Фінальна перевірка звіряє кожен факт чернетки з джерелами та виправляє непідтверджене.
- Запитання «перелічи всі X» використовують сформовані довідники замість неповних результатів пошуку. Для великих списків спочатку пропонується обрати категорію.
Без здогадок
Три рівні захищають від вигаданих відповідей:
- Відмова на етапі пошуку, якщо нічого релевантного не знайдено.
- Правило в промпті, що забороняє висновки поза межами джерел.
- Самоперевірка, яка звіряє факти з джерелами.
Опублікований розклад подається саме як розклад, а не як фактичний стан будівель.
Оцінювання й контроль витрат
- Власний набір зі 162 запитань. Кожну відповідь LLM-суддя оцінює тричі; зберігаються історія запусків і вартість кожного запитання.
- Між повними запусками перевіряється кілька окремих запитань, щоб заощаджувати бюджет API.
- Власний лічильник обгортає кожен API-клієнт і враховує токени й вартість у доларах для кожного кроку діалогу та етапу обробки. Ціни зберігаються в JSON-конфігурації. Невідома вартість записується як невідома, а не як $0.
- A/B-тест альтернативного переранжувальника через OpenRouter Decisions API показав ту саму якість за приблизно на 9% нижчої вартості й удвічі вищої швидкості. Цей варіант залишили.
Поточний стек: мова й тестування
- Python 3 для бекенду, обробки даних і системи оцінювання відповідей.
- pytest: близько 1 600 тестів; приблизно 110 тестових файлів перевіряють чисті функції обробки даних без мережевих запитів і викликів моделей. Модульні тести Node перевіряють JavaScript вебпанелі.
Збір і перетворення даних
- Selenium з undetected-chromedriver запускає справжній Chrome для обходу сайтів. curl_cffi завантажує документи з TLS-відбитком Chrome.
- BeautifulSoup і lxml розбирають HTML, потім markdownify перетворює його на Markdown.
- pypdf витягує текст PDF. PyMuPDF перетворює скановані сторінки на зображення для розпізнавання моделлю комп’ютерного зору.
- python-docx і openpyxl обробляють документи Office.
- Під час розбору iCal використовується python-dateutil для розгортання RRULE і zoneinfo/tzdata для часових поясів.
Стек пошуку
- ChromaDB — локальне постійне векторне сховище приблизно 98 000 фрагментів з ембеддингами text-embedding-3-large.
- Лексичний індекс BM25 написаний з нуля, без зовнішньої бібліотеки BM25.
- Гібридний пошук об’єднує векторні результати й BM25, виконуючи окремі запити для кожної школи.
Бекенд та інтерфейс
- Flask із Server-Sent Events передає відповіді, етапи обробки й використання токенів у реальному часі. Панель також має підказки наступних запитань і картку витрат для кожного чату.
- Фронтенд написано на звичайному JavaScript без фреймворку; marked.js відображає Markdown.
- SQLite зберігає історію чатів і журнал перевірки повідомлень. В інтерфейсі є адмінпанель, дашборд оцінювання та розділ Browse.
Моделі та їхні ролі
- GPT-6 Luna (OpenAI): модель за замовчуванням для генерації відповідей, класифікації запитів, переранжування й самоперевірки. Модель і рівень міркування налаштовуються окремо для кожного етапу.
- Claude Haiku 5.5 (Anthropic Messages API): альтернативна чат-модель, яку можна обрати в панелі через адаптер із тим самим інтерфейсом.
- text-embedding-3-large (OpenAI): ембеддинги для пошуку.
- GPT-5.6 Luna: посторінкове розпізнавання сканованих PDF, файлів Drive, зображень і вкладень календаря.
- Jev 1.13 через OpenRouter Decisions API: суддя переранжування, класифікатор типів повідомлень і додаткова фонова перевірка фактів. Модель відповідає на одне запитання «так/ні» щодо кожного фрагмента й ухвалює рішення за ймовірністю. В A/B-тесті проєкту альтернативний переранжувальник показав якість чат-моделі за приблизно на 9% нижчої вартості й удвічі вищої швидкості.
- GPT-5.6 Luna: суддя оцінювання відповідей, по три голоси на відповідь. Модель судді зафіксована, щоб порівнювати запуски під час зміни основної моделі бота.
- Локальна модель Qwen через Ollama: структуроване витягування довідника програм без витрат на API.
Як змінювався вибір моделей
Проєкт почався до виходу GPT-6 Luna. Згодом тести показали нижчу вартість у цій системі, після чого на неї перейшли.
Потім я обрав Haiku 5.5 для чату. Claude мені звичніший, а в моїх запусках Haiku працювала приблизно вдвічі швидше за порівнянної з Luna вартості. Це порівняння стосується завдань цього проєкту.