client-bot /api/ask

Назначение

Ответ на вопрос по базе знаний (Ollama embeddings, Z.ai glm-5, pgvector). Используется talkiq вместо эха. База знаний: BIZZUP, Битрикс24.

Метод

POST http://127.0.0.1:17090/api/ask

Внешний доступ не проксируется. Вызов с внутренних сервисов (talkiq).

Параметры

Поле	Тип	Где	Описание
`question`	string	body JSON	Вопрос (обязательно, до 500 символов)
`mascot`	string	body JSON	Опционально. Хэлпи, Юни, Коттапыч, Пиля — ответ от его лица
`user_name`	string	body JSON	Опционально. Имя для обращения по имени
`messages`	array	body JSON	Опционально. История диалога [{role, content}]. Сессия 6 ч, окно 2 дня
`persona_info`	object	body JSON	Опционально. Данные подписчика (клиника, должность, цели) для персонификации
`access_ids`	array int	body JSON	Опционально. Права доступа (permission_id). Книга продаж и edu — при 2,3,4,5

Ответ

Поле	Тип	Описание
`answer`	string	Текст ответа (пустой при out_of_topic)
`cost`	float	Оценка стоимости Z.ai (USD, по токенам)
`out_of_topic`	bool	true — нет релевантных чанков или «нет информации». talkiq показывает «Упс, это не моя тема!» с кнопками [Да] [Нет]
`suggested_buttons`	array string	2–4 варианта (до 40 символов, короткие фразы без скобок). Удаляется при нажатии или продолжении диалога.
`suggest_manager`	bool	true — маркер [MANAGER_BUTTON] в ответе. talkiq показывает кнопку «📞 Позвать менеджера»

Ограничения

Rate limit: 60 RPM, burst 10. Внутренние IP — без лимитов.

Пример запроса (Python)

import requests

url = 'http://127.0.0.1:17090/api/ask'
body = {'question': 'Что такое Битрикс24?', 'mascot': 'Коттапыч'}  # mascot опционально
response = requests.post(url, json=body, timeout=45)
data = response.json()
print(data['answer'], data['cost'])

Интеграция talkiq

В talkiq/.env: CLIENT_BOT_API_ADDR=http://127.0.0.1:17090. Текстовые сообщения отправляются в /api/ask. talkiq передаёт mascot, user_name, messages, persona_info, access_ids (из subscribed_users). При out_of_topic — «Упс, это не моя тема!» и кнопки [Да] [Нет]. При suggest_manager — кнопка «Позвать менеджера»; саммари через POST /api/summarize_request.