Управление моделями

В разделе «Настройки → Модели» можно добавлять диалоговые, векторные, реранкинговые, визуальные и голосовые модели, которые затем используются базами знаний или агентами. Локальные модели Ollama и удаленные модели можно комбинировать, например: использовать локальную модель для создания векторов и удаленную для генерации ответов.

При добавлении модели следует проверить настройки подключения и совместимость индексов:

• Смена векторной модели требует перестроения индекса. Модель определяет семантическое пространство и размерность векторов, старые и новые векторы нельзя смешивать напрямую;
• Тестирование подключения перед сохранением. Убедитесь в доступности адреса сервиса, учетных данных и имени модели, прежде чем использовать ее в базах знаний или агентах.

Типы моделей, поля конфигурации и статус использования можно проверить согласно следующим инструкциям.

Выбор типа модели

Тип	Назначение
Диалоговая модель	Генерация ответов на вопросы, аннотаций и логический вывод для агентов
Векторная модель	Преобразование документов и запросов в векторы для семантического поиска
Модель реранкинга (rerank)	Переупорядочивание извлеченных фрагментов
Визуальная модель	Распознавание изображений в документах или диалогах
Голосовая модель	Преобразование аудио в текст

Добавление и проверка подключения

При добавлении модели сначала выберите тип и источник: «API» для удаленных сервисов, «Ollama» для локальных моделей (модели реранкинга не поддерживают Ollama). Удаленные модели настраиваются по следующим шагам:

1. Выберите поставщика. В списке отображаются только производители, поддерживающие выбранный тип модели, после выбора можно перейти на их документацию. При отсутствии нужного поставщика выберите «Пользовательский (совместимый с OpenAI интерфейс)».
2. Введите имя модели. Можно выбрать из встроенного каталога поставщика (оторгаются контекстное окно, размерность векторов, возможности рассуждения и зрения) или ввести имя вручную. При выборе из каталога незаполненные поля контекстного окна, максимального числа выходных токенов, поддержки зрения и размерности векторов заполняются автоматически.
3. Укажите Base URL и API Key, а также дополнительные поля, требуемые поставщиком (см. Дополнительные поля поставщиков). При необходимости доступа через корпоративный шлюз можно добавить пользовательские заголовки запроса.
4. Проверьте «Фактический способ вызова». Для диалоговых и визуальных моделей в реальном времени отображаются протокол запроса, источник возможностей (встроенный профиль или стандартные настройки поставщика), адрес запроса, параметры переключателя рассуждений, доступная интенсивность рассуждений, контекстное окно и максимальное число выходных токенов для подтверждения перед сохранением.
5. Проверьте подключение и сохраните. Тест использует данные из текущей формы без предварительного сохранения; при редактировании существующей модели для API Key используется ранее сохраненное значение. Если после теста настройки были изменены, проверку нужно повторить.

В «Расширенных настройках» также можно настроить:

Настройка	Применимый тип	Описание
Размерность векторов / Настраиваемая размерность вывода	Векторная	Размерность должна соответствовать индексу. Включайте «Настраиваемую размерность вывода» только при подтвержденной поддержке модели
Контекстное окно	Диалоговые, визуальные	Если оставить пустым, используется значение по умолчанию 200 000. Указывайте реальное значение из документации поставщика; слишком большое значение приведет к несрабатыванию сжатия истории агента и отказу на верхнем уровне
Поддержка зрения / мультимодальности	Диалоговые	Принимает ли модель изображения на вход
Вход изображение	Векторная	Способна ли модель кодировать изображение в то же векторное пространство, что и текст. При включении и поддержке передачи картинок протоколом поставщика в базах знаний с включённым «Поиском по векторам изображений» после генерации описания для каждого изображения сохраняется ещё и векторная запись изображения, по содержимому которой находятся сведения, отсутствующие в описании (кроме страниц сканированных PDF); переключатель в базе знаний по умолчанию выключен, и только заявленная возможность модели не меняет поведение существующих баз. Модели из каталога распознаются автоматически, в модель сохраняется только расхождение с каталогом; для моделей, которых нет в каталоге, возможность нужно заявлять вручную
Максимальное число выходных токенов	Диалоговые, визуальные	Ограничение вывода для одного ответа, при пустом поле используется значение по умолчанию из каталога
Предел параллелизма в фоне	Диалоговые, визуальные, векторные	Ограничение параллельных задач фонового импорта и обогащения для модели; 0 или пусто — глобальное значение по умолчанию, не влияет на интерактивный диалог
Расширенные → Переопределение протокола	Диалоговые, визуальные	Принудительное использование протокола запроса, обычно оставляйте «Авто»
Расширенные → Удаленное имя модели	Удаленные модели	Фактический ID модели, отправляемый поставщику, если он отличается от имени модели
Расширенные → Переопределение совместимости протокола (JSON)	Удаленные модели	Корректировка полей запроса для отдельных интерфейсов, расходящихся со стандартом каталога, например {"max_tokens_field": "max_tokens"}; пусто — без переопределения. Синтаксис и поля см. в Переопределение совместимости протокола

Если у диалоговой модели, сохраненной в старой версии, настроен параметр thinking_control, в расширенном разделе появится «Формат параметров рассуждений (старая конфигурация)», при смене на «Следовать настройкам каталога» формат параметров рассуждений будет определяться каталогом моделей.

Каталог моделей определяет, способна ли диалоговая модель рассуждать, и доступные уровни рассуждений (часть из набора: выкл, авто, минимальный, низкий, средний, высокий, сверхвысокий, максимальный). Если выбранный в агенте или диалоге уровень не поддерживается моделью, он автоматически корректируется до ближайшего доступного.

Переопределение совместимости протокола compat JSON

Даже при наличии интерфейса, «совместимого с OpenAI», требования к полям запроса у поставщиков различаются: одни принимают только max_tokens, другие используют разные поля для включения рассуждений, а модели рассуждений могут отвергать temperature. Эти различия для встроенных поставщиков и добавленных моделей уже заложены в каталоге, поэтому обычно заполнять этот пункт не требуется. Параметр расположен в разделе «Расширенные настройки → Расширенные» для удаленных моделей (за исключением облачного сервиса) и востребован только в следующих случаях:

• Развертывание собственных сервисов (vLLM, SGLang и т.д.) или шлюзов, чье поведение расходится с дефолтами поставщика;
• Появление новой модели поставщика, еще не добавленной в каталог (панель «Фактический способ вызова» показывает «Стандартные настройки поставщика (модель не найдена в каталоге)»), при возникновении ошибок вызова;
• Изменение API поставщика, требующее временной корректировки до обновления.

Правила заполнения

1. Сначала проверьте протокол. Поля диалоговых и визуальных моделей зависят от «протокола запроса» на панели «Фактический способ вызова» и принимают только его поля; при изменении «переопределения протокола» JSON также нужно перевести на поля нового протокола. Векторные, реранкинговые и голосовые модели используют собственные группы полей независимо от протокола.
2. Указывайте только изменяемые ключи. Неуказанные ключи наследуют значения из каталога по умолчанию. Объекты вроде extra_body объединяются по ключам, массивы заменяются целиком.
3. Проверка при сохранении. Ввод должен быть валидным JSON-объектом. Ошибки в ключах, типах значений или несуществующие константы приведут к ошибке сохранения с пояснением причин, не дожидаясь момента вызова.
4. Тест после изменения. «Проверить подключение» использует текущие настройки из формы без сохранения.

Приоритет этого переопределения выше дефолтов поставщика и каталога; старые настройки «Формат параметров рассуждений» и «Удаленное имя модели» применяются в последнюю очередь. Поля рассуждений для моделей, помеченных в каталоге как не поддерживающие рассуждения, будут проигнорированы.

extra_body дополняет только те поля, которые не записаны системой, и не может переопределять model, messages, max_tokens и другие поля, генерируемые платформой.

