Skip to content

API_OPERATIONS.md

Latest commit

 

History

History
78 lines (56 loc) · 5.13 KB

API_OPERATIONS.md

File metadata and controls

78 lines (56 loc) · 5.13 KB

Специфікація операцій та логіки API (v1.0)

Цей документ визначає технічні операції, які виконує geminiService.ts, включаючи протоколи вводу-виводу та алгоритми трансформації даних.

1. Операція: analyzeData (Інтелектуальний аналіз та пошук)

Призначення: Основний метод для обробки запитів користувача, що використовує контекст бази даних та інструменти заземлення (Grounding).

Вхідні дані Тип Опис
query string Текст запиту користувача українською мовою.
organizations Organization[] Масив об'єктів організацій, відфільтрований за регіоном.
userLocation {lat, lng} (Опційно) Координати користувача для Google Maps.
useThinking boolean Прапор активації режиму глибоких міркувань.

Логіка трансформації (Internal Logic):

  1. Аналіз наміру: Система шукає ключові слова ("перевір", "актуально") для вибору моделі gemini-3-pro-preview (якщо потрібна верифікація) або gemini-3-flash-preview (для швидких відповідей).
  2. Формування контексту: Масив organizations (до 5200 точок) агрегується у коротке резюме: "У списку X організацій. Категорії: Y, Z.".
  3. Вибір інструментів (Tools):
    • Якщо запит про локацію: підключається googleMaps.
    • Якщо запит про верифікацію: підключається googleSearch.
  4. Вихід: Об'єкт AnalyzeResult, що містить згенерований текст та масив посилань на джерела.

2. Операція: generateSpeech (Голосове відтворення)

Призначення: Перетворення тексту у мовлення з емоційним забарвленням пані Думки.

Вхідні дані Трансформація Вихідні дані
Текст (UTF-8) Додавання тегу [EMOTIONAL STYLE: Warm...] + запит до моделі TTS ArrayBuffer (Raw PCM 24kHz, 16-bit)

Технічні параметри:

  • Модель: gemini-2.5-flash-preview-tts.
  • Голос: Kore (оптимізовано під жіночий вокал).
  • Обробка: Декодування Base64 -> Перетворення у Uint8Array -> Отримання бінарного буфера для Web Audio API.

3. Операція: LiveSession (Потоковий діалог)

Призначення: Забезпечення двостороннього голосового зв'язку в реальному часі.

Схема передачі даних (Data Pipeline):

  1. Вхід (Input): Захоплення аудіо з getUserMedia.
  2. Трансформація вводу:
    • Float32Array (Microphone) -> Int16Array (PCM).
    • Енкапсуляція в Base64.
    • Відправка через WebSocket: mimeType: 'audio/pcm;rate=16000'.
  3. Обробка виводу:
    • Отримання чанків Base64 від моделі.
    • Декодування PCM.
    • Планування відтворення через nextStartTime для усунення розривів (gapless playback).

4. Операція: getIntelligentSummary (Агрегація даних)

Призначення: Створення швидкого огляду можливостей допомоги у вибраному радіусі.

Алгоритм:

  1. Відбір ТОП-20 найбільш релевантних організацій з поточного фільтра.
  2. Трансформація об'єктів у рядок: Назва (Категорія): Послуги;.
  3. Запит до моделі з інструкцією виділити найважливіше для людини в скруті.
  4. Вихід: Текст у стилі "Парада від пані Думки".

5. Обробка помилок та верифікація

Сценарій Дія API Трансформація даних
Помилка 429 Retry logic Експоненціальна затримка (2s -> 4s -> 8s)
Відсутність API Key Блокування викликів Повернення статичного повідомлення про помилку
Порожній контекст Grounding Перемикання на чистий Google Search без локальних даних