GenAudioBookInfo/wiki/OpenRouter.md

OpenRouter (LLM интеграция)

GenAudioBookInfo поддерживает опциональную нормализацию метаданных через LLM с помощью OpenRouter — унифицированного API-шлюза к сотням AI-моделей.

---

Зачем нужно LLM

Теги в аудиофайлах и имена папок часто содержат:

• Инициалы вместо полного имени: Акунин Б. → Акунин Борис
• Неправильный порядок: Борис Акунин → Акунин Борис
• Лишние символы, транслитерацию, опечатки
• Номера серий и части в названии

LLM нормализует автора в формат Фамилия Имя и очищает название книги.

---

Настройка

1. Получить API ключ

Зарегистрируйтесь на openrouter.ai и создайте API ключ в личном кабинете.

2. Добавить в config.yaml

openrouter:
  api_key: sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
  model: openai/gpt-4o-mini

Или через переменную окружения

export OPENROUTER_API_KEY=sk-or-v1-xxxx
./genaudiobookinfo

Переменная OPENROUTER_API_KEY проверяется если api_key в конфиге пуст.

---

Настройки в config.yaml

openrouter:
  api_key: sk-or-v1-xxxx         # API ключ (или env OPENROUTER_API_KEY)
  base_url: https://openrouter.ai/api/v1
  timeout: 30s                   # Таймаут HTTP запроса
  model: openai/gpt-4o-mini       # Идентификатор модели
  max_retries: 3                  # Ретраи при ошибках API
  retry_backoff: 2s               # Начальная задержка backoff
  retry_backoff_max: 30s          # Максимальная задержка backoff
  prompt: |                       # Системный промпт
    Ты эксперт по русскоязычным аудиокнигам...

---

Промпт

Промпт определяет, как LLM должна обработать метаданные. Требования к промпту:

1. Отвечать только JSON без дополнительного текста.
2. Формат ответа: {"author": "Фамилия Имя", "title": "Название"}.
3. Автор в формате Фамилия Имя (не инициалы).

Пример промпта

prompt: |
  Ты эксперт по русскоязычным аудиокнигам.
  Тебе дадут сырые данные об аудиокниге (автор и название).
  Твоя задача — нормализовать их:
  1. Автор: формат "Фамилия Имя" (полное имя, без инициалов)
  2. Название: убрать номера частей, лишние скобки, год
  Верни ответ строго в JSON формате:
  {"author": "Фамилия Имя", "title": "Чистое название"}
  Только JSON, никакого лишнего текста.

---

Выбор модели

OpenRouter предоставляет доступ к сотням моделей.
Формат: provider/model-name.

Рекомендуемые модели для нормализации текста:

Модель	Стоимость	Качество
openai/gpt-4o-mini	низкая	хорошее
openai/gpt-4o	средняя	отличное
anthropic/claude-3-haiku	низкая	хорошее
google/gemini-flash-1.5	очень низкая	хорошее
meta-llama/llama-3.1-8b-instruct:free	бесплатно	среднее

Полный список: openrouter.ai/models

---

Поведение при ошибках

Ситуация	Действие
API ключ не задан	LLM выключен, книга обрабатывается с исходными тегами
Ошибка HTTP	Ретрай до max_retries раз с backoff
Невалидный JSON в ответе	WARN в лог, используются исходные теги
Пустые поля в ответе	LLM результат игнорируется, используются исходные теги
Таймаут запроса	WARN в лог, используются исходные теги

LLM-ошибки не прерывают обработку книги — конвейер продолжается с оригинальными данными.

---

Архитектура интеграции

usecase/scan_audiobooks.go
    │
    ▼ (если llmClient != nil)
domain.LLMClient.NormalizeMetadata(rawAuthor, rawTitle)
    │
    ▼
infrastructure/openrouter_client.go
    OpenRouterClient.NormalizeMetadata()
    │
    ├── HTTP POST /chat/completions
    │   Authorization: Bearer <api_key>
    │   {"model": "...", "messages": [...]}
    │
    └── разбор JSON {"author": "...", "title": "..."}

LLMClient — интерфейс в domain/llm.go. Легко заменить на любой другой LLM провайдер.