Типичные сценарии

Проблема	Заполнение
Ошибка неизвестного поля max_completion_tokens	{"max_tokens_field": "max_tokens"}
Модель рассуждений отклоняет temperature / top_p	{"supports_temperature": false}
Интерфейс принимает только фиксированную температуру (например, 1)	{"fixed_temperature": 1}
Проблемы с включением/выключением рассуждений в гибридных моделях вроде Qwen3 на vLLM / SGLang	{"thinking_format": "chat-template-kwargs"}
Ошибка шлюза при возврате использования в стриминге	{"supports_usage_in_streaming": false}
Шлюз отклоняет структуру сообщений с изображениями	{"supports_multi_content": false} (отправляется только текст, изображения отбрасываются)
Необходимость передачи приватных параметров (например, веб-поиск Aliyun)	{"extra_body": {"enable_search": true}}
Ошибка при передаче контента рассуждений в многодиалоговом режиме	{"replay_reasoning_content": false}
Собственный векторный сервис принимает не более 16 элементов за запрос	{"max_batch_size": 16}
Развёрнутые на vLLM мультимодальные векторные модели (VLM2Vec, GME и т. п.)	Достаточно включить «Вход изображение». Если image_format и image_field не заполнены, OpenAI-совместимый протокол отправляет изображения в формате messages от vLLM. Если шаблону требуются инструкции, добавьте {"image_prompt": "Represent the given image."}; если текст тоже должен пройти через диалоговый шаблон, чтобы оказаться в том же векторном пространстве с картинками, добавьте {"text_as_messages": true}
Развёрнутые на vLLM Qwen3-VL-Embedding	Заполнять не нужно: для моделей с именем, содержащим qwen3-vl-embedding, у пользовательского поставщика вход изображений и {"text_as_messages": true, "extra_body": {"add_special_tokens": true}} уже встроены. Обычный текстовый input минует диалоговый шаблон и оказывается не в том же пространстве, что и изображения; без add_special_tokens в конце не хватает <|endoftext|>, по которому модель извлекает вектор, и результат расходится с карточкой модели. Индексы, уже созданные с этой моделью, нужно перестроить
Развёрнутые в SGLang мультимодальные векторные модели	Включите «Вход изображение» и укажите {"image_format": "object", "image_field": "image"}
Медленный ответ векторного или реранкингового сервиса, требуется больший тайм-аут	{"request_timeout_seconds": 120}
Собственный реранкинговый сервис возвращает ненормализованную оценку (logit)	{"score_scale": "logit"}

WeMM-Embedding

В списке векторных моделей пользовательского поставщика (generic) уже встроены пресеты ниже — после выбора вход изображений и родная размерность вектора распознаются автоматически:

Название модели	Родная размерность
tencent/WeMM-Embedding-2B	2048
tencent/WeMM-Embedding-4B	2560
tencent/WeMM-Embedding-9B	4096

Можно выбрать официальное развёртывание на vLLM либо использовать скрипт развёртывания Transformers из этого репозитория и обслуживать тот же Embedding-интерфейс на CUDA, MPS или CPU. MPS — дополнительное вычислительное устройство, службу также можно развернуть на отдельном сервере.

Развёртывание по официальной инструкции использует vLLM 0.27.0 и загружает embedding_chat_template.jinja из каталога модели. Например, развёртывание 2B с приведением имени службы к пресету через --served-model-name:

MODEL_PATH=/path/to/WeMM-Embedding-2B
vllm serve "$MODEL_PATH" \
  --runner pooling \
  --chat-template "$MODEL_PATH/embedding_chat_template.jinja" \
  --served-model-name tencent/WeMM-Embedding-2B

Для 4B и 9B замените путь к модели и имя службы. В aihelpme.ru выберите поставщика «Пользовательский», в Base URL укажите http://хост:порт/v1 службы, выберите соответствующую векторную модель, а при первом подключении оставьте «Настраиваемую размерность вывода» выключенной. Если у службы не задан --served-model-name, имя модели должно быть фактическим локальным путём, который служба возвращает; пресет также распознаёт короткое имя WeMM-Embedding-2B и пути, оканчивающиеся на /WeMM-Embedding-2B, — то же самое для 4B и 9B. Для произвольных пользовательских псевдонимов возможности модели и переопределение протокола настраиваются отдельно.

Пресет проводит и текст, и изображения через messages в шаблон модели, который добавляет нужный маркер <embedding> для получения вектора; включён batch_messages — независимые conversations из одной партии объединяются в один запрос, но вектор возвращается для каждой. Изображения — не более 5 штук на пачку, излишки разбиваются автоматически; это выбранное aihelpme.ru значение размера пачки, совпадающее с существующим пресетом Qwen3-VL-Embedding, и не заявляет официальный предел модели или vLLM — при необходимости скорректируйте max_image_batch_size под мощность службы. Текущие задачи индексации изображений в базе знаний по-прежнему вызываются по одной и из-за этой настройки не объединяются. Устаревшее значение по умолчанию truncate_prompt_tokens: 511 не отправляется: при превышении контекста службы вернётся ошибка вместо незаметного усечения. Дополнительные совместимость JSON и промпты для изображений не нужны. Если раньше индекс для этой модели создавался через обычный текстовый input, векторы нужно перестроить.

Шаблон WeMM уже содержит нужные специальные токены — сохраните поведение vLLM по умолчанию add_special_tokens: false и add_generation_prompt: false, не переносите add_special_tokens: true из пресета Qwen3-VL-Embedding. Embedding в vLLM по умолчанию берёт последний токен и выполняет L2-нормализацию — дополнительно отправлять normalize или отключать use_activation не нужно.

Для понижения размерности включите «Настраиваемую размерность вывода» и выберите допустимую размерность из конфигурации модели; aihelpme.ru отправит одинаковый dimensions в текстовых и в запросах с изображениями, vLLM сначала урежет вектор до нужной размерности, а затем нормализует:

Модель	Доступные размерности
2B	64, 128, 256, 512, 1024, 2048
4B	64, 128, 256, 512, 1024, 2560
9B	64, 128, 256, 512, 1024, 2048, 4096

Эти значения приведены из официальной конфигурации и описания модели — vLLM отклонит размерность вне списка. После смены размерности вывода существующий векторный индекс нужно перестроить. Таймауты, параллелизм и ограничения на размер изображений остаются текущими значениями по умолчанию — настраивайте их под фактическую производительность службы.

Для прямого поиска по содержимому изображений в базе знаний нужно дополнительно включить индексацию векторов изображений. Текущий пресет подключает текст и изображения; видео, произвольные составные текстово-графические входы и векторизация целых страниц сканированных PDF текущей цепочкой обработки не поддерживаются.

Справочник по полям

Значения «По умолчанию в протоколе» в таблице ниже применяются при полном отсутствии данных поставщика, каталога или переопределений; фактические значения для конкретного поставщика проверяйте на панели «Фактический способ вызова».

OpenAI Chat Completions (openai-completions): используется большинством поставщиков с поддержкой «совместимости с OpenAI», собственными сервисами и шлюзами.

