Skip to content

API_REQUIREMENTS.md

Latest commit

 

History

History
63 lines (45 loc) · 5.24 KB

API_REQUIREMENTS.md

File metadata and controls

63 lines (45 loc) · 5.24 KB

Документ вимог до API та ШІ-архітектури (v1.3)

1. Вступ

Цей документ визначає вимоги до інтеграції Google Gemini API та внутрішнього сервісу geminiService.ts для проекту "Інклюзивна мапа соціальних послуг України". Він слугує технічним завданням для забезпечення високої якості інтелектуальних послуг та інклюзивності інтерфейсу.

2. Функціональні вимоги (Functional Requirements)

2.1. Персоналізація ШІ "Пані Думка"

  • Психотип: Модель має дотримуватися образу мудрої, емпатичної української жінки.
  • Мова: Виключно українська з використанням теплих звертань ("серденько", "сонечко", "рідненькі").
  • Тон: Заспокійливий, підтримуючий, але професійний у питаннях надання допомоги.

2.2. Пошукове заземлення (Grounding)

  • Google Search: Обов'язкова перевірка актуальності контактів фондів та пошук останніх новин про гуманітарні коридори через інструмент googleSearch.
  • Google Maps: Використання googleMaps для візуалізації маршрутів до прихистків та підтвердження їхнього реального розташування.
  • Прозорість джерел: Всі фактичні твердження ШІ повинні супроводжуватися посиланнями з groundingChunks.

2.3. Мультимодальність та Live API

  • Real-time Voice: Забезпечення двосторонньої голосової взаємодії через Gemini Live API з мінімальною затримкою (до 500мс).
  • TTS (Text-to-Speech): Використання моделі gemini-2.5-flash-preview-tts з жіночим голосом для озвучування текстових відповідей.
  • Transcription: Автоматична транскрипція вводу користувача для людей з порушеннями мовлення або слуху.

2.4. Складні міркування (Deep Thinking)

  • Аналіз кейсів: Для складних запитів (наприклад, "як перевезти лежачу особу з прифронтової зони") використовувати модель gemini-3-pro-preview з активованим thinkingBudget.

3. Нефункціональні вимоги (Non-Functional Requirements)

3.1. Продуктивність (Performance)

  • Час відгуку: Генерація тексту — не більше 2 секунд для Flash-моделей.
  • Стрімінг: Обов'язкове використання generateContentStream для відображення відповіді в реальному часі.

3.2. Безпека (Security)

  • API Key: Ключ доступу має бути ізольований у process.env.API_KEY. Будь-яке виведення ключа в консоль або UI заборонено.
  • Конфіденційність: Голосові дані не повинні зберігатися на сервері після завершення сесії.

3.3. Доступність (Accessibility)

  • WCAG Compliance: Відповіді ШІ мають бути структурованими (Markdown) для коректної роботи екранних читців (Screen Readers).
  • Voice-first UI: Можливість повного керування пошуком допомоги виключно голосом.

3.4. Масштабованість та Надійність

  • Rate Limiting: Реалізація черги запитів та експоненціальної затримки (exponential backoff) при помилках 429.
  • Fallback: У разі відмови Live API система має автоматично перемикатися на текстовий чат без втрати контексту.

4. Конфігурація моделей

Завдання Рекомендована модель
Базовий пошук та чат gemini-3-flash-preview
Аналітика та верифікація gemini-3-pro-preview
Голосовий режим (Live) gemini-2.5-flash-native-audio-preview-12-2025
Озвучування тексту (TTS) gemini-2.5-flash-preview-tts

5. Документація та підтримка

  • Всі зміни в логіці API мають відображатися в файлах API_DESIGN.md та API_OPERATIONS.md.
  • Юридичні обмеження використання даних описані в API_LEGAL_NOTICE.md.