Справочник API: модели и инициализация
Управление моделями, проверка соединений, инициализация баз знаний и запуск задач оценки. Интерфейсы облачного сервиса обеспечивают подключение соответствующих облачных сервисов.
Интерфейсы системной информации и системного администрирования (/system, /system/admin) см. в Система и управление платформой.
Модели (/api/v1/models)
API-ключ: manage_models или full-access.
GET /api/v1/models/providers
Назначение: каталог провайдеров (фронтенд по нему динамически строит выпадающий список провайдеров, значки, дополнительные поля и выбор модели). Права: Viewer+. Параметры запроса: model_type (необязательный: chat/embedding/rerank/vllm/asr; также принимаются внутренние значения бэкенда, например KnowledgeQA; неизвестное значение возвращает 400) — если указан, возвращаются только провайдеры, поддерживающие этот тип, и модели этого типа. Handler: internal/handler/model_catalog.go
Ответ: 200 {"success":true,"data":[ModelProviderDTO]}, каждый элемент:
| Поле | Описание |
|---|---|
value / label / labels / description / descriptions / website | id провайдера, брендовое имя, название и описание по языкам |
icon | data:image/svg+xml;base64,..., можно напрямую использовать в <img src> |
api / auth / requiresAuth | протокол по умолчанию (openai-completions и т. п.), способ аутентификации, нужен ли ключ |
defaultUrls / modelTypes | адреса по умолчанию и поддерживаемые типы по типу модели. defaultUrls возвращается только для Admin+ (или API-ключа full-access / manage_tenant_settings); для остальных вызывающих — пусто |
extraFields | определения дополнительных полей конфигурации провайдера (key,label,labels,type,required,default,placeholder,options,model_types,secret); значения сохраняются в parameters.extra_config |
credentialLabels | названия и подсказки полей ввода учётных данных для некоторых типов моделей (например, в разделе API Key у Volcano Engine и реранкера LKEAP фактически вводятся Access Key ID / SecretId) |
models | встроенный каталог моделей (id,name,type,api,reasoning,input,context_window,max_output_tokens,dimension,thinking_levels,cost,source); source — ссылка на документацию провайдера, на которой основаны параметры модели |
thinking | сводка кодирования рассуждений на уровне провайдера (format, levels) |
order | значение сортировки списка |
curl "$BASE/api/v1/models/providers?model_type=chat" -H "Authorization: Bearer $TOKEN"GET|POST /api/v1/models/catalog/resolve
Назначение: разбор действующей конфигурации подключения (протокол, уровень рассуждений, контекст) по провайдеру, имени модели, base_url и extra_config для отображения в редакторе моделей в реальном времени. Права: Viewer+.
Параметры (в GET — параметры запроса, в POST — JSON-тело, поля одинаковы): provider (ID провайдера), model, base_url, model_type (по умолчанию chat), api, thinking_control, remote_model_name, а также объявленные провайдером дополнительные поля, не являющиеся ключами (например, api_version у Azure). Тело POST может дополнительно содержать объект spec (такой же, как parameters.spec модели) для предпросмотра построчного переопределения каталога. Поля, содержащие ключи, не принимаются.
Ответ: 200 {"success":true,"data":{provider,api,remote_model,cataloged,model,capabilities,base_url,url}}, где capabilities — это {provider,api,cataloged,reasoning,thinking_levels,thinking_format,input,context_window,max_output_tokens,max_tokens_field}. base_url и url (фактический адрес запроса; возвращается только провайдерами, вычисляющими адрес самостоятельно, например Azure) возвращаются только для Admin+ (или API-ключа full-access / manage_tenant_settings). При невозможности разбора возвращается 400. Та же структура capabilities возвращается и в ModelResponse.capabilities удалённых диалоговых/визуальных моделей.
curl "$BASE/api/v1/models/catalog/resolve?provider=deepseek&model=deepseek-v4-pro" -H "Authorization: Bearer $TOKEN"POST /api/v1/models
Назначение: создание модели. Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | Да (binding:"required") | Имя модели |
display_name | string | Нет | Отображаемое имя |
type | string | Да (binding:"required") | Тип модели: KnowledgeQA / Embedding / Rerank / VLLM / ASR (сохраняется как есть; не принимаются фронтенд-значения вроде chat) |
source | string | Да (binding:"required") | Источник (local / remote) |
description | string | Нет | Описание |
parameters | object | Да (binding:"required") | Параметры подключения (base_url, provider, extra_config, spec, context_window и т. д.; поля см. в Управление моделями). При создании можно сразу указать api_key / app_secret; позже они изменяются через подресурс credentials |
parameters проверяется по каталогу моделей (неизвестный протокол, ошибочный compat-ключ, недопустимый уровень рассуждений — 400); base_url проходит проверку SSRF.
Самостоятельно развернутые модели generic / Qwen3-VL-Embedding по умолчанию отправляют независимые входы пакетами через двумерные messages (проверено на vLLM 0.29.0); одиночный вход сохраняет одномерный формат диалога. Для текста действует прежняя пакетизация по BATCH_EMBED_SIZE, лимит пакетной отправки изображений по умолчанию — 5, это консервативная настройка клиента, её можно изменить через parameters.spec.compat.max_image_batch_size. Задачи разбора загруженных файлов по-прежнему планируются по одному изображению, изображения не объединяются между задачами. Если старый сервис не поддерживает двумерные messages, установите parameters.spec.compat.batch_messages=false, чтобы вернуть поштучные запросы; в пресетах WeMM-Embedding пакетная обработка диалогов тоже включена по умолчанию, другим моделям без такого пресета её нужно включать явно.
Пакетирование сохраняет содержимое диалогов и отображение векторных индексов каждого входа, но не гарантирует побитово одинаковый размер батча на стороне сервера. При строгой воспроизводимости проверьте численное поведение стенда; режим Batch Invariance в vLLM нужно включать на сервере и проверять для конкретной модели. Можно задать WEKNORA_EMBEDDING_TEST_URL и WEKNORA_EMBEDDING_TEST_FIXTURE и запустить go test ./internal/models/embedding -run '^TestLiveQwenMessagesBatchParity$' -v -count=1: fixture имеет вид {"texts":[...],"image_paths":[...]}, текстов и изображений должно быть не меньше двух; для приватных/IP-эндпоинтов настройте SSRF_WHITELIST, аутентификацию можно передать через WEKNORA_EMBEDDING_TEST_API_KEY. Тест сравнивает поштучные, пакетные, обратные и повторные поштучные запросы, фиксирует максимальную абсолютную ошибку и минимальную косинусную близость; при превышении строгих порогов падает и ничего не записывает в базу знаний.
Ответ: 201 {"success":true,"data":{ModelResponse}} (id,name,type,source,parameters,is_default,is_builtin,status,credentials,capabilities,...; ответ не содержит ключей)
curl -X POST $BASE/api/v1/models -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"gpt-5.5","type":"KnowledgeQA","source":"remote","parameters":{"provider":"openai","base_url":"https://api.openai.com/v1","api_key":"sk-..."}}'GET /api/v1/models
Назначение: список моделей. Права: Viewer+.
Ответ: 200 {"success":true,"data":[ModelResponse]}
curl $BASE/api/v1/models -H "Authorization: Bearer $TOKEN"GET /api/v1/models/:id
Назначение: сведения о модели. Права: Viewer+.
Ответ: 200 {"success":true,"data":{ModelResponse}}
curl $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/models/:id/copy
Назначение: копирование конфигурации невстроенной модели в текущем пространстве. Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
display_name | string | Да (binding:"required") | Отображаемое имя копии; после удаления начальных и конечных пробелов не должно быть пустым; максимум 255 символов |
Сервер читает полную конфигурацию по ID исходной модели из пути: у копии name остаётся таким же, как у исходной модели; type, source, description, parameters и сохранённые учётные данные копируются вместе; повторная передача с клиента не принимается. Копия не наследует встроенный или статус по умолчанию; уже активированная локальная модель не скачивается повторно, остальные неактивные локальные модели заново попадают в процесс загрузки.
Ответ: 201 {"success":true,"data":{ModelResponse}} (ответ не содержит ключей)
Если исходная модель не существует — 404; если исходная модель встроенная, либо ID или display_name недопустимы — 400.
curl -X POST $BASE/api/v1/models/m-1/copy -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"display_name":"Копия GPT-4o"}'POST /api/v1/models/:id/debug
Назначение: отладка сохранённой модели (выполняется реальный вызов вышестоящего сервиса, что влечёт расходы). Права: Admin+. Поля form-data: input (≤64KB), options (JSON-кодированные параметры отладки: system_prompt, temperature (0~2), top_p, max_tokens (1~8192), thinking, reasoning_effort (off/auto/minimal/low/medium/high/xhigh/max; при установке перекрывает thinking)), documents (JSON-массив, ≤100 элементов), file (необязательно).
Ответ: 200 {"success":true,"data":{"ok",elapsed_ms,request,raw_response,observations,error}}
curl -X POST $BASE/api/v1/models/m-1/debug -H "Authorization: Bearer $TOKEN" -F 'input=Привет'PUT /api/v1/models/:id
Назначение: обновление модели (для встроенных моделей сервисный слой ограничивает SystemAdmin). Права: Admin+ или SystemAdmin (AdminOrSystemAdmin). Тело запроса: name, display_name (указатель), description, parameters (сохранённые ключи сохраняются), source, type (все необязательны).
Ответ: 200 {"success":true,"data":{ModelResponse}}
curl -X PUT $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"display_name":"GPT-4o mini"}'DELETE /api/v1/models/:id
Назначение: удаление модели. Права: Admin+.
Ответ: 200 {"success":true,"message":"Model deleted"}
Если модель всё ещё используется базами знаний, агентами или долговременной памятью текущего пространства, ответ — HTTP 400; совместимое поле message сохраняется, при этом error.code=2300, а error.details указывает конкретные объекты и места ссылок:
{
"success": false,
"error": {
"code": 2300,
"message": "model is used by 2 knowledge base(s); reconfigure or remove those references before deleting",
"details": {
"knowledge_bases": [
{"id": "kb-1", "name": "Product docs", "bindings": ["vlm_model"]},
{"id": "kb-2", "name": "Engineering", "bindings": ["vlm_model"]}
],
"agents": [],
"long_term_memory": {"bindings": []},
"knowledge_base_total": 2,
"agent_total": 0
}
}
}Значения привязок базы знаний: embedding_model, summary_model, image_processing_model, vlm_model, asr_model, wiki_synthesis_model, auto_tag_model; привязки агента: chat_model, rerank_model, vlm_model, asr_model, query_understand_model, follow_up_model; привязки долговременной памяти: embedding_model, extract_model. Детали содержат id, name объекта, объединённые bindings, а также knowledge_base_total / agent_total. Список содержит не более 50 записей каждого вида; защита удаления ориентируется на итоговые счётчики.
curl -X DELETE $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/models/:id/credentials
Назначение: установка ключей модели (ключи не передаются через основной PUT). Права: Admin+ или SystemAdmin. Handler: internal/handler/model_credentials.go
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
api_key | *string | Нет | Новый API Key |
app_secret | *string | Нет | Новый App Secret (если оба опущены, возвращается только статус) |
Ответ: 200 {"success":true,"data":{"fields":{"api_key":{"configured":bool},"app_secret":{"configured":bool}}}}
curl -X PUT $BASE/api/v1/models/m-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"api_key":"sk-..."}'DELETE /api/v1/models/:id/credentials/:field
Назначение: удаление поля ключа (api_key или app_secret). Права: Admin+ или SystemAdmin.
Ответ: 204 No Content
curl -X DELETE $BASE/api/v1/models/m-1/credentials/api_key -H "Authorization: Bearer $TOKEN"Облачный сервис
Handler: internal/handler/weknoracloud.go. API-ключ: manage_models/full.
POST /api/v1/weknoracloud/credentials
Назначение: сохранение учётных данных облачного сервиса (SaaS). Права: Admin+. Тело запроса: {"app_id":"...","app_secret":"..."} (оба binding:"required").
Ответ: 200 {"success":true,"message":"Учётные данные сохранены"}
curl -X POST $BASE/api/v1/weknoracloud/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"app_id":"app","app_secret":"secret"}'GET /api/v1/models/weknoracloud/status
Назначение: проверка готовности облачного сервиса. Права: Viewer+.
Ответ: 200 объект состояния сервиса.
curl $BASE/api/v1/models/weknoracloud/status -H "Authorization: Bearer $TOKEN"Инициализация (/api/v1/initialization)
Handler: internal/handler/initialization.go. Класс конфигурации KB: API-ключ manage_kbs (запись)/retrieve (чтение); класс проверки моделей: manage_models (оба могут быть full-access).
GET /api/v1/initialization/config/:kbId
Назначение: чтение текущей модели/конфигурации разбора KB. Права: Viewer+, KB read.
baseUrl модели возвращается только для Admin+ пространства, которому принадлежит KB (или API-ключа full-access / manage_tenant_settings). Пространства, получившие доступ через общий доступ организации, видят лишь то, настроены ли учётные данные (credentials.*), но не видят адреса моделей и сведения о бакетах хранилища исходного пространства.
Ответ: 200 {"success":true,"data":{"hasFiles",llm,embedding,rerank,multimodal,documentSplitting,nodeExtract,questionGeneration}}
curl $BASE/api/v1/initialization/config/kb-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/initialization/initialize/:kbId
Назначение: инициализация моделей и конфигурации разбора KB (мастер первой настройки). Права: создатель KB ИЛИ Admin+, KB write.
Вызывать может только пространство, которому принадлежит KB; пространству, получившему права редактирования через общий доступ организации, будет отказано (403). Если у KB уже привязаны модели, этот интерфейс обновляет их конфигурацию на месте; этот шаг требует тех же прав, что и PUT /models/:id (Admin+ или API-ключ с capability manage_models), иначе 403.
Основные поля (InitializationRequest):
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
llm.source / llm.modelName | string | Да | Источник LLM и имя модели |
llm.baseUrl / llm.apiKey | string | Нет | Параметры подключения |
embedding.source / embedding.modelName | string | Да | Модель Embedding |
embedding.baseUrl / embedding.apiKey / embedding.dimension | — | Нет | Подключение и размерность |
rerank.enabled + rerank.modelName/baseUrl/apiKey | — | Нет | Конфигурация Rerank |
multimodal.enabled + multimodal.vlm.* + multimodal.storageType + `multimodal.cos.* | minio.*` | — | Нет |
documentSplitting.chunkSize / separators | int / []string | Да | Конфигурация разбиения на фрагменты |
documentSplitting.chunkOverlap | int | Нет | Перекрытие |
nodeExtract.* | — | Нет | Извлечение графа (enabled/text/tags/nodes/relations) |
questionGeneration.* | — | Нет | Генерация вопросов (enabled/questionCount) |
Ответ: 200 {"success":true,"message":"Конфигурация базы знаний обновлена","data":{"models":[Model],"knowledge_base":{KnowledgeBase}}}
curl -X POST $BASE/api/v1/initialization/initialize/kb-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"llm":{"source":"remote","modelName":"gpt-4o-mini"},"embedding":{"source":"remote","modelName":"text-embedding-3-small"},"documentSplitting":{"chunkSize":512,"separators":["\n\n"]}}'PUT /api/v1/initialization/config/:kbId
Назначение: обновление моделей/конфигурации разбиения KB (KBModelConfigRequest: llmModelId обязателен; embeddingModelId, vlm_config, asr_config, documentSplitting.*, multimodal.enabled, storageProvider, storageBackendId, nodeExtract.*, questionGeneration.* необязательны). Права: создатель KB ИЛИ Admin+, KB write.
При доступе через общий доступ организации действующие права общего доступа должны быть admin; editor может редактировать только содержимое, но не менять настройки (403). Привязку хранилища (storageBackendId / storageProvider) может изменять только пространство, которому принадлежит KB; если другое пространство отправит значение, отличное от текущего, вернётся 403.
Ответ: 200 {"success":true,"message":"Конфигурация обновлена"}
curl -X PUT $BASE/api/v1/initialization/config/kb-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"llmModelId":"m-1","embeddingModelId":"m-2"}'GET /api/v1/initialization/ollama/status
Назначение: проверка доступности Ollama. Права: Viewer+.
Ответ: 200 {"success":true,"data":{"available","version","baseUrl","error"}}
curl $BASE/api/v1/initialization/ollama/status -H "Authorization: Bearer $TOKEN"GET /api/v1/initialization/ollama/models
Назначение: список локальных моделей Ollama. Права: Viewer+.
Ответ: 200 {"success":true,"data":{"models":[...]}}
curl $BASE/api/v1/initialization/ollama/models -H "Authorization: Bearer $TOKEN"POST /api/v1/initialization/ollama/models/check
Назначение: массовая проверка наличия моделей. Права: Admin+. Тело запроса: {"models":["llama3"]} (binding:"required").
Ответ: 200 {"success":true,"data":{"models":{"llama3":true}}}
curl -X POST $BASE/api/v1/initialization/ollama/models/check -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"models":["llama3"]}'POST /api/v1/initialization/ollama/models/download
Назначение: загрузка модели Ollama (асинхронная задача). Права: Admin+. Тело запроса: {"modelName":"llama3"} (binding:"required").
Ответ: 200 {"success":true,"data":{"taskId","modelName","status","progress"}}
curl -X POST $BASE/api/v1/initialization/ollama/models/download -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"modelName":"llama3"}'GET /api/v1/initialization/ollama/download/progress/:taskId
Назначение: прогресс задачи загрузки. Права: Viewer+.
Ответ: 200 {"success":true,"data":{id,modelName,status,progress,message,startTime,endTime}}
curl $BASE/api/v1/initialization/ollama/download/progress/task-1 -H "Authorization: Bearer $TOKEN"GET /api/v1/initialization/ollama/download/tasks
Назначение: список всех задач загрузки. Права: Viewer+.
Ответ: 200 {"success":true,"data":[DownloadTask]}
curl $BASE/api/v1/initialization/ollama/download/tasks -H "Authorization: Bearer $TOKEN"Проверка доступности моделей (все POST, права Admin+)
Тело запроса единообразно — ModelTestRequest:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
source | string | Нет | По умолчанию remote |
modelName | string | Да | Имя модели |
baseUrl / apiKey / appSecret | string | Нет | Параметры подключения |
provider / interfaceType | string | Нет | Провайдер/тип интерфейса |
dimension / supportsDimensionOverride | int / bool | Нет | Размерность embedding; указывать ли размерность в запросе |
customHeaders / extraConfig | map | Нет | Расширения |
spec | object | Нет | Построчное переопределение каталога, такое же, как parameters.spec модели |
modelId | string | Нет | ID сохранённой модели: отсутствующие в запросе ключи, extraConfig и spec дополняются из этой модели |
| Конечная точка | Назначение | data в ответе |
|---|---|---|
POST /api/v1/initialization/remote/check | Удалённая доступность LLM | {available,message} |
POST /api/v1/initialization/embedding/test | Проверка Embedding | {available,message,dimension} |
POST /api/v1/initialization/rerank/check | Проверка Rerank | {available,message} |
POST /api/v1/initialization/asr/check | Проверка ASR | {available,message} |
curl -X POST $BASE/api/v1/initialization/remote/check -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"modelName":"gpt-4o-mini","baseUrl":"https://api.openai.com/v1","apiKey":"sk-..."}'POST /api/v1/initialization/multimodal/test
Назначение: сквозная проверка мультимодальности (VLM + хостинг изображений). Права: Admin+. Поля multipart: image (обязательно), vlm_model, vlm_base_url (обязательно), vlm_api_key, vlm_interface_type, storage_type (cos|minio, обязательно) и соответствующие поля cos_*/minio_*, chunk_size, chunk_overlap, separators.
Ответ: 200 {"success":true,"data":{"success","caption","ocr","processing_time"}}
curl -X POST $BASE/api/v1/initialization/multimodal/test -H "Authorization: Bearer $TOKEN" \
-F 'image=@demo.png' -F 'vlm_model=qwen-vl' -F 'vlm_base_url=http://x' -F 'storage_type=minio'POST /api/v1/initialization/extract/text-relation
Назначение: проверка извлечения графа из текста. Права: Admin+. Тело запроса: text (обязательно, ≤5000 символов), tags (обязательно, минимум один), model_id (обязательно).
Ответ: 200 {"success":true,"data":{"nodes":[GraphNode],"relations":[GraphRelation]}}
curl -X POST $BASE/api/v1/initialization/extract/text-relation -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"text":"Иван работает в компании","tags":["человек","компания"],"model_id":"m-1"}'POST /api/v1/initialization/extract/fabri-tag
Назначение: генерация примерных тегов. Права: Admin+. Без тела запроса.
Ответ: 200 {"success":true,"data":{"tags":[...]}}
curl -X POST $BASE/api/v1/initialization/extract/fabri-tag -H "Authorization: Bearer $TOKEN"POST /api/v1/initialization/extract/fabri-text
Назначение: генерация примерного текста по тегам. Права: Admin+. Тело запроса: {"tags":[...],"model_id":"m-1"} (model_id обязателен).
Ответ: 200 {"success":true,"data":{"text":"..."}}
curl -X POST $BASE/api/v1/initialization/extract/fabri-text -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"model_id":"m-1","tags":["человек"]}'Оценка (/api/v1/evaluation)
Handler: internal/handler/evaluation.go. API-ключ: run_evaluations/full.
POST /api/v1/evaluation
Назначение: запуск задачи оценки (с вызовом LLM, что влечёт расходы). Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
dataset_id | string | Нет | ID набора данных |
knowledge_base_id | string | Нет | Целевая KB |
chat_id | string | Нет | ID диалоговой модели |
rerank_id | string | Нет | ID модели Rerank |
Ответ: 200 {"success":true,"data":{задача оценки}}
curl -X POST $BASE/api/v1/evaluation -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"knowledge_base_id":"kb-1","chat_id":"m-1"}'GET /api/v1/evaluation
Назначение: запрос результатов оценки. Права: Viewer+. Параметры запроса: task_id (обязательно).
Ответ: 200 {"success":true,"data":{результат оценки}}
curl "$BASE/api/v1/evaluation?task_id=task-1" -H "Authorization: Bearer $TOKEN"Справочник по реализации
Регистрация маршрутов: internal/router/router.go вызывает RegisterModelRoutes, RegisterInitializationRoutes, RegisterEvaluationRoutes, RegisterWeKnoraCloudRoutes (определены в internal/router/routes_infra.go). Handler: internal/handler/model.go, internal/handler/model_catalog.go, internal/handler/model_credentials.go, internal/handler/initialization.go, internal/handler/evaluation.go, internal/handler/weknoracloud.go.