Поле	Тип	По умолчанию в протоколе	Описание
max_tokens_field	string	max_completion_tokens	Имя поля лимита вывода: max_tokens или max_completion_tokens, отправляется только одно из них
thinking_format	string	none	Формат переключателя рассуждений: none не отправлять; openai отправлять reasoning_effort; thinking-type отправлять {"thinking": {"type": ...}}; enable-thinking отправлять enable_thinking (вместе с полем бюджета); chat-template-kwargs отправлять chat_template_kwargs.enable_thinking (vLLM / SGLang); openrouter отправлять {"reasoning": ...}
thinking_enabled_value	string	enabled	Значение type при включении рассуждений для формата thinking-type (например, у MiniMax это adaptive)
thinking_always_send	bool	false	Отправлять переключатель даже при неуказанных предпочтениях рассуждений
thinking_disable_on_non_stream	bool	false	Принудительно отключать рассуждения при нестриминговых вызовах (некоторые модели разрешают рассуждения только со стримингом)
thinking_budget_field	string	Пусто	Имя поля бюджета рассуждений, например thinking_budget; если пусто, не отправляется
thinking_budget_excludes_effort	bool	false	Установите в true, если поставщик запрещает одновременное появление бюджета и reasoning_effort, оставляя только интенсивность рассуждений
supports_reasoning_effort	bool	false	Отправлять ли дополнительную интенсивность рассуждений
reasoning_effort_field	string	reasoning_effort	Имя поля интенсивности рассуждений
supports_developer_role	bool	false	Использовать роль developer для системных промптов моделей рассуждений
supports_store	bool	false	Отправлять store: false, требуя от сервера не сохранять диалог
supports_usage_in_streaming	bool	true	Передавать stream_options.include_usage в стриминговых запросах для подсчета токенов
supports_temperature	bool	true	При false не отправлять параметры сэмплирования (температура, top_p, штрафы)
fixed_temperature	number	Нет	Фиксированное значение температуры для отправки
supports_seed	bool	true	Отправлять ли seed
tool_choice_modes	string[]	none, auto, required, function	Допустимые значения tool_choice
supports_parallel_tool_calls	bool	true	Отправлять ли parallel_tool_calls
supports_response_format	bool	true	Отправлять ли response_format при необходимости вывода в JSON
supports_multi_content	bool	true	При false в сообщениях со смешанным текстом и картинками оставлять только текст
replay_reasoning_content	bool	true	Передавать модели предыдущий контент рассуждений в многодиалоговом режиме
reasoning_fields	string[]	reasoning_content, reasoning, reasoning_text	Поля для чтения текста рассуждений из ответа, берется первое доступное по порядку
tool_call_extra_fields	string[]	Пусто	Дополнительные поля, передаваемые без изменений в вызовах инструментов (например, extra_content при вызове Gemini через совместимый интерфейс OpenAI)
prompt_cache_key	bool	true	Отправлять prompt_cache_key для попадания в кэш промптов в рамках одной сессии
cache_control_format	string	Пусто	При значении anthropic вставлять точки останова кэша в формате Anthropic
prompt_cache_accounting	bool	false	Возврат поставщиком использования кэша для статистики
extra_body	object	Пусто	Поля, добавляемые к каждому запросу

OpenAI Responses (openai-responses): используется официальным интерфейсом OpenAI (api.openai.com) по умолчанию.

Поле	Тип	По умолчанию в протоколе	Описание
supports_developer_role	bool	true	Использовать роль developer для системных промптов
supports_max_output_tokens	bool	true	Отправлять ли max_output_tokens
supports_reasoning_summary	bool	true	Запрашивать ли сводку рассуждений
supports_encrypted_reasoning	bool	true	Запросить и вернуть зашифрованный контент рассуждений
supports_store	bool	true	Отправлять store: false
supports_temperature	bool	true	При false не отправлять параметры сэмплирования
prompt_cache_key	bool	true	Отправлять ключ кэша промптов
supports_long_cache_retention	bool	true	Разрешить долгосрочное кэширование на 24 часа
supports_parallel_tool_calls	bool	true	Отправлять ли parallel_tool_calls
extra_body	object	Пусто	Поля, добавляемые к каждому запросу

Anthropic Messages (anthropic-messages): Anthropic и совместимые интерфейсы с base_url, оканчивающимся на /anthropic.

Поле	Тип	По умолчанию в протоколе	Описание
thinking_mode	string	budget	budget включает рассуждения по бюджету; adaptive отдается на усмотрение модели, интенсивность передается через output_config.effort
thinking_off_type	string	disabled	Тип thinking.type, отправляемый при отключении рассуждений в режиме adaptive; Claude Sonnet 5.5 не принимает disabled — используйте between_tools
supports_effort	bool	false	Отправлять ли интенсивность рассуждений
thinking_budgets	object	minimal 1024, low 2048, medium 8192, high 16384, xhigh 32768, max 63999	Значения budget_tokens для каждого уровня интенсивности, ключи minimal/low/medium/high/xhigh/max
default_max_tokens	int	4096	Значение max_tokens по умолчанию при отсутствии лимита вывода (обязательно для этого протокола)
supports_temperature	bool	true	Отправлять ли температуру
temperature_with_thinking	bool	false	Отправлять ли температуру при включенных рассуждениях
supports_top_p	bool	true	Отправлять ли top_p
supports_cache_control	bool	true	Вставлять ли точки останова кэша
supports_cache_control_on_tools	bool	true	Вставлять ли точки останова кэша в определения инструментов
long_cache_ttl	string	1h	Срок действия долгосрочного кэша
version	string	2023-06-01	Заголовок anthropic-version
beta_headers	string[]	Пусто	Дополнительные заголовки anthropic-beta
interleaved_thinking_beta	string	interleaved-thinking-2025-05-14	Метка beta при одновременном использовании рассуждений и инструментов; пустая строка — не отправлять
prompt_cache_accounting	bool	true	Возврат поставщиком использования кэша
extra_body	object	Пусто	Поля, добавляемые к каждому запросу

Gemini (google-generative-ai): нативный интерфейс Gemini.

Поле	Тип	По умолчанию в протоколе	Описание
thinking_mode	string	budget	budget отправляет thinkingBudget (Gemini 2.5); level отправляет thinkingLevel (начиная с Gemini 3); none не отправляет настройки рассуждений
thinking_budgets	object	minimal 128, low 2048, medium 8192, high 24576, xhigh 32768, max 32768	Значения thinkingBudget для каждого уровня рассуждений
include_thoughts	bool	true	Возвращать ли контент рассуждений
supports_seed	bool	true	Отправлять ли seed
supports_penalty	bool	true	Отправлять ли штрафы за частоту / присутствие
extra_generation_config	object	Пусто	Поля, добавляемые в generationConfig
prompt_cache_accounting	bool	true	Возврат поставщиком использования кэша
api_version_prefix	string	/v1beta	Путь версии, добавляемый к base_url, если указан только хост

Векторные модели

Поле	Тип	По умолчанию в протоколе	Описание
api	string	По умолчанию поставщика	Векторный протокол: openai-embeddings, dashscope-embeddings, ark-embeddings, google-embeddings
path	string	Пусто	Путь, добавляемый после base_url
send_encoding_format	bool	false	Отправлять ли encoding_format: "float"
dimensions_field	string	Пусто	Имя поля для указания размерности вывода; отправляется только при включенной опции «Настраиваемая размерность вывода»
truncate_field / truncate_value	string	Пусто	Поле переключателя и значение для усечения сервером при превышении длины входа
input_type_field	string	Пусто	Имя поля для различения «документа» и «запроса»
input_type_values	object	Пусто	Значения для типов document и query
max_batch_size	int	0 (без ограничений)	Максимальное число элементов в запросе, разбивается автоматически
max_input_chars	int	0 (без ограничений)	Максимальное число символов на один вход
accepts_truncate_prompt_tokens	bool	false	Поддерживает ли сервер truncate_prompt_tokens для vLLM
request_timeout_seconds	int	60	Тайм-аут запроса (сек)
extra_body	object	Пусто	Поля, добавляемые к каждому запросу
image_field	string	Пусто	Только openai-embeddings: имя ключа объекта, несущего изображение, в input (у Jina и SGLang — image). Если модель не заявляет вход изображений, поле пусто и image_format не равен messages, endpoint изображения не принимает
image_format	string	Пусто	Только openai-embeddings: способ отправки изображений. object кладёт {image_field: изображение} в input; messages отправляет изображение как ход диалога в messages (мультимодальный векторный интерфейс vLLM). Если модель заявляет вход изображений, а это поле и image_field пусты — отправка в формате messages; если заполнен только image_field — формат object; при object без image_field изображения всё равно не отправляются
image_prompt	string	Пусто	Только для формата messages: текст, отправляемый вместе с изображением, — он требуется шаблонам части моделей (например, Represent the given image. у VLM2Vec)
text_as_messages	bool	false	Только openai-embeddings: и текст отправляется в формате messages, по одному запросу на каждый. Для моделей, которым обязателен проход через диалоговый шаблон, чтобы текст и изображения оказались в одном векторном пространстве (у Qwen3-VL-Embedding у пользовательского поставщика уже встроено); после изменения для таких моделей существующие индексы нужно перестроить
max_image_batch_size	int	1	Максимум изображений в одном запросе, излишки разбиваются автоматически
max_image_bytes	int	0 (без ограничений)	Лимит размера одного изображения в байтах; изображения больше лимита отклоняются без отправки запроса
image_mime_types	array	Пусто (без ограничений)	Принимаемые поставщиком форматы изображений, например ["image/png", "image/jpeg"]

Модели реранкинга

Поле	Тип	По умолчанию в протоколе	Описание
path	string	Пусто	Путь, добавляемый после base_url
send_top_n	bool	false	Отправлять ли top_n (при отсутствии возвращаются все документы)
send_return_documents	bool	false	Требовать ли от сервера возврата текста документов
score_scale	string	probability	Смысл оценки: probability (0–1) или logit (ненормализованные). Ошибка приведет к сбою порога релевантности
truncate	string	Пусто	Настройки усечения на сервере (например, END для NIM)
max_documents	int	0 (без ограничений)	Максимум документов в одном запросе, при превышении — автоматическое разбиение на пакеты
max_query_chars	int	0 (без ограничений)	Ограничение длины запроса, при превышении вызов считается неудачным (запрос повторяется в каждом запросе — разбиение документов не делает его короче)
max_document_chars	int	0 (без ограничений)	Ограничение длины одного документа, при превышении вызов считается неудачным
max_request_chars	int	0 (без ограничений)	Общий лимит длины одного запроса (запрос + все документы), при превышении — автоматическое разбиение; действует одновременно с max_documents, и срабатывает то ограничение, которое первым; если одного документа с запросом уже недостаточно, вызов считается неудачным
max_concurrency	int	0 (использовать значение по умолчанию)	Количество параллельных запросов после разбиения на пакеты
accepts_truncate_prompt_tokens	bool	false	Поддерживает ли сервер truncate_prompt_tokens от vLLM
request_timeout_seconds	int	0 (по умолчанию 60 сек)	Тайм-аут запроса (сек); при сбое поиск откатывается к исходному порядку выдачи
extra_body	object	Пусто	Поля, добавляемые к каждому запросу
image_field	string	Пусто	Только cohere-rerank: имя ключа объекта-изображения в документе (у Jina — image). Пусто = endpoint принимает только текст. Формат изображений в протоколе NIM закреплён протоколом и заполнения не требует
max_image_batch_size	int	1	Максимум изображений в одном запросе; изображения и текст отправляются разными запросами, излишки разбиваются автоматически
max_image_bytes	int	0 (без ограничений)	Лимит размера одного изображения в байтах; изображения больше лимита отклоняются без отправки запроса
image_mime_types	array	Пусто (без ограничений)	Принимаемые поставщиком форматы изображений

Изображения получают только модели реранкинга, чья возможность input включает image (в каталоге — jina-reranker-m0 и nvidia/llama-nemotron-rerank-vl-1b-v2).

Модели распознавания речи (ASR)

Поле	Тип	По умолчанию в протоколе	Описание
api	string	По умолчанию поставщика	openai-transcriptions (загрузка аудиофайла) или openai-chat-audio (передача аудио в запросе чата)
path	string	/audio/transcriptions	Путь, добавляемый после base_url
response_format	string	Пусто	Отправляемый response_format, укажите verbose_json для пошаговых результатов
language_param	string	Пусто	Расположение языковой подсказки: form, header, asr_options; пусто — не отправлять
max_file_bytes / max_encoded_bytes	int	0 (без ограничений)	Лимиты размера аудиофайла и закодированного в base64 размера
formats	string[]	Пусто (без ограничений)	Допустимые расширения аудио (без точки)
request_timeout_seconds	int	300	Тайм-аут запроса (сек)

Встроенные поставщики

Встроено 30 поставщиков, также возможно подключение локальных моделей через Ollama. Поддерживаемые типы моделей для каждого поставщика (✓ означает поддержку):

Поставщик	ID	Диалог	Вектор	Реранкинг	Визуальные	Голос
Пользовательский (совместимый с OpenAI)	generic	✓	✓	✓	✓	✓
Облачный сервис	weknoracloud	✓	✓	✓	✓
Aliyun DashScope	aliyun	✓	✓	✓	✓	✓
Zhipu BigModel	zhipu	✓	✓	✓	✓	✓
Volcengine (Волкано)	volcengine	✓	✓	✓	✓
Hunyuan	hunyuan	✓	✓
SiliconFlow	siliconflow	✓	✓	✓	✓	✓
MiniMax	minimax	✓				✓
Moonshot AI (Лунный свет)	moonshot	✓			✓
Xiaomi MiMo	mimo	✓				✓
ModelScope (Модаб)	modelscope	✓	✓		✓
Baidu Qianfan	qianfan	✓	✓	✓	✓
Qiniu	qiniu	✓
Meituan LongCat	longcat	✓
LKEAP	lkeap	✓		✓
DeepSeek	deepseek	✓
OpenAI	openai	✓	✓		✓	✓
Azure OpenAI	azure_openai	✓	✓		✓
Anthropic	anthropic	✓
Google Gemini	gemini	✓	✓
OpenRouter	openrouter	✓	✓	✓	✓	✓
LiteLLM	litellm	✓	✓	✓	✓	✓
Requesty	requesty	✓	✓		✓	✓
Jina	jina		✓	✓
NVIDIA	nvidia	✓	✓	✓	✓
Novita AI	novita	✓	✓	✓	✓
GPUStack	gpustack	✓	✓	✓	✓	✓
Hugging Face TEI	huggingface_tei			✓
Pinecone	pinecone			✓
Cohere	cohere			✓

Столбец «Визуальные» означает возможность выбора поставщика для визуального типа модели; принимает ли сама диалоговая модель изображения, определяется каталогом моделей и переключателем «Поддержка зрения/мультимодальности». Для облачного сервиса необходимо предварительно сохранить учетные данные в настройках, имена моделей могут быть chat, embedding, rerank, vlm.

Список поставщиков, адреса по умолчанию и каталог моделей передаются с сервера (GET /api/v1/models/providers), администраторы могут изменять или добавлять поставщиков через файл наложения развертывания.

Cohere реранкинг

При добавлении удалённой модели реранкинга выберите Cohere, укажите API-ключ Cohere и модель rerank-v4.0-pro, rerank-v4.0-fast или rerank-v3.5. Адрес по умолчанию — https://api.cohere.com/v2, можно указать и полный адрес /v2/rerank.

Пример тела запроса при создании через POST /api/v1/models:

{
  "name": "rerank-v4.0-pro",
  "type": "Rerank",
  "source": "remote",
  "parameters": {
    "provider": "cohere",
    "base_url": "https://api.cohere.com/v2",
    "api_key": "your-cohere-api-key"
  }
}

Запрос отправляет только текстовый запрос и документы, исходный текст восстанавливается по индексам из ответа. aihelpme.ru следует рекомендациям Cohere API и разбивает набор из более чем 1000 кандидатов на несколько запросов; 1000 — принятый рекомендуемый размер пакета. Поле top_n можно не указывать, тогда оценки вернутся для всех кандидатов; для очень длинных документов действует поведение усечения по умолчанию на стороне службы. Эта интеграция предоставляет только текстовый реранкинг Cohere.

Просмотр использования и настройка параметров

Базы знаний и агенты сохраняют ссылки на модели. Перед удалением модели необходимо проверить детали зависимостей; встроенные модели управляются конфигурацией YAML и должны поддерживаться в соответствующем файле.

Отладчик моделей выполняет реальные запросы к сохраненной модели, отображая время выполнения, маскированный запрос и результат ответа, что удобно для проверки размерности векторов, оценок реранкинга или потокового вывода. Диалоговые модели с поддержкой рассуждений позволяют выбирать интенсивность рассуждений в отладке, результаты содержат фактический протокол запроса и параметры переключателя рассуждений. Статистику вызовов и использования кэша можно просмотреть в разделе Наблюдаемость и аудит.

Справочник конфигурации и вызовов

Типы моделей и назначение

Типы моделей определены в internal/types/model.go:

const (
    ModelTypeEmbedding   ModelType = "Embedding"   // Векторная модель
    ModelTypeRerank      ModelType = "Rerank"      // Модель реранкинга
    ModelTypeKnowledgeQA ModelType = "KnowledgeQA" // Модель Q&A знаний
    ModelTypeVLLM        ModelType = "VLLM"        // VLLM модель
    ModelTypeASR         ModelType = "ASR"         // ASR модель
)

Тип	Метка на фронтенде	Пакет клиента	Интерфейс	Назначение
KnowledgeQA	chat	internal/models/chat	Chat / ChatStream (поддерживает Tools, Thinking, мультимодальные сообщения)	Базовые Q&A, логический вывод агентов, генерация аннотаций/вопросов/графов и любые другие вызовы LLM
Embedding	embedding	internal/models/embedding	Embed / BatchEmbed (включая GetDimensions)	Векторизация текста для индексации и поиска
Rerank	rerank	internal/models/rerank	Rerank(query, documents) возвращает RankResult	Точное ранжирование результатов поиска
VLLM	vllm	internal/models/vlm	Predict(imgBytes, prompt)	Визуально-языковые модели (VLLM), понимание изображений документов / мультимодальный анализ
ASR	asr	internal/models/asr	Transcribe(audioBytes, fileName) возвращает текст; при поддержке модели передаются временные метки сегментов (например, OpenAI whisper-1)	Транскрипция аудио (автоматическое распознавание речи)

Маппинг типов между фронтендом и бэкендом находится в modelTypeToFrontend() файла internal/handler/model_catalog.go (KnowledgeQA -> chat и т.д.). REST-интерфейсы создания моделей сохраняют type как есть, вызывающая сторона должна передавать значение бэкенда (KnowledgeQA и др.); параметр запроса model_type поддерживает оба варианта написания.

Основные значения источника модели (ModelSource): local (запуск через локальный Ollama) и remote (удаленный API); остальные исторические значения (aliyun, zhipu, openai и т.д.) сохранены для обратной совместимости, их маршрутизация эквивалентна remote + соответствующий провайдер.

Поля конфигурации моделей

Параметры сущности модели types.Model (ModelParameters в internal/types/model.go):

Имя	Тип	По умолчанию	Описание
base_url	string	Пусто (адрес по умолчанию поставщика)	API-адрес модели, при создании/обновлении проверяется на SSRF (ValidateURLForSSRF)
api_key	string	Пусто	API-ключ, хранится в зашифрованном виде AES-256-GCM (ModelParameters.Value/Scan). Передается при создании; в дальнейшем изменяется только через подресурс PUT /models/:id/credentials
interface_type	string	Пусто (VLLM: local по умолчанию ollama, remote по умолчанию openai)	Тип протокола интерфейса
embedding_parameters.dimension	int	0	Размерность векторов
embedding_parameters.truncate_prompt_tokens	int	0	Лимит токенов для усечения на сервере. Расширенный параметр vLLM, отправляется только для generic и gpustack (при 0 используется историческое значение 511); для облачных поставщиков не отправляется
embedding_parameters.supports_dimension_override	bool	false	Указывать ли размерность векторов в запросе. Имя поля определяется поставщиком (OpenAI — dimensions, Gemini — outputDimensionality, мультимодальный Bailian — parameters.dimension); для моделей без поддержки в документации (NVIDIA NIM, Hunyuan, Novita, ada-002 и др.) не отправляется даже при включении
parameter_size	string	Пусто	Размер параметров модели Ollama (например, "7B"), поддерживается бэкендом, недоступно для изменения на фронтенде
provider	string	Пусто (автоопределение по BaseURL)	ID поставщика, см. Встроенные поставщики
extra_config	map[string]string	nil	Дополнительные поля поставщика (см. следующий раздел); зарезервированные ключи: api (принудительный протокол диалога), remote_model_name (удаленное имя модели), thinking_control (старый формат параметров рассуждений)
spec	object	nil	Переопределение каталога для одной строки: api, reasoning, input, context_window, max_output_tokens, thinking_levels, compat (плоский JSON, связанный с протоколом)
custom_headers	map[string]string	nil	Пользовательские заголовки HTTP-запросов (аналогично extra_headers в SDK OpenAI; заголовки Authorization, api-key и др. игнорируются во время выполнения)
supports_vision	bool	false	Принимает ли диалоговая модель мультимодальный ввод изображений
context_window	int	0 (откат к 200000)	Контекстное окно диалога/VLLM (в токенах). Используется агентами для загрузки и сжатия истории; должно соответствовать реальной емкости сервиса, слишком высокое значение помешает своевременному сжатию
max_output_tokens	int	0 (значение по умолчанию из каталога)	Лимит вывода для одного ответа диалога/VLLM
max_concurrency	int	0 (откат к глобальному model.max_concurrency)	Предел параллелизма фоновых задач модели (актуально для chat/vlm/embedding)
app_id / app_secret	string	Пусто	Учетные данные облачного сервиса; вторая часть ключа для реранкинга LKEAP / Volcengine также хранится в app_secret. app_secret шифруется AES

Поля модели также включают name (фактическое имя модели во время выполнения), display_name, type, source, is_default (единственное по умолчанию в пределах группы (tenant_id, type)), is_builtin, managed_by, status (active / downloading / download_failed).

Ответы для удаленных диалоговых и визуальных моделей содержат capabilities (протокол, поддержка рассуждений, доступные уровни рассуждений, контекстное окно и т.д.), вычисляемые сервером на основе каталога.

Дополнительные поля поставщиков

Поставщики объявляют дополнительные поля в своих определениях, на основе которых редактор динамически формирует интерфейс, а значения сохраняются в extra_config (поля, помеченные как секретные, не возвращаются обратно, отображается лишь статус их настройки):

Поставщик	Поле	Применимый тип	Описание
Azure OpenAI	api_version	Все	Пусто — плоскость данных /openai/v1; указание версии (например, 2025-04-01-preview) возвращает старый путь /openai/deployments/{deployment_name}
LKEAP	SecretKey (обязательно, шифруется при сохранении), region (по умолчанию ap-guangzhou)	Реранкинг	Интерфейс реранкинга использует подпись TC3, в поле API Key указывается SecretId
Volcengine	SecretKey (обязательно, шифруется при сохранении), region (по умолчанию cn-beijing), instruction	Реранкинг	Интерфейс реранкинга использует подпись AK/SK, в поле API Key указывается Access Key ID; instruction по умолчанию соответствует тексту консоли
Пользовательский, GPUStack, LiteLLM	score_scale	Реранкинг	«Шкала оценок Rerank»: probability (релевантность 0–1, для BGE и подобных) или logit (безграничная оценка, для Qwen3-Reranker, преобразуется в 0–1 перед сравнением с порогом). Выбирается под фактически развернутую модель
Пользовательский, GPUStack	truncate_prompt_tokens	Реранкинг	Расширенный параметр vLLM, по умолчанию не отправляется; заполняется только при ошибках бэкенда из-за слишком длинных документов

Управляющий API (internal/router/routes_infra.go)

Метод и путь	Описание
GET /models/providers	Запрос поддерживаемых определений поставщиков по model_type (включая иконки, адреса по умолчанию, дополнительные поля, каталог моделей)
GET / POST /models/catalog/resolve	Разбор фактического способа вызова для одной конфигурации (протокол, уровень рассуждений, контекст) — соответствует панели «Фактический способ вызова» в редакторе
POST /models / GET /models / GET /models/:id / PUT /models/:id / DELETE /models/:id	CRUD моделей
PUT /models/:id/credentials, DELETE /models/:id/credentials/:field	Подресурс учетных данных; поле api_key в теле запроса PUT /models/:id принудительно игнорируется с предупреждением
POST /models/:id/debug	Отладка модели (см. ниже)
GET /models/weknoracloud/status	Статус учетных данных облачного сервиса

Полный список запросов и ответов см. в Справочник API: Модели и инициализация.

Проверка здоровья / тестирование подключения моделей

Используются два механизма, оба хранят учетные данные на сервере и не передают открытые ключи на клиент:

1. Проверка подключения (internal/handler/initialization.go, вызывается кнопкой «Проверить подключение» в редакторе моделей):

• POST /initialization/remote/check — модели Chat (CheckRemoteModel / checkChatModelConnection)
• POST /initialization/embedding/test — Embedding (TestEmbeddingModel)
• POST /initialization/rerank/check — Rerank (CheckRerankModel)
• POST /initialization/asr/check — ASR (CheckASRModel)
• POST /initialization/multimodal/test — Мультимодальный анализ VLM (TestMultimodalFunction)

Тело запроса ModelTestRequest может содержать modelId: функция fillSecretsFromStoredModel автоматически дополняет недостающие в запросе APIKey / AppSecret, extraConfig и spec из сохраненной модели (после расшифровки), реализуя сценарий «смена BaseURL с проверкой по старому ключу в один клик», при котором фронтенд не имеет доступа к открытым ключам и не может их получить. Функция buildTestModel преобразует запрос во временный объект *types.Model без сохранения в базу, разделяя единый логический пайплайн ConfigFromModel с рабочей средой.

2. Отладчик моделей (POST /models/:id/debug, ModelHandler.DebugModel): выполняет реальный вызов сохраненной модели с возвратом полных нормализованных данных — для Chat используется стриминг, можно задавать интенсивность рассуждений (options.reasoning_effort), собираются метрики протокола и параметров рассуждений; Embedding возвращает векторы и размерности; Rerank возвращает оценки; VLLM / ASR принимают загружаемые файлы. Ответ содержит elapsed_ms, замаскированный превью запроса и observations.

Механизм встроенных моделей

internal/types/builtin_models_config.go реализует декларативные встроенные модели: при запуске считывается файл config/builtin_models.yaml (или путь из переменной BUILTIN_MODELS_CONFIG, шаблон см. в config/builtin_models.yaml.example), каждая запись сохраняется или обновляется (UPSERT) в таблице models с флагами is_builtin=true, managed_by="yaml", по умолчанию tenant_id=10000 (DefaultBuiltinModelTenantID), что делает их видимыми для всех тенантов.

Ключевое поведение (LoadBuiltinModelsConfig):

• Строковые поля поддерживают интерполяцию переменных окружения через ${ENV_NAME}; необъявленные переменные сохраняются как литералы для упрощения диагностики ошибок конфигурации.
• При каждом запуске выполняется UPSERT по id, а deleted_at принудительно сбрасывается в NULL (записи, вновь появившиеся в файле, «оживают»).
• Очистка при смещении (drift cleanup): строки с managed_by='yaml', чей id отсутствует в файле, помечаются как мягко удаленные — удаление записи из YAML является стандартным способом деактивации встроенной модели.
• Если администратор перехватит управление строкой во время работы (managed_by сбрасывается в пустое значение), загрузчик YAML пропустит ее («preserving runtime override»).
• Записи с is_default: true предварительно сбрасывают флаг по умолчанию для других элементов в группе (tenant_id, type), сохраняя инвариант единственности значения по умолчанию, аналогично API.
• Правила валидации: id не пуст и не длиннее 64 символов (ModelIDMaxLen), type должен принадлежать к KnowledgeQA | Embedding | Rerank | VLLM | ASR, status должен быть корректным или пустым; ошибки парсинга YAML прерывают сверку (очистка при смещении не выполняется).
• parameters и REST API используют единый набор проверок каталога (runtime.ValidateRow): строки, которые не удалось разобрать (неизвестный протокол, опечатки в ключах compat, недопустимый уровень рассуждений), генерируют только варнинги WARN, не препятствуя запуску.

Пример YAML (из builtin_models.yaml.example):

builtin_models:
  - id: builtin-llm-default
    type: KnowledgeQA
    source: remote
    is_default: true
    name: ${LLM_MODEL_NAME}
    parameters:
      base_url: ${LLM_BASE_URL}
      api_key: ${LLM_API_KEY}
      provider: ${LLM_PROVIDER}
      context_window: 200000     # Опционально; при отсутствии используется значение по умолчанию 200K

Загрузка локальных моделей (Ollama)

Локальные модели эмбеддингов и чата используют единый OLLAMA_BASE_URL; имена векторных моделей и описание переменных окружения приведены в Руководстве по конфигурации.

Жизненный цикл локальных моделей управляется сервисом OllamaService в internal/models/utils/ollama/ollama.go (IsModelAvailable / PullModel / EnsureModelAvailable / ListModelsDetailed / DeleteModel и др.), точки входа HTTP находятся в internal/handler/initialization.go:

Путь	Описание
GET /initialization/ollama/status	Доступность сервиса Ollama
GET /initialization/ollama/models	Список уже загруженных локальных моделей
POST /initialization/ollama/models/check	Пакетная проверка наличия загруженных моделей
POST /initialization/ollama/models/download	Асинхронная загрузка (downloadModelAsync + pullModelWithProgress, записывает статус модели status=downloading)
GET /initialization/ollama/download/progress/:taskId, GET /initialization/ollama/download/tasks	Прогресс загрузки / Список задач

Примечание: cmd/download/duckdb/duckdb.go не связано с моделями — оно предварительно загружает расширения spatial и excel для DuckDB при сборке образа для использования в инструментах анализа данных. Загрузка весов моделей происходит исключительно через Ollama.

Наложение развертывания config/models.json

Добавление поставщиков, изменение адресов и добавление моделей без правки кода: скопируйте config/models.json.example в config/models.json (или задайте путь через MODELS_CONFIG). Поставщики задаются ключами по ID (providers), известные ID получают патчи, новые ID объявляют новых поставщиков.

Поле	Описание
name / names / description / descriptions / website	Отображаемое имя, имя и описание по языкам, официальный сайт
api	Протокол диалога по умолчанию (openai-completions, openai-responses, anthropic-messages, google-generative-ai)
base_url / base_urls	Адрес по умолчанию; base_urls задается отдельно для chat, embedding, rerank, vlm, asr
api_key	Ключ уровня развертывания, используется, если в строке модели ключ не сохранен; поддерживает интерполяцию ${ENV} / $ENV, ненайденные переменные раскрываются в пустые строки
auth / requires_auth	Способ аутентификации (bearer, api-key, x-api-key, x-goog-api-key, none) и требование обязательного заполнения ключа
headers	Дополнительные заголовки запроса
model_types / url_patterns	Типы моделей, поддерживаемые новым поставщиком; старые строки без указания провайдера распознают его по подстроке URL
compat / thinking_levels	Переопределения совместимости протокола уровня поставщика и маппинг уровней рассуждений
models	UPSERT по ID: для существующих ID перезаписываются только указанные поля, а reasoning, thinking_levels, compat, input сохраняют прежние значения; новые ID создаются полностью
model_overrides	Исправление существующих записей по ID (например, context_window, max_output_tokens)
icon	Встроенная строка SVG (<svg …>) или путь к .svg относительно каталога файла наложения; абсолютные пути запрещены, выходить за пределы каталога нельзя, размер ограничен до 256 КБ (иконка передается всем пользователям страницы моделей в виде data URI)

Файл наложения вступает в силу после общей проверки при старте: при обнаружении неизвестных ключей, недопустимых методов авторизации или неразбираемых моделей наложение полностью отменяется, в лог старта выводится Load models catalog overlay failed, а сервис продолжает работу со встроенным каталогом. Изменения в файле на лету не отслеживаются, после правок требуется перезапуск. Модели данных во время выполнения извне не подгружаются, фактическое поведение (имена полей, форматы рассуждений) поддерживается разработчиками.

Наложение меняет только определения поставщиков и каталог моделей; каждая модель по-прежнему хранит собственные URL, API Key, дополнительные поля и spec, не затрагивая ID или связи существующих моделей.

Управление каталогом моделей системным администратором

В разделе «Настройки → Системное администрирование → Каталог моделей» можно просмотреть все модели каталога: отображаются производитель, тип, контекстное окно / максимальный вывод, возможности (рассуждения, ввод изображений и т.д.) и источник конфигурации (встроенный / файл развертывания / правки администратора). Доступна фильтрация по производителю, типу или просмотр изменений администратора. Шаблоны подстановок размещаются после конкретных моделей производителя и служат только источником параметров по умолчанию, не попадая в кандидаты.

Изменения администратора сохраняются отдельно в базе данных в следующем порядке приоритета: Встроенный каталог → Файл развертывания при старте → Правки администратора → Явная конфигурация конкретной модели. Консоль не изменяет смонтированный файл конфигурации; для применения правок в файле развертывания по-прежнему нужен перезапуск, экземпляры должны использовать идентичные файлы.

Частые операции вступают в силу немедленно: текущий экземпляр сразу переключается на новый каталог, остальные экземпляры проверяют версию и синхронизируются каждые 5 секунд; при сбое проверки или ошибках БД сохраняется прежний рабочий каталог. При параллельной публикации другим администратором возвращается ошибка 409, интерфейс предлагает обновить страницу до актуальной версии.

• Редактирование модели: кликните по модели в списке для открытия панели редактирования отображаемого имени, контекстного окна, скрытия из кандидатов; для диалоговых моделей можно менять максимальный вывод, входные модальности (изображения / аудио / видео, после выбора изображений модель доступна как визуальная), поддержку и уровни рассуждений; для векторных моделей — размерность (автозаполнение при добавлении). Для каждого параметра отображается значение по умолчанию (из файла развертывания или встроенного каталога) и отметка о ручной правке администратором; пустые поля восстанавливают дефолтные значения. Блок «Значения по уровням» сопоставляет встроенный каталог, файл развертывания и текущий результат. Кнопка «Восстановить по умолчанию» удаляет все административные правки для модели.
• Уровни рассуждений отображаются в соответствии с результатами серверного анализа (объединяют маппинги уровней производителя и возможности протокола). Снятие галочки записывает маркер null об отсутствии поддержки, повторная установка возвращает сетевое значение производителя; уровни, совпадающие с дефолтными, не записываются как переопределения и продолжают следовать за производителем. Отсутствие галочки у пункта «Отключение» означает обязательное включение рассуждений у модели (например, DeepSeek Reasoner, QwQ, Kimi K3). Кастомный маппинг уровней на значения производителя по-прежнему настраивается через JSON-редактор.
• Добавление модели: добавление модели, отсутствующей в каталоге производителя (производитель, тип, ID модели, опционально отображаемое имя и параметры по умолчанию; уровни рассуждений наследуются от производителя, после добавления их можно скорректировать). Добавленные администратором модели можно удалить через панель редактирования.
• Редактирование JSON (меню «Еще»): прямая правка административных изменений в формате models.json (до 1 МБ, допускается корневой ключ _comment, удаляемый при публикации), подходит для массовой корректировки или миграции. Сначала нажмите «Проверить изменения» для серверной валидации и просмотра списка добавляемых, изменяемых и удаляемых записей и полей; после подтверждения нажмите «Опубликовать N изменений». Функция «Импортировать JSON» загружает файл в редактор с последующей публикацией; «Экспорт изменений» скачивает текущие правки администратора.
• История версий (меню «Еще»): сохраняются последние 20 версий с указанием автора, времени и числа измененных моделей; «Восстановить» публикует новую версию с содержимым выбранной.

Документ каталога предназначен для управления метаданными. Консоль не принимает api_key, headers, base_url / base_urls, url_patterns, auth производителей или пути к файлам иконок; они по-прежнему настраиваются в файлах конфигурации / развертывания (интерполяция переменных окружения также раскрывается только в этих полях файла развертывания, символы $ в консольных документах обрабатываются как обычный текст). Консольные иконки принимают только встроенный SVG. Структура version + providers: массив сгенерированного файла models.generated.json не подходит для импорта в качестве файла наложения, следует использовать структуру providers: объект из шаблона config/models.json.example.

После обновления каталога повторное открытие редактора моделей обновляет списки производителей и кандидатов. В управлении моделями есть специальный пункт «Каталог моделей» для системных администраторов. Модели из каталога не создаются автоматически как настроенные, deprecated скрывает их только из выпадающих списков; явные значения существующих моделей (например, контекстные окна) сохраняются без массовой перезаписи. Непереопределенные значения вроде API / compat из каталога влияют на создаваемые в дальнейшем клиенты; уже созданные клиенты продолжают использовать старые снимки.

Статистика использования моделей

• Использование токенов: структура types.TokenUsage (internal/types/chat.go) фиксирует prompt_tokens / completion_tokens / total_tokens и детали кэша промптов (cache_read_tokens / cache_write_tokens / cache_miss_tokens / cache_status). Все клиенты протоколов выводят унифицированные структурированные логи через LogUsage в internal/models/api/usage_log.go:

 logger.Infof(ctx,
     "[LLM Usage] model=%s, purpose=%s, prompt_prefix=%s, prompt_tokens=%d, completion_tokens=%d, ...",
     ...)

Параметр purpose передается через types.WithLLMCallMetadata (например, document_summary, entity_extraction), позволяя выполнять агрегацию по назначениям.

• Трейсинг: при включенном Langfuse для каждого типа моделей работает декоратор langfuse_wrapper.go, отправляющий вызовы (включая usage) как trace/span.
• Потоковый ответ: статистика usage передается с последним событием StreamResponse (отладчик моделей агрегирует ее в поле usage).
• Уровни параллелизма: эндпоинт GET /system/admin/runtime/queues предоставляет текущие метрики active / waiting / limit для каждой модели (см. ниже раздел Параллелизм и ограничение скорости).

Вызовы моделей и справочник реализации

Многоуровневая архитектура

Интеграция моделей распределена по протоколам, поставщикам, каталогу и исполняемой среде:

Уровень	Расположение	Назначение
Протокольный уровень	internal/models/api/<protocol>	Один пакет на один проводной протокол. Диалог: openaicompletions, openairesponses, anthropicmessages, googlegenai; реранкинг: cohererank, dashscoperank, nimrerank, tencentlkeap, volcengineknowledge, teirank, pineconerank; эмбеддинги: openaiembeddings, dashscopeembeddings, arkembeddings, googleembeddings; аудио: openaitranscriptions, openaichataudio. Содержат структуры запросов/ответов и логику разбора без привязки к определениям поставщиков или каталогу моделей
Уровень поставщиков	internal/models/providers/<id>.go	Одно определение на поставщика, объявляет поддерживаемые типы моделей, адреса по умолчанию для каждого типа, способ авторизации, дополнительные поля, дефолты совместимости протоколов и хуки эндпоинтов; иконки хранятся в providers/assets/ и явно перечисляются в Builtins() файла builtin.go
Уровень каталога	internal/models/catalog	Загружает сгенерированный каталог моделей catalog/data/models.generated.json, выполняет поиск записей по типу и имени модели; не содержит логики поведения поставщиков
Исполняемая среда	internal/models/runtime	Объединяет определения поставщиков с каталогом, применяет наложения развертывания (overlay.go), объединяет конфигурации отдельных моделей, выбирает протокол, собирает аутентификацию и эндпоинты, изолируя логику старых полей

Порядок слияния в runtime.Resolve(Ref{Provider, Model, BaseURL, ModelType, Extra, Override}) от низшего к высшему:

1. Значения протокола по умолчанию (DefaultOpenAICompletions() и др.);
2. Уровни совместимости Compat поставщика (определяются в providers/<id>.go, например max_tokens_field: max_tokens для DeepSeek; уровень поставщика из наложения также применяется здесь);
3. Найденная в каталоге запись (точное совпадение id → aliases → сопоставление по маске match с приоритетом наиболее длинного префикса; модели и переопределения моделей из наложения уже включены в каталог);
4. Поле parameters.spec в строке модели (переопределение протокола и compat JSON из раздела «Расширенные» в редакторе);
5. Принудительный протокол extra_config.api, кодирование старых рассуждений extra_config.thinking_control, удаленное имя модели extra_config.remote_model_name.

Параметры поставщиков поддерживаются на основе документации, в комментариях к каждому файлу providers/<id>.go приводятся ссылки на документацию, а поле source в записях каталога фиксирует источник. Исходящий JSON для каждого протокола фиксируется золотыми тестами (golden tests, например openaicompletions/golden_test.go).

Поля compat, дефолты протоколов и частые сценарии для каждого протокола описаны в разделе Переопределение совместимости протокола; структуры определены в internal/models/api/compat_settings.go (протокол диалога), а также в одноименных файлах embeddings_settings.go, rerank_settings.go, transcriptions_settings.go.

Интенсивность рассуждений унифицирована внутри системы как off / auto / minimal / low / medium / high / xhigh / max, а поле thinking_levels каждой модели маппит этот универсальный уровень на значение поставщика (null означает отсутствие поддержки, "off": null — невозможность отключения рассуждений, как у DeepSeek Reasoner, QwQ, Kimi K3). Если запрашиваемый уровень не поддерживается, выбирается ближайший доступный в сторону увеличения или уменьшения.

Выбор протокола

Anthropic использует протокол Messages; Gemini по умолчанию использует нативный generateContent (base_url, указывающий на /v1beta/openai, сохраняет совместимость с OpenAI); OpenAI использует протокол Responses на api.openai.com, а прокси/шлюзы сохраняют Chat Completions; любой base_url поставщика, оканчивающийся на /anthropic, автоматически переключается на протокол Messages (совместимые эндпоинты Anthropic для MiniMax, Zhipu, Kimi). Явный выбор в spec.api имеет приоритет над URL и автоопределением по поставщику; старый конфиг extra_config.api сохраняет наивысший приоритет. extra_config.api может принудительно задавать протокол диалога и применяется только к строкам чата / VLLM; переопределение протокола для строк эмбеддингов пишется в spec.compat в поле "api" со значением векторного протокола (openai-embeddings, dashscopeembeddings, arkembeddings, googleembeddings).

Записи каталога ищутся по типу модели: строки эмбеддингов сопоставляются только с записями эмбеддингов, исключая захват диалоговыми масками с тем же префиксом (например, qwen3* от Bailian или gpt-5* от OpenAI). Новые ID, еще отсутствующие в каталоге, и датированные снапшоты обрабатываются по дефолтам поставщика.

На стороне записи также действует проверка: runtime.ValidateRow при создании/обновлении модели (REST) и загрузке config/builtin_models.yaml (при старте) проверяет конфигурацию (для всех типов моделей), отклоняя при создании неизвестные протоколы, опечатки в ключах compat или неверные уровни рассуждений (строки YAML генерируют только варнинг WARN без блокировки старта, исключая отключение рабочих моделей при перезагрузке).

Процедура добавления новых поставщиков, работы с каталогом моделей и реализации поведения поставщиков описана в Руководстве по точкам расширения.

Изменения поведения при обновлении с версии v0.8.0

Строки моделей в старой базе не требуют миграций: колонка parameters пополнилась лишь опциональным полем spec, все значения provider из v0.8.0 продолжают регистрироваться, исторические ключи extra_config (thinking_control со всеми значениями, remote_model_name, api_version, secret_key, region, instruction, truncate_prompt_tokens) сохраняют семантику, а отсутствующие в каталоге ID моделей (кастомные файнтюны, выведенные из эксплуатации версии) разбираются и сохраняются штатно. Это проверяется тестами internal/models/runtime/legacy_rows_test.go и internal/types/legacy_persisted_json_test.go.

При обновлении следует учитывать изменения в поведении выполнения следующих строк моделей.

Диалоговые модели (поставщиковые тесты см. в internal/models/parity/parity_test.go):

1. extra_config.api стал зарезервированным ключом. Теперь это селектор протоколов (openai-completions / openai-responses / anthropic-messages / google-generative-ai / ollama), недопустимые значения возвращают 400 при создании и обновлении модели. Затрагивает только строки, созданные через ручные запросы REST или написание YAML, перед обновлением их следует удалить или исправить.
2. Строки Azure OpenAI без заполненного api_version переведены на плоскость данных GA /openai/v1, вместо старого пути /openai/deployments/{model}/...?api-version=2024-10-21. Для сохранения старого пути явно укажите api_version в дополнительных полях.
3. Прямой трафик для api.openai.com переведен на протокол Responses. Различные прокси и шлюзы продолжают использовать Chat Completions.
4. Поля лимитов вывода для 7 поставщиков приведены в соответствие с документацией: для hunyuan, modelscope, qiniu, requesty, longcat, novita поле изменено с max_completion_tokens обратно на max_tokens, а для moonshot — наоборот, на max_completion_tokens. Aliyun сохраняет max_completion_tokens.

Модели реранкинга (тесты исходящих запросов см. в internal/models/rerank/wire_test.go):

1. OpenAI больше не отображается в списке поставщиков реранкинга. У OpenAI нет интерфейса rerank; шлюзы со встроенным реранкингом за интерфейсом OpenAI следует оформлять как generic. Существующие строки разбираются без изменений.
2. Реранкинг Volcengine ограничивается 200 элементами за запрос (ранее реализация резала по 50 элементов), инструкция по умолчанию изменена на оригинальную консольную Whether the document answers the query or matches the content retrieval intent. Строки с сохраненными в дополнительных полях инструкциями работают без изменений.

Векторные модели (тесты исходящих запросов см. в internal/models/embedding/wire_test.go):

1. Облачные поставщики больше не получают параметр truncate_prompt_tokens, который сохраняется только для generic и gpustack.
2. Поисковые запросы NVIDIA NIM используют input_type: query (для документов используется passage, существующие индексы не затрагиваются), длинные входы обрезаются через truncate: END, параметр dimensions больше не отправляется; из каталога удалены выведенные из эксплуатации NVIDIA модели nv-embed-v1, llama-3.2-nemoretriever-300m-embed-v1, baai/bge-m3.
3. Разделение трафика для Aliyun: текстовые модели используют /compatible-mode/v1/embeddings, а qwen3-vl-embedding, qwen2.5-vl-embedding, tongyi-embedding-vision*, multimodal-embedding* обращаются к нативным мультимодальным интерфейсам. При указании в base_url только хоста, международного сайта или домена бизнес-пространства этот хост сохраняется.