Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

refactor(models): rebuild vendor integration on protocol + catalog + vendor layers (#3470)

lyingbugc40a9dd1940f
diff --git a/Makefile b/Makefile
index 211641c8e..862960a98 100644
--- a/Makefile
+++ b/Makefile
@@ -44,6 +44,11 @@ help:
@echo " docs 生成 Swagger API 文档"
@echo " install-swagger 安装 swag 工具"
@echo ""
+ @echo "模型厂商目录:"
+ @echo " model-catalog-check 校验厂商目录(不变量 + 新旧行为对照 + 厂商测试)"
+ @echo " model-catalog-diff 对比 models.dev,输出模型元数据差异报告(需人工审阅)"
+ @echo " 可选: make model-catalog-diff VENDOR=deepseek"
+ @echo ""
@echo "环境检查:"
@echo " check-env 检查环境配置"
@echo " list-containers 列出运行中的容器"
@@ -107,6 +112,19 @@ run: build
test:
go test -v ./...
+# Vendor catalog: invariants, legacy-behaviour parity and vendor facts.
+# Run this after adding a vendor or editing any models.json.
+.PHONY: model-catalog-check
+model-catalog-check:
+ go test ./internal/models/parity/ ./internal/models/vendors/ ./internal/models/catalog/ ./internal/models/api/...
+
+# Vendor catalog: report where our model metadata differs from models.dev.
+# Development aid only — nothing is fetched at runtime and nothing is written
+# automatically; review each line against the vendor's own documentation.
+.PHONY: model-catalog-diff
+model-catalog-diff:
+ @python3 scripts/model_catalog_diff.py $(if $(VENDOR),--vendor $(VENDOR),)
+
# Clean build artifacts
clean:
go clean
diff --git a/config/builtin_models.yaml.example b/config/builtin_models.yaml.example
index f0a18a24a..2095d2d76 100644
--- a/config/builtin_models.yaml.example
+++ b/config/builtin_models.yaml.example
@@ -75,3 +75,14 @@ builtin_models: []
# api_key: ${OPENAI_API_KEY}
# provider: openai
# context_window: 200000 # optional; omit to use the 200K default
+# # Optional catalog overrides for chat models. `api` forces the wire
+# # protocol; `compat` is the flat protocol object documented in
+# # internal/models/catalog/compat.go; `thinking_levels` maps the
+# # off/auto/minimal/low/medium/high/xhigh/max ladder to vendor values.
+# # spec:
+# # api: openai-completions
+# # compat:
+# # max_tokens_field: max_tokens
+# # thinking_format: thinking-type
+# # thinking_levels:
+# # xhigh: high
diff --git a/config/models.json.example b/config/models.json.example
new file mode 100644
index 000000000..4fa66eecf
--- /dev/null
+++ b/config/models.json.example
@@ -0,0 +1,61 @@
+{
+ "_comment": [
+ "config/models.json — deployment overlay for the model catalog.",
+ "Copy to config/models.json (or point MODELS_CONFIG at a custom path).",
+ "Same idea as pi's ~/.pi/agent/models.json: 'providers' is keyed by vendor id.",
+ "A known id (see GET /api/v1/models/providers) patches the built-in vendor;",
+ "a new id declares a vendor. String values accept ${ENV} / $ENV interpolation.",
+ "Unknown keys are rejected at startup so typos surface immediately.",
+ "'models' upserts by id: an id that already exists keeps every field you",
+ "did not write (reasoning, thinking_levels, compat, input); a new id is created.",
+ "'icon' is an inline <svg ...> string or an .svg path under this file's own",
+ "directory — no absolute paths, no escaping it, 256 KB max: icons are served",
+ "as a data: URI to everyone who can open the model pages.",
+ "Per-model 'compat' keys depend on the protocol; see internal/models/catalog/compat.go."
+ ],
+ "providers": {
+ "openai": {
+ "base_url": "https://gateway.example.com/openai/v1",
+ "api_key": "${OPENAI_API_KEY}",
+ "headers": {"X-Gateway-Team": "rag"},
+ "model_overrides": {
+ "gpt-5.5": {"context_window": 200000, "max_output_tokens": 32000}
+ }
+ },
+ "aliyun": {
+ "models": [
+ {"id": "qwen3.9-plus", "reasoning": true, "input": ["text", "image"],
+ "context_window": 1000000, "max_output_tokens": 65536,
+ "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}}
+ ]
+ },
+ "lab-vllm": {
+ "name": "Lab vLLM",
+ "names": {"zh-CN": "实验室 vLLM"},
+ "description": "Self-hosted vLLM cluster",
+ "api": "openai-completions",
+ "base_url": "http://vllm.lab.internal:8000/v1",
+ "requires_auth": false,
+ "model_types": ["chat", "embedding"],
+ "url_patterns": ["vllm.lab.internal"],
+ "icon": "icons/lab-vllm.svg",
+ "compat": {"thinking_format": "chat-template-kwargs", "max_tokens_field": "max_tokens"},
+ "models": [
+ {"id": "Qwen/Qwen3-32B", "reasoning": true, "context_window": 131072, "max_output_tokens": 16384},
+ {"id": "BAAI/bge-m3", "type": "Embedding", "dimension": 1024}
+ ]
+ },
+ "claude-proxy": {
+ "name": "Claude via proxy",
+ "api": "anthropic-messages",
+ "base_url": "https://claude-proxy.example.com/v1",
+ "auth": "x-api-key",
+ "api_key": "${CLAUDE_PROXY_KEY}",
+ "models": [
+ {"id": "claude-sonnet-5", "reasoning": true, "input": ["text", "image"],
+ "context_window": 200000, "max_output_tokens": 64000,
+ "compat": {"thinking_mode": "adaptive", "supports_effort": true}}
+ ]
+ }
+ }
+}
diff --git a/docker-compose.yml b/docker-compose.yml
index 35fd3cbdd..5e02f5614 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -56,6 +56,9 @@ services:
# to config/builtin_models.yaml, edit it for your deployment, then
# uncomment the line below. See docs/BUILTIN_MODELS.md.
# - ./config/builtin_models.yaml:/app/config/builtin_models.yaml:ro
+ # Optional: model catalog overlay (extra vendors / model overrides).
+ # Copy config/models.json.example to config/models.json, then
+ # - ./config/models.json:/app/config/models.json:ro
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
diff --git a/frontend/src/api/agent/index.ts b/frontend/src/api/agent/index.ts
index 6b12705fa..8fe975f59 100644
--- a/frontend/src/api/agent/index.ts
+++ b/frontend/src/api/agent/index.ts
@@ -47,6 +47,9 @@ export interface CustomAgentConfig {
temperature?: number;
max_completion_tokens?: number; // 0 = 跟随系统默认(快速问答 2048;智能推理 4096,绑沙箱可写文件时 24576)。大于 0 为自定义上限
thinking?: boolean; // 是否启用思考模式(支持扩展思考的模型)
+ // 思考强度:off | auto | minimal | low | medium | high | xhigh | max。
+ // 为空时退回 thinking 布尔值(true == auto,false == off)。
+ reasoning_effort?: string;
citation_enabled?: boolean; // 是否在最终回答中输出知识库/网页来源引用(默认开启)
// ===== Agent模式设置 =====
diff --git a/frontend/src/api/initialization/index.ts b/frontend/src/api/initialization/index.ts
index 36ded671d..a7bf1b5c4 100644
--- a/frontend/src/api/initialization/index.ts
+++ b/frontend/src/api/initialization/index.ts
@@ -1,5 +1,6 @@
import { get, post, put } from '../../utils/request';
import i18n from '@/i18n'
+import type { ModelCapabilities, ReasoningEffortLevel } from '../model'
const t = (key: string) => i18n.global.t(key)
@@ -579,28 +580,163 @@ export function fabriTag(request: FabriTagRequest): Promise<FabriTagResponse> {
});
}
-// 模型厂商信息类型
+// 厂商额外配置字段(Azure api_version、LKEAP secret_key 等)。
+// Mirrors internal/models/catalog.ExtraField.
+export interface ModelProviderExtraFieldOption {
+ label: string;
+ value: string;
+}
+
+/**
+ * Renames the primary credential input for vendors whose API does not take a
+ * plain API key. LKEAP and Volcengine sign their rerank requests with a
+ * CAM / IAM key pair, so the first field is a SecretId / Access Key ID.
+ * The vendor declares the wording so the editor needs no vendor table.
+ */
+export interface ModelProviderCredentialLabel {
+ label: string;
+ labels?: Record<string, string>;
+ placeholder?: string;
+ placeholders?: Record<string, string>;
+ hint?: string;
+ hints?: Record<string, string>;
+ // Backend model types ("KnowledgeQA", "Rerank", ...); empty = all.
+ model_types?: string[];
+ required?: boolean;
+}
+
+export interface ModelProviderExtraField {
+ key: string;
+ label: string;
+ labels?: Record<string, string>;
+ type: 'string' | 'number' | 'boolean' | 'select' | 'password' | string;
+ required?: boolean;
+ default?: string;
+ placeholder?: string;
+ options?: ModelProviderExtraFieldOption[];
+ // Backend model types ("KnowledgeQA", "Embedding", "Rerank", "VLLM", "ASR"); empty = all.
+ model_types?: string[];
+ // Secret values are never echoed back; they are stored as the app_secret credential.
+ secret?: boolean;
+}
+
+// 厂商内置模型目录条目。Mirrors handler.ModelCatalogEntryDTO.
+export interface ModelCatalogEntry {
+ id: string;
+ name: string;
+ type: string;
+ api?: string;
+ reasoning?: boolean;
+ input?: string[];
+ context_window?: number;
+ max_output_tokens?: number;
+ dimension?: number;
+ thinking_levels?: ReasoningEffortLevel[];
+ cost?: Record<string, unknown>;
+ // Vendor page these facts came from, for the "read the docs" link.
+ source?: string;
+}
+
+export interface ModelProviderThinking {
+ format: string;
+ levels: ReasoningEffortLevel[];
+}
+
+// 模型厂商信息类型。Mirrors handler.ModelProviderDTO — the frontend keeps no
+// vendor table of its own; everything rendered for a vendor comes from here.
export interface ModelProviderOption {
value: string; // provider 标识符
- label: string; // 显示名称
+ label: string; // 显示名称(英文 / 默认)
+ labels?: Record<string, string>; // 按 locale 的显示名称
description: string; // 描述
+ descriptions?: Record<string, string>;
+ website?: string;
+ icon?: string; // data:image/svg+xml;base64,... 可直接用于 <img src>
+ api?: string;
+ auth?: string;
+ requiresAuth?: boolean;
defaultUrls: Record<string, string>; // 按模型类型区分的默认 URL
modelTypes: string[]; // 支持的模型类型
+ extraFields?: ModelProviderExtraField[];
+ credentialLabels?: ModelProviderCredentialLabel[];
+ models?: ModelCatalogEntry[];
+ thinking?: ModelProviderThinking;
+ order?: number;
+}
+
+// 获取模型厂商列表。
+//
+// 失败时 reject(不再吞成空数组):唯一的调用方 stores/modelProviders 需要
+// 区分「后端真的没有厂商」和「这次请求挂了」——把失败当成空列表缓存下来,
+// 会让厂商下拉在整个会话里一直空着,直到用户刷新页面。
+export function listModelProviders(modelType?: string): Promise<ModelProviderOption[]> {
+ const url = modelType
+ ? `/api/v1/models/providers?model_type=${encodeURIComponent(modelType)}`
+ : '/api/v1/models/providers';
+ return get(url).then((response: any) => {
+ const data = response?.data;
+ // Reject rather than coerce: the store distinguishes "this vendor list
+ // is genuinely empty" (cacheable) from "the request did not produce a
+ // list" (retry on the next mount). Returning [] here would make a
+ // malformed 200 look like the former and blank the vendor dropdown and
+ // every card icon for the rest of the session.
+ if (!Array.isArray(data)) {
+ return Promise.reject(new Error('model providers response is not a list'));
+ }
+ return data as ModelProviderOption[];
+ });
}
-// 获取模型厂商列表
-export function listModelProviders(modelType?: string): Promise<ModelProviderOption[]> {
+export interface ResolveModelCatalogParams {
+ provider: string;
+ model?: string;
+ base_url?: string;
+ model_type?: string;
+ api?: string;
+ thinking_control?: string;
+ remote_model_name?: string;
+ // Vendor-declared non-secret extra fields (Azure api_version, ...) are
+ // forwarded by key so the preview resolves the same request the runtime
+ // will make. The backend only accepts keys the vendor declares.
+ [extraField: string]: string | undefined;
+}
+
+// 目录解析结果。Mirrors handler.ResolveModelCatalog response data.
+export interface ResolvedModelCatalog {
+ provider: string;
+ api: string;
+ // base_url and url are only returned to callers who may configure
+ // integrations; a viewer gets the capability answer without the endpoint.
+ base_url?: string;
+ // url is the endpoint the row will actually call, and only vendors that
+ // compute their own URL report one (Azure, whose api_version picks
+ // between the v1 data plane and the dated deployments path).
+ url?: string;
+ remote_model: string;
+ cataloged: boolean;
+ model: Record<string, unknown>;
+ capabilities: ModelCapabilities;
+}
+
+// 解析模型的有效接入配置(协议、思考等级、上下文窗口等),供编辑器实时展示。
+export function resolveModelCatalog(params: ResolveModelCatalogParams): Promise<ResolvedModelCatalog> {
+ const query = new URLSearchParams();
+ for (const [key, value] of Object.entries(params)) {
+ if (value !== undefined && value !== null && String(value).trim() !== '') {
+ query.set(key, String(value).trim());
+ }
+ }
return new Promise((resolve, reject) => {
- const url = modelType
- ? `/api/v1/models/providers?model_type=${encodeURIComponent(modelType)}`
- : '/api/v1/models/providers';
- get(url)
+ get(`/api/v1/models/catalog/resolve?${query.toString()}`)
.then((response: any) => {
- resolve(response.data || []);
+ if (response?.success && response?.data) {
+ resolve(response.data as ResolvedModelCatalog);
+ } else {
+ reject(new Error(response?.message || 'resolve failed'));
+ }
})
.catch((error: any) => {
- console.error('Failed to list model providers:', error);
- resolve([]); // 失败时返回空数组,前端可以回退到默认值
+ reject(error?.error || error);
});
});
}
diff --git a/frontend/src/api/model/index.ts b/frontend/src/api/model/index.ts
index 4ad93f09a..5b5699c88 100644
--- a/frontend/src/api/model/index.ts
+++ b/frontend/src/api/model/index.ts
@@ -6,6 +6,45 @@ export * from './modelUsage'
const t = (key: string) => i18n.global.t(key)
+// Protocol-neutral thinking level. Mirrors internal/models/api.ReasoningEffort.
+export type ReasoningEffortLevel =
+ | 'off'
+ | 'auto'
+ | 'minimal'
+ | 'low'
+ | 'medium'
+ | 'high'
+ | 'xhigh'
+ | 'max'
+
+// Catalog view of a saved chat/VLM model. Mirrors internal/models/catalog.Capabilities.
+// thinking_levels: empty array = the model cannot be asked to think.
+export interface ModelCapabilities {
+ provider: string;
+ api: string;
+ cataloged: boolean;
+ reasoning: boolean;
+ thinking_levels: ReasoningEffortLevel[];
+ thinking_format: string;
+ input?: string[];
+ context_window?: number;
+ max_output_tokens?: number;
+ max_tokens_field?: string;
+}
+
+// Per-row override of a catalog entry. Mirrors internal/types.ModelSpecOverride.
+// compat is the flat, protocol-specific object documented in
+// internal/models/catalog/compat.go (free-form JSON).
+export interface ModelSpecOverride {
+ api?: string;
+ reasoning?: boolean;
+ input?: string[];
+ context_window?: number;
+ max_output_tokens?: number;
+ thinking_levels?: Record<string, string | null>;
+ compat?: Record<string, unknown>;
+}
+
// 模型类型定义
export interface ModelConfig {
id?: string;
@@ -43,7 +82,12 @@ export interface ModelConfig {
// kept on the type so create-mode payloads can still carry them in the
// initial POST body.
app_secret?: string;
+ // Per-model catalog override (protocol, limits, protocol compat knobs).
+ spec?: ModelSpecOverride;
};
+ // Catalog view (chat / VLM remote models only): protocol, thinking levels,
+ // context window. Computed by the backend from provider + name + overrides.
+ capabilities?: ModelCapabilities;
is_default?: boolean;
is_builtin?: boolean;
status?: string;
@@ -171,6 +215,8 @@ export interface ModelDebugOptions {
top_p?: number
max_tokens?: number
thinking?: boolean
+ // Graded thinking level; takes precedence over the boolean when set.
+ reasoning_effort?: ReasoningEffortLevel | string
}
export interface ModelDebugResult {
diff --git a/frontend/src/assets/theme/tdesign-overrides.less b/frontend/src/assets/theme/tdesign-overrides.less
index e48294a26..75f635267 100644
--- a/frontend/src/assets/theme/tdesign-overrides.less
+++ b/frontend/src/assets/theme/tdesign-overrides.less
@@ -21,6 +21,16 @@
border-color: rgba(255, 255, 255, 0.08);
}
+// .wk-popover clips to its rounded corners with overflow:hidden, which also
+// cancels the overflow-y:auto TDesign puts on a select's list — the options
+// past the first screenful become unreachable rather than merely unseen.
+// Restore vertical scrolling for any select wearing this skin; the horizontal
+// axis stays clipped, which is what the rounded corners needed.
+.t-select__dropdown.wk-popover .t-popup__content {
+ overflow-y: auto;
+ overscroll-behavior: contain;
+}
+
// A quiet option surface, with the brand accent reserved for the small check.
.t-select-option.t-is-selected:not(.t-is-disabled),
.t-select-option.t-is-selected:not(.t-is-disabled):hover {
diff --git a/frontend/src/components/ModelDebugDrawer.vue b/frontend/src/components/ModelDebugDrawer.vue
index 55cc000f8..dd734edc7 100644
--- a/frontend/src/components/ModelDebugDrawer.vue
+++ b/frontend/src/components/ModelDebugDrawer.vue
@@ -138,12 +138,24 @@
:autosize="{ minRows: 2, maxRows: 4 }"
/>
</div>
+ <!-- 思考强度:由模型 capabilities.thinking_levels 决定;不能思考的模型不显示 -->
<div v-if="supportsThinking" class="form-item">
- <label class="form-label">{{ $t('modelSettings.debug.thinking') }}</label>
- <div class="switch-field">
- <t-switch v-model="thinking" />
- <span class="form-desc form-desc--inline">{{ $t('modelSettings.debug.thinkingDesc') }}</span>
- </div>
+ <label class="form-label">{{ $t('modelSettings.debug.reasoningEffort') }}</label>
+ <t-select v-model="reasoningEffort" :popup-props="{ overlayClassName: 'reasoning-level-select-popup' }">
+ <t-option v-for="level in reasoningOptions" :key="level" :value="level" :label="$t(levelLabelKey(level))"
+ :show-overflow-tooltip="false">
+ <div class="reasoning-level-option">
+ <span class="reasoning-level-option__title">{{ $t(levelLabelKey(level)) }}</span>
+ <span class="reasoning-level-option__hint">{{ $t(levelDescriptionKey(level)) }}</span>
+ </div>
+ </t-option>
+ </t-select>
+ <p class="form-desc">
+ {{ $t('modelSettings.debug.reasoningEffortDesc') }}
+ <template v-if="selectedModel.capabilities?.thinking_format">
+ · <code>{{ selectedModel.capabilities.thinking_format }}</code>
+ </template>
+ </p>
</div>
</section>
@@ -204,7 +216,16 @@ import { copyWithToast } from '@/utils/clipboard'
import SettingDrawer from '@/components/settings/SettingDrawer.vue'
import { debugModel, type ModelConfig, type ModelDebugResult } from '@/api/model'
import { fileSizeVerification } from '@/utils'
-import { modelSupportsThinking } from '@/utils/thinkingControl'
+import { useModelProvidersStore } from '@/stores/modelProviders'
+import {
+ clampLevel,
+ levelDescriptionKey,
+ levelEnablesThinking,
+ levelLabelKey,
+ modelCanThink,
+ supportedLevels,
+ type ReasoningLevel,
+} from '@/utils/reasoningEffort'
import {
formatContextWindow,
modelHasContextWindow,
@@ -219,7 +240,8 @@ const emit = defineEmits<{
(e: 'update:visible', value: boolean): void
}>()
-const { t, te } = useI18n()
+const { t, locale } = useI18n()
+const providersStore = useModelProvidersStore()
const drawerVisible = computed({
get: () => props.visible,
set: value => emit('update:visible', value),
@@ -233,7 +255,7 @@ const input = ref('')
const documentsText = ref('')
const file = ref<File | null>(null)
const fileInputRef = ref<HTMLInputElement | null>(null)
-const thinking = ref(false)
+const reasoningEffort = ref<ReasoningLevel>('off')
const temperature = ref(0.7)
const topP = ref(1)
const maxTokens = ref(1024)
@@ -251,7 +273,10 @@ let runSequence = 0
const selectedModel = computed(() => props.models.find(model => model.id === selectedModelId.value))
const filteredModels = computed(() => props.models.filter(model => model.type === selectedModelType.value))
const isChat = computed(() => selectedModel.value?.type === 'KnowledgeQA')
-const supportsThinking = computed(() => selectedModel.value ? modelSupportsThinking(selectedModel.value) : false)
+// Thinking is offered only when the catalog says the model can think
+// (remote chat models carry `capabilities` computed by the backend).
+const supportsThinking = computed(() => modelCanThink(selectedModel.value?.capabilities))
+const reasoningOptions = computed(() => supportedLevels(selectedModel.value?.capabilities))
const needsFile = computed(() => ['VLLM', 'ASR'].includes(selectedModel.value?.type || ''))
const documents = computed(() => documentsText.value.split('\n').map(item => item.trim()).filter(Boolean))
const canRun = computed(() => {
@@ -289,8 +314,8 @@ const vendorLabel = (model: ModelConfig) => {
const provider = model.parameters.provider || ''
if (model.source === 'local') return 'Ollama'
if (provider === 'generic') return t('modelSettings.source.custom')
- const key = `model.editor.providers.${provider}.label`
- return te(key) ? t(key) : provider || model.source
+ if (!provider) return model.source
+ return providersStore.labelFor(provider, String(locale.value || '')) || provider
}
const inputLabel = computed(() => {
@@ -321,6 +346,9 @@ const formattedResult = computed(() => {
})
const OBSERVATION_LABELS: Record<string, string> = {
+ api: 'modelSettings.debug.metrics.api',
+ thinking_format: 'modelSettings.debug.metrics.thinkingFormat',
+ requested_reasoning_effort: 'modelSettings.debug.metrics.requestedReasoningEffort',
dimension: 'modelSettings.debug.metrics.dimension',
result_count: 'modelSettings.debug.metrics.resultCount',
answer_characters: 'modelSettings.debug.metrics.answerChars',
@@ -332,7 +360,16 @@ const OBSERVATION_LABELS: Record<string, string> = {
const resultMetrics = computed(() => {
if (!result.value?.observations) return []
- const obs = result.value.observations
+ // Flatten the nested capabilities object the backend attaches so the
+ // effective thinking encoding shows up next to the protocol.
+ const raw = result.value.observations
+ const caps = raw.capabilities as { thinking_format?: unknown } | undefined
+ const obs: Record<string, unknown> = {
+ ...raw,
+ ...(caps && typeof caps === 'object' && caps.thinking_format !== undefined
+ ? { thinking_format: caps.thinking_format }
+ : {}),
+ }
const keys = Object.keys(OBSERVATION_LABELS).filter(key => obs[key] !== undefined && obs[key] !== null)
return keys.map(key => ({
key,
@@ -345,6 +382,9 @@ const formatMetricValue = (key: string, value: unknown) => {
if (typeof value === 'boolean') {
return value ? t('common.yes') : t('common.no')
}
+ if (key === 'requested_reasoning_effort' && typeof value === 'string' && value) {
+ return t(levelLabelKey(value))
+ }
return String(value)
}
@@ -364,7 +404,10 @@ const ensureDefaultSelection = () => {
}
watch(() => props.visible, visible => {
- if (visible) ensureDefaultSelection()
+ if (visible) {
+ ensureDefaultSelection()
+ void providersStore.ensureLoaded('').catch(() => {})
+ }
})
watch(availableModelTypes, () => {
@@ -372,8 +415,8 @@ watch(availableModelTypes, () => {
})
watch(() => selectedModel.value?.id, () => {
- if (!supportsThinking.value) thinking.value = false
-})
+ reasoningEffort.value = clampLevel(reasoningEffort.value, reasoningOptions.value)
+}, { immediate: true })
watch(() => selectedModel.value?.type, () => {
file.value = null
@@ -417,9 +460,9 @@ const formatBytes = (bytes: number) => {
return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
}
-const historyLabel = (thinkingValue: boolean) => {
- if (supportsThinking.value) {
- return thinkingValue ? t('modelSettings.debug.thinkOn') : t('modelSettings.debug.thinkOff')
+const historyLabel = (level: ReasoningLevel | null) => {
+ if (level) {
+ return `${t('modelSettings.debug.reasoningEffort')}: ${t(levelLabelKey(level))}`
}
return t('modelSettings.debug.runLabel', { n: runSequence })
}
@@ -428,7 +471,7 @@ const runDebug = async () => {
if (!selectedModel.value?.id || !canRun.value || running.value) return
running.value = true
try {
- const thinkingValue = supportsThinking.value ? thinking.value : false
+ const level: ReasoningLevel | null = supportsThinking.value ? reasoningEffort.value : null
const nextResult = await debugModel(selectedModel.value.id, {
input: input.value.trim(),
documents: documents.value,
@@ -438,13 +481,14 @@ const runDebug = async () => {
temperature: temperature.value,
top_p: topP.value,
max_tokens: maxTokens.value,
- thinking: thinkingValue,
+ // reasoning_effort is authoritative; the boolean keeps older backends working.
+ ...(level ? { reasoning_effort: level, thinking: levelEnablesThinking(level) } : { thinking: false }),
} : {},
})
result.value = nextResult
history.value.unshift({
id: ++runSequence,
- label: historyLabel(thinkingValue),
+ label: historyLabel(level),
result: nextResult,
})
history.value = history.value.slice(0, 6)
@@ -571,11 +615,9 @@ onBeforeUnmount(() => {
}
}
-.switch-field {
- display: flex;
- align-items: center;
- gap: 8px;
- min-height: 32px;
+.form-desc code {
+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+ font-size: var(--app-text-xs);
}
.file-picker {
@@ -714,3 +756,37 @@ onBeforeUnmount(() => {
}
}
</style>
+
+<!-- 非 scoped:t-select popup 渲染到 body 下 -->
+<style lang="less">
+.reasoning-level-select-popup {
+ padding: 4px;
+
+ .t-select-option {
+ height: auto !important;
+ padding: 6px 10px;
+ border-radius: 6px;
+ margin: 2px 0;
+ white-space: normal;
+ }
+}
+
+.reasoning-level-option {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ line-height: 1.35;
+ min-width: 0;
+
+ &__title {
+ font-size: var(--app-text-md);
+ color: var(--td-text-color-primary);
+ }
+
+ &__hint {
+ font-size: var(--app-text-sm);
+ color: var(--td-text-color-placeholder);
+ word-break: break-word;
+ }
+}
+</style>
diff --git a/frontend/src/components/ModelEditorDialog.vue b/frontend/src/components/ModelEditorDialog.vue
index 5b27b0214..aa1696828 100644
--- a/frontend/src/components/ModelEditorDialog.vue
+++ b/frontend/src/components/ModelEditorDialog.vue
@@ -172,20 +172,45 @@
<div class="form-item">
<label class="form-label">{{ $t('model.editor.providerLabel') }}</label>
<t-select v-model="formData.provider" :placeholder="$t('model.editor.providerPlaceholder')"
- @change="handleProviderChange" :popup-props="{ overlayClassName: 'provider-select-popup' }">
+ :loading="loadingProviders" filterable
+ @change="handleProviderChange"
+ :popup-props="{ overlayClassName: 'wk-popover provider-select-popup', overlayInnerStyle: matchTriggerWidth }">
+ <!--
+ 已选值:图标 + 本地化名称(描述只在下拉里展示,避免输入框过长)。
+ 目录里已经没有这个 provider 时(厂商下线 / 旧数据)退回显示原始 id,
+ 否则输入框会整个空掉,看起来像"没选厂商",但保存时仍会带上它。
+ -->
+ <template #valueDisplay>
+ <span v-if="formData.provider" class="provider-value">
+ <img v-if="selectedProviderIcon" :src="selectedProviderIcon" class="provider-icon" alt="" />
+ <span class="provider-value__name">{{ selectedProviderDisplayLabel }}</span>
+ </span>
+ </template>
<!--
show-overflow-tooltip=false: TDesign 默认在 hover 时给选项浮一个
完整 label 的小气泡,但这里选项本身就是双行(主名 + 描述),不会
出现省略,tooltip 只会和已经命中的灰底打架。直接关掉。
-->
- <t-option v-for="opt in providerOptions" :key="opt.value" :value="opt.value" :label="opt.label"
- :show-overflow-tooltip="false">
+ <t-option v-for="opt in providerOptions" :key="opt.value" :value="opt.value"
+ :label="providerDisplayLabel(opt)" :show-overflow-tooltip="false">
<div class="provider-option">
- <span class="provider-name">{{ opt.label }}</span>
- <span class="provider-desc">{{ opt.description }}</span>
+ <img v-if="providerIcon(opt)" :src="providerIcon(opt)" class="provider-icon" alt="" />
+ <span v-else class="provider-icon provider-icon--placeholder" aria-hidden="true">
+ {{ providerDisplayLabel(opt).slice(0, 1) }}
+ </span>
+ <div class="provider-option__text">
+ <span class="provider-name">{{ providerDisplayLabel(opt) }}</span>
+ <span class="provider-desc">{{ providerDisplayDescription(opt) }}</span>
+ </div>
</div>
</t-option>
</t-select>
+ <p v-if="vendorDocLink" class="form-desc provider-doc-link">
+ <a :href="vendorDocLink" target="_blank" rel="noopener noreferrer">
+ {{ $t('model.editor.providerDocs', { provider: selectedProviderDisplayLabel }) }}
+ <t-icon name="jump" size="12px" />
+ </a>
+ </p>
</div>
<!-- WeKnoraCloud 提示信息 -->
@@ -230,11 +255,54 @@
</div>
</template>
- <!-- 模型名称 -->
+ <!--
+ 模型名称:厂商内置目录做候选,同时允许自由输入(filterable + creatable)。
+ 选中目录内模型时自动带出上下文窗口 / 输出上限 / 视觉 / 维度(仅填空字段)。
+ -->
<div class="form-item">
<label class="form-label required">{{ $t('model.modelName') }}</label>
- <t-input v-model="formData.modelName" :placeholder="getModelNamePlaceholder()"
- :disabled="formData.provider === 'weknoracloud' && wkcCredentialState !== 'configured'" />
+ <!--
+ 没有内置目录时用纯输入框:TDesign 的 select 在零选项时会隐藏整个
+ 浮层(hideEmptyPopup),连 creatable 的"创建"行也一并藏掉,于是
+ 用户能打字、但没有任何方式提交,失焦后输入直接丢失。自定义
+ (OpenAI 兼容接口) 正是这种情况,所以那里根本填不进模型名。
+ -->
+ <t-input
+ v-if="catalogModelOptions.length === 0"
+ v-model="formData.modelName"
+ :placeholder="getModelNamePlaceholder()"
+ :disabled="formData.provider === 'weknoracloud' && wkcCredentialState !== 'configured'"
+ clearable
+ autocomplete="off"
+ spellcheck="false"
+ />
+ <t-select
+ v-else
+ v-model="formData.modelName"
+ filterable
+ creatable
+ clearable
+ :placeholder="getModelNamePlaceholder()"
+ :disabled="formData.provider === 'weknoracloud' && wkcCredentialState !== 'configured'"
+ :popup-props="{ overlayClassName: 'wk-popover catalog-model-select-popup', overlayInnerStyle: matchTriggerWidth }"
+ @create="handleCatalogModelCreate"
+ @change="handleCatalogModelChange"
+ >
+ <t-option v-for="opt in catalogModelOptions" :key="opt.value" :value="opt.value" :label="opt.label"
+ :show-overflow-tooltip="false">
+ <div class="catalog-model-option">
+ <span class="catalog-model-option__name">{{ opt.label }}</span>
+ <span v-if="opt.value !== opt.label" class="catalog-model-option__id">{{ opt.value }}</span>
+ <span class="catalog-model-option__badges">
+ <span v-if="opt.contextWindow" class="catalog-badge">{{ opt.contextWindow }}</span>
+ <span v-if="opt.dimension" class="catalog-badge">{{ $t('model.editor.dimensionLabel') }} {{ opt.dimension }}</span>
+ <span v-if="opt.reasoning" class="catalog-badge catalog-badge--accent">{{ $t('model.editor.catalog.reasoning') }}</span>
+ <span v-if="opt.vision" class="catalog-badge catalog-badge--accent">{{ $t('model.editor.catalog.vision') }}</span>
+ </span>
+ </div>
+ </t-option>
+ </t-select>
+ <p v-if="catalogModelOptions.length > 0" class="form-desc">{{ $t('model.editor.catalog.hint') }}</p>
</div>
<div class="form-item">
@@ -249,9 +317,7 @@
</div>
<div v-if="formData.provider !== 'weknoracloud'" class="form-item">
- <label class="form-label">{{
- isSignedRerank ? signedRerankAccessKeyLabel : $t('model.editor.apiKeyOptional')
- }}</label>
+ <label class="form-label" :class="{ required: apiKeyRequired }">{{ apiKeyLabel }}</label>
<!--
Edit mode: credentials live behind the /credentials subresource
of the model — managed by the shared CredentialResource card,
@@ -266,26 +332,49 @@
<CredentialResource v-if="isEdit && props.modelData?.id" :api="credentialApi" :fields="credentialFields"
:meta="credentialMeta" @changed="invalidateConnectionTest()" />
<t-input v-else v-model="formData.apiKey" type="password"
- :placeholder="isSignedRerank ? signedRerankAccessKeyPlaceholder : apiKeyPlaceholder"
+ :placeholder="apiKeyPlaceholder"
class="api-key-input" autocomplete="off" spellcheck="false">
<template #prefix-icon><t-icon name="lock-on" /></template>
</t-input>
- <p v-if="isSignedRerank" class="form-desc">{{ signedRerankCredentialHint }}</p>
+ <p v-if="apiKeyHint" class="form-desc">{{ apiKeyHint }}</p>
</div>
- <!-- AK/SK Rerank 创建模式:SecretKey(编辑模式由 CredentialResource 管理) -->
- <div v-if="isSignedRerank && !isEdit" class="form-item">
- <label class="form-label required">{{ signedRerankSecretKeyLabel }}</label>
+ <!--
+ 厂商声明的 secret 额外字段(LKEAP / 火山引擎 Rerank 的 SecretKey 等):
+ 创建模式写入 app_secret;编辑模式由上面的 CredentialResource 卡片管理。
+ -->
+ <div v-if="secretExtraField && !isEdit && formData.provider !== 'weknoracloud'" class="form-item">
+ <label class="form-label" :class="{ required: secretExtraField.required }">{{ extraFieldDisplayLabel(secretExtraField) }}</label>
<t-input v-model="formData.appSecret" type="password"
- :placeholder="signedRerankSecretKeyPlaceholder" autocomplete="off" spellcheck="false">
+ :placeholder="secretExtraField.placeholder || ''" autocomplete="off" spellcheck="false">
<template #prefix-icon><t-icon name="lock-on" /></template>
</t-input>
+ <p v-if="secretExtraField.placeholder" class="form-desc">{{ secretExtraField.placeholder }}</p>
</div>
- <div v-if="isLkeapRerank" class="form-item">
- <label class="form-label">{{ $t('model.editor.lkeap.regionLabel') }}</label>
- <t-input v-model="formData.lkeapRegion" :placeholder="$t('model.editor.lkeap.regionPlaceholder')" />
- <p class="form-desc">{{ $t('model.editor.lkeap.regionDesc') }}</p>
+ <!-- 厂商声明的其余额外字段:按 type 动态渲染,值存入 extra_config[key] -->
+ <div v-for="field in plainExtraFields" :key="field.key" class="form-item">
+ <label class="form-label" :class="{ required: field.required }">{{ extraFieldDisplayLabel(field) }}</label>
+ <div v-if="field.type === 'boolean'" class="vision-toggle">
+ <t-switch :model-value="extraConfigBool(field.key)"
+ @update:model-value="(v: boolean) => setExtraConfig(field.key, v ? 'true' : 'false')" />
+ <span v-if="field.placeholder" class="form-desc form-desc--inline">{{ field.placeholder }}</span>
+ </div>
+ <t-select v-else-if="field.type === 'select'" :model-value="formData.extraConfig[field.key] || ''"
+ :placeholder="field.placeholder || ''" clearable
+ @update:model-value="(v: string) => setExtraConfig(field.key, v)">
+ <t-option v-for="opt in (field.options || [])" :key="opt.value" :value="opt.value" :label="opt.label || opt.value" />
+ </t-select>
+ <t-input v-else-if="field.type === 'number'" :model-value="formData.extraConfig[field.key] || ''"
+ type="number" :placeholder="field.placeholder || ''"
+ @update:model-value="(v: string | number) => setExtraConfig(field.key, String(v ?? ''))" />
+ <t-input v-else-if="field.type === 'password'" :model-value="formData.extraConfig[field.key] || ''"
+ type="password" :placeholder="field.placeholder || ''" autocomplete="off" spellcheck="false"
+ @update:model-value="(v: string) => setExtraConfig(field.key, v)">
+ <template #prefix-icon><t-icon name="lock-on" /></template>
+ </t-input>
+ <t-input v-else :model-value="formData.extraConfig[field.key] || ''" :placeholder="field.placeholder || ''"
+ @update:model-value="(v: string) => setExtraConfig(field.key, v)" />
</div>
<!-- 自定义 HTTP Header(类似 OpenAI Python SDK 的 extra_headers) -->
@@ -312,6 +401,66 @@
</div>
</div>
+ <!--
+ 接入诊断:由后端目录实时解析出的有效协议 / 思考格式 / 支持等级 /
+ 是否目录内 / 上下文窗口,只读。厂商、模型名、Base URL 变化后 400ms 防抖刷新。
+ 仅对话 / VLM 有意义——Embedding、ReRank、ASR 既没有思考等级也没有
+ 上下文窗口,展示出来只会让人以为这些值对它们生效。
+ -->
+ <div v-if="showResolvedPanel" class="form-item">
+ <div class="resolved-panel" aria-live="polite">
+ <div class="resolved-panel__header">
+ <t-icon name="system-code" class="resolved-panel__icon" />
+ <span class="resolved-panel__title">{{ $t('model.editor.resolved.title') }}</span>
+ <t-icon v-if="resolving" name="loading" class="spinning resolved-panel__loading" />
+ </div>
+ <p v-if="!resolved && !resolving && !resolveFailed" class="form-desc">{{ $t('model.editor.resolved.empty') }}</p>
+ <!-- 后端错误体形态不固定,取不到可读文案时只显示标题,不显示 [object Object] -->
+ <p v-else-if="resolveFailed" class="form-desc form-desc--warn">
+ {{ $t('model.editor.resolved.failed') }}<template v-if="resolveError">: {{ resolveError }}</template>
+ </p>
+ <dl v-else-if="resolved" class="resolved-panel__grid">
+ <dt>{{ $t('model.editor.resolved.protocol') }}</dt>
+ <dd><code>{{ resolved.api }}</code></dd>
+ <dt>{{ $t('model.editor.resolved.catalog') }}</dt>
+ <dd>
+ <span class="catalog-badge" :class="{ 'catalog-badge--accent': resolved.cataloged }">
+ {{ resolved.cataloged ? $t('model.editor.resolved.catalogedYes') : $t('model.editor.resolved.catalogedNo') }}
+ </span>
+ </dd>
+ <template v-if="resolved.url">
+ <dt>{{ $t('model.editor.resolved.endpoint') }}</dt>
+ <dd><code class="resolved-endpoint">{{ resolved.url }}</code></dd>
+ </template>
+ <template v-if="resolved.remote_model && resolved.remote_model !== formData.modelName">
+ <dt>{{ $t('model.editor.advanced.remoteModelName.label') }}</dt>
+ <dd><code>{{ resolved.remote_model }}</code></dd>
+ </template>
+ <template v-if="isChatLike">
+ <dt>{{ $t('model.editor.resolved.thinkingFormat') }}</dt>
+ <dd><code>{{ resolved.capabilities?.thinking_format || '-' }}</code></dd>
+ <dt>{{ $t('model.editor.resolved.thinkingLevels') }}</dt>
+ <dd>
+ <template v-if="resolvedThinkingLevels.length > 0">
+ <span v-for="level in resolvedThinkingLevels" :key="level" class="catalog-badge">
+ {{ $t(levelLabelKey(level)) }}
+ </span>
+ </template>
+ <span v-else class="form-desc form-desc--inline">{{ $t('model.editor.resolved.noThinking') }}</span>
+ </dd>
+ <template v-if="resolved.capabilities?.context_window">
+ <dt>{{ $t('model.editor.contextWindowLabel') }}</dt>
+ <dd>{{ formatTokenCount(resolved.capabilities.context_window) }}</dd>
+ </template>
+ <template v-if="resolved.capabilities?.max_output_tokens">
+ <dt>{{ $t('model.editor.maxOutputTokensLabel') }}</dt>
+ <dd>{{ formatTokenCount(resolved.capabilities.max_output_tokens) }}</dd>
+ </template>
+ </template>
+ </dl>
+ </div>
+ </div>
+
<!--
Connection test action moved to the drawer footer (footer-left
slot above) so primary actions live in one row at the bottom.
@@ -320,7 +469,7 @@
</template>
<!-- Section 3 — 高级选项(仅在有内容时渲染,避免空 section 出现底部分隔线) -->
- <section v-if="['embedding', 'chat', 'vllm'].includes(activeModelType)" class="setting-drawer__section">
+ <section v-if="['embedding', 'chat', 'vllm'].includes(activeModelType) || formData.source === 'remote'" class="setting-drawer__section">
<h4 class="setting-drawer__section-title">{{ $t('model.editor.sectionAdvanced') }}</h4>
<!-- Embedding 专用:维度 -->
@@ -367,29 +516,12 @@
</div>
</div>
- <!-- Chat + 远程 API:思考模式参数格式 -->
- <div v-if="showThinkingControlField" class="form-item">
- <label class="form-label">{{ $t('model.editor.thinkingControlLabel') }}</label>
- <t-select
- v-model="formData.thinkingControl"
- :key="`thinking-${formData.id}-${formData.thinkingControl}`"
- :popup-props="{ overlayClassName: 'thinking-control-select-popup' }"
- @change="onThinkingControlManualPick"
- >
- <t-option
- v-for="opt in thinkingControlOptions"
- :key="opt.value"
- :value="opt.value"
- :label="opt.label"
- :show-overflow-tooltip="false"
- >
- <div class="thinking-control-option">
- <span class="thinking-control-option__title">{{ opt.label }}</span>
- <span class="thinking-control-option__hint">{{ opt.hint }}</span>
- </div>
- </t-option>
- </t-select>
- <p class="form-desc">{{ $t('model.editor.thinkingControlDesc') }}</p>
+ <!-- Chat / VLM: max output tokens (catalog default when empty). -->
+ <div v-if="activeModelType === 'chat' || activeModelType === 'vllm'" class="form-item">
+ <label class="form-label">{{ $t('model.editor.maxOutputTokensLabel') }}</label>
+ <t-input v-model.number="formData.maxOutputTokens" type="number" :min="1" :max="10000000"
+ :placeholder="$t('model.editor.maxOutputTokensPlaceholder')" />
+ <p class="form-desc">{{ $t('model.editor.maxOutputTokensDesc') }}</p>
</div>
<!--
@@ -397,12 +529,64 @@
are gated by the governor (see internal/models/limiter), so we surface
it just for those three. 0 = fall back to the global default.
-->
- <div class="form-item">
+ <div v-if="['embedding', 'chat', 'vllm'].includes(activeModelType)" class="form-item">
<label class="form-label">{{ $t('model.editor.maxConcurrencyLabel') }}</label>
<t-input v-model.number="formData.maxConcurrency" type="number" :min="0" :max="4096"
:placeholder="$t('model.editor.maxConcurrencyPlaceholder')" />
<p class="form-desc">{{ $t('model.editor.maxConcurrencyDesc') }}</p>
</div>
+
+ <!--
+ 高级:协议覆盖 / 远端模型名 / 目录 compat 覆盖,以及仅旧数据才显示的
+ thinking_control 兼容选择。默认折叠,绝大多数用户无需触碰。
+ -->
+ <template v-if="formData.source === 'remote' && formData.provider !== 'weknoracloud'">
+ <button type="button" class="advanced-toggle" :aria-expanded="advancedOpen" @click="advancedOpen = !advancedOpen">
+ <t-icon name="chevron-right" class="toggle-arrow" :class="{ open: advancedOpen }" />
+ <span>{{ $t('model.editor.advanced.toggle') }}</span>
+ </button>
+
+ <template v-if="advancedOpen">
+ <div class="form-item">
+ <label class="form-label">{{ $t('model.editor.advanced.api.label') }}</label>
+ <t-select :model-value="formData.extraConfig.api || ''" clearable
+ @update:model-value="(v: string) => setExtraConfig('api', v)">
+ <t-option value="" :label="$t('model.editor.advanced.api.auto')" />
+ <t-option v-for="api in PROTOCOL_OPTIONS" :key="api" :value="api" :label="api" />
+ </t-select>
+ <p class="form-desc">{{ $t('model.editor.advanced.api.desc') }}</p>
+ </div>
+
+ <div class="form-item">
+ <label class="form-label">{{ $t('model.editor.advanced.remoteModelName.label') }}</label>
+ <t-input :model-value="formData.extraConfig.remote_model_name || ''"
+ :placeholder="$t('model.editor.advanced.remoteModelName.placeholder')"
+ @update:model-value="(v: string) => setExtraConfig('remote_model_name', v)" />
+ <p class="form-desc">{{ $t('model.editor.advanced.remoteModelName.desc') }}</p>
+ </div>
+
+ <!-- 仅旧数据:extra_config.thinking_control 存在时才显示,可清空改走目录默认 -->
+ <div v-if="showLegacyThinkingControl" class="form-item">
+ <label class="form-label">{{ $t('model.editor.advanced.legacyThinking.label') }}</label>
+ <t-select :model-value="formData.thinkingControl || ''"
+ @update:model-value="(v: string) => formData.thinkingControl = v">
+ <t-option value="" :label="$t('model.editor.advanced.legacyThinking.catalog')" />
+ <t-option v-for="opt in LEGACY_THINKING_CONTROL_VALUES" :key="opt" :value="opt"
+ :label="opt === 'none' ? $t('model.editor.advanced.legacyThinking.none') : opt" />
+ </t-select>
+ <p class="form-desc form-desc--warn">{{ $t('model.editor.advanced.legacyThinking.desc') }}</p>
+ </div>
+
+ <div class="form-item">
+ <label class="form-label">{{ $t('model.editor.advanced.compat.label') }}</label>
+ <t-textarea v-model="formData.specCompat" :autosize="{ minRows: 3, maxRows: 10 }"
+ :placeholder="$t('model.editor.advanced.compat.placeholder')" class="compat-textarea"
+ :status="specCompatError ? 'error' : undefined" />
+ <p v-if="specCompatError" class="form-desc form-desc--error">{{ $t('model.editor.advanced.compat.invalid') }}: {{ specCompatError }}</p>
+ <p v-else class="form-desc">{{ $t('model.editor.advanced.compat.desc') }}</p>
+ </div>
+ </template>
+ </template>
</section>
</t-form>
@@ -412,21 +596,33 @@
<script setup lang="ts">
import { ref, watch, computed, onUnmounted, nextTick } from 'vue'
import { MessagePlugin, DialogPlugin } from 'tdesign-vue-next'
-import { checkOllamaModels, checkRemoteModel, testEmbeddingModel, checkRerankModel, checkASRModel, listOllamaModels, downloadOllamaModel, getDownloadProgress, checkOllamaStatus, listModelProviders, type OllamaModelInfo, type ModelProviderOption } from '@/api/initialization'
+import {
+ checkOllamaModels, checkRemoteModel, testEmbeddingModel, checkRerankModel, checkASRModel, listOllamaModels,
+ downloadOllamaModel, getDownloadProgress, checkOllamaStatus, resolveModelCatalog,
+ type OllamaModelInfo, type ModelProviderOption, type ModelProviderExtraField, type ModelCatalogEntry,
+ type ResolvedModelCatalog,
+} from '@/api/initialization'
import {
getWeKnoraCloudStatus,
putModelCredentials,
deleteModelCredentialField,
type ModelCredentialField,
+ type ModelSpecOverride,
} from '@/api/model'
import { useI18n } from 'vue-i18n'
import { useUIStore } from '@/stores/ui'
+import { useModelProvidersStore } from '@/stores/modelProviders'
import {
- defaultThinkingControl,
- resolveThinkingControl,
- type ThinkingControlValue,
-} from '@/utils/thinkingControl'
-import { DEFAULT_MODEL_CONTEXT_WINDOW } from '@/utils/contextWindow'
+ credentialLabelForModelType,
+ extraFieldLabel,
+ extraFieldsForModelType,
+ pickLocalized,
+ providerDescription,
+ providerIcon,
+ providerLabel,
+} from '@/stores/modelProvidersState'
+import { levelLabelKey, supportedLevels } from '@/utils/reasoningEffort'
+import { DEFAULT_MODEL_CONTEXT_WINDOW, formatTokenCount } from '@/utils/contextWindow'
import { copyWithToast } from '@/utils/clipboard'
import SettingDrawer from '@/components/settings/SettingDrawer.vue'
import CredentialResource, {
@@ -458,16 +654,44 @@ interface ModelFormData {
contextWindow?: number
/** 后台任务对该模型的并发上限;0/undefined 表示沿用全局默认。仅 chat/embedding/vllm 生效。 */
maxConcurrency?: number
- /** extra_config.thinking_control — how agent thinking on/off maps to API fields. */
+ /** 对话/VLM 单次输出上限(token)。空/0 表示使用目录默认。 */
+ maxOutputTokens?: number
+ /**
+ * Legacy extra_config.thinking_control (none | enable_thinking | thinking_type
+ * | chat_template_kwargs). Only rows saved by older UIs carry it; the catalog
+ * decides the encoding otherwise. Empty string = drop the key on save.
+ */
thinkingControl?: string
+ /**
+ * Provider-specific extra_config entries: vendor-declared extra fields
+ * (api_version, region, ...) plus the advanced overrides `api` and
+ * `remote_model_name`. thinking_control lives in its own field above.
+ */
+ extraConfig: Record<string, string>
+ /** parameters.spec.compat as JSON text (validated before save). */
+ specCompat?: string
+ /** Other parameters.spec fields preserved verbatim from the loaded row. */
+ spec?: ModelSpecOverride | null
// 自定义 HTTP 请求头(类似 OpenAI Python SDK 的 extra_headers)
customHeaders?: CustomHeaderItem[]
- /** LKEAP Rerank:腾讯云 SecretKey(创建时写入 app_secret) */
+ /** 第二段密钥(厂商 secret 额外字段,如 LKEAP / 火山引擎 Rerank 的 SecretKey);创建时写入 app_secret */
appSecret?: string
- /** LKEAP Rerank:地域,如 ap-guangzhou */
- lkeapRegion?: string
}
+/** Protocols the backend accepts in extra_config.api (internal/models/api.API). */
+const PROTOCOL_OPTIONS = [
+ 'openai-completions',
+ 'openai-responses',
+ 'anthropic-messages',
+ 'google-generative-ai',
+] as const
+
+/** Legacy thinking_control values still honoured by catalog.Resolve. */
+const LEGACY_THINKING_CONTROL_VALUES = ['none', 'enable_thinking', 'thinking_type', 'chat_template_kwargs'] as const
+
+/** Keys of extra_config that are edited by dedicated controls, not the generic renderer. */
+const RESERVED_EXTRA_CONFIG_KEYS = new Set(['thinking_control'])
+
type EditorModelType = 'chat' | 'embedding' | 'rerank' | 'vllm' | 'asr'
interface Props {
@@ -477,8 +701,9 @@ interface Props {
saveModel: (data: ModelFormData & { modelType?: EditorModelType }) => Promise<void>
}
-const { t, te } = useI18n()
+const { t, locale } = useI18n()
const uiStore = useUIStore()
+const providersStore = useModelProvidersStore()
const props = withDefaults(defineProps<Props>(), {
visible: false,
@@ -505,242 +730,340 @@ const modelTypeChoices = computed(() => ([
{ value: 'asr' as const, label: t('modelSettings.typeShort.asr'), icon: 'sound' },
]))
-// API 返回的 Provider 列表
-const apiProviderOptions = ref<ModelProviderOption[]>([])
-const loadingProviders = ref(false)
-
-// 硬编码的后备 Provider 配置 (当 API 不可用时使用)
-const fallbackProviderOptions = computed(() => [
- {
- value: 'openai',
- label: t('model.editor.providers.openai.label'),
- defaultUrls: {
- chat: 'https://api.openai.com/v1',
- embedding: 'https://api.openai.com/v1',
- rerank: 'https://api.openai.com/v1',
- vllm: 'https://api.openai.com/v1',
- asr: 'https://api.openai.com/v1'
- },
- description: t('model.editor.providers.openai.description'),
- modelTypes: ['chat', 'embedding', 'vllm', 'asr']
- },
- {
- value: 'azure_openai',
- label: t('model.editor.providers.azure_openai.label'),
- defaultUrls: {
- chat: 'https://{resource}.openai.azure.com',
- embedding: 'https://{resource}.openai.azure.com',
- vllm: 'https://{resource}.openai.azure.com',
- asr: 'https://{resource}.openai.azure.com'
- },
- description: t('model.editor.providers.azure_openai.description'),
- modelTypes: ['chat', 'embedding', 'vllm', 'asr']
- },
- {
- value: 'aliyun',
- label: t('model.editor.providers.aliyun.label'),
- defaultUrls: {
- chat: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
- embedding: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
- rerank: 'https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank',
- vllm: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
- },
- description: t('model.editor.providers.aliyun.description'),
- modelTypes: ['chat', 'embedding', 'rerank', 'vllm']
- },
- {
- value: 'zhipu',
- label: t('model.editor.providers.zhipu.label'),
- defaultUrls: {
- chat: 'https://open.bigmodel.cn/api/paas/v4',
- embedding: 'https://open.bigmodel.cn/api/paas/v4/embeddings',
- vllm: 'https://open.bigmodel.cn/api/paas/v4'
- },
- description: t('model.editor.providers.zhipu.description'),
- modelTypes: ['chat', 'embedding', 'vllm']
- },
- {
- value: 'openrouter',
- label: t('model.editor.providers.openrouter.label'),
- defaultUrls: {
- chat: 'https://openrouter.ai/api/v1',
- embedding: 'https://openrouter.ai/api/v1'
- },
- description: t('model.editor.providers.openrouter.description'),
- modelTypes: ['chat', 'embedding']
- },
- {
- value: 'litellm',
- label: t('model.editor.providers.litellm.label'),
- defaultUrls: {
- chat: 'http://your_litellm_proxy/v1',
- embedding: 'http://your_litellm_proxy/v1',
- vllm: 'http://your_litellm_proxy/v1'
- },
- description: t('model.editor.providers.litellm.description'),
- modelTypes: ['chat', 'embedding', 'vllm']
- },
- {
- value: 'requesty',
- label: t('model.editor.providers.requesty.label'),
- defaultUrls: {
- chat: 'https://router.requesty.ai/v1',
- embedding: 'https://router.requesty.ai/v1'
- },
- description: t('model.editor.providers.requesty.description'),
- modelTypes: ['chat', 'embedding']
- },
- {
- value: 'gemini',
- label: t('model.editor.providers.gemini.label'),
- defaultUrls: {
- chat: 'https://generativelanguage.googleapis.com/v1beta/openai',
- embedding: 'https://generativelanguage.googleapis.com/v1beta'
- },
- description: t('model.editor.providers.gemini.description'),
- modelTypes: ['chat', 'embedding']
- },
- {
- value: 'siliconflow',
- label: t('model.editor.providers.siliconflow.label'),
- defaultUrls: {
- chat: 'https://api.siliconflow.cn/v1',
- embedding: 'https://api.siliconflow.cn/v1',
- rerank: 'https://api.siliconflow.cn/v1'
- },
- description: t('model.editor.providers.siliconflow.description'),
- modelTypes: ['chat', 'embedding', 'rerank']
- },
- {
- value: 'jina',
- label: t('model.editor.providers.jina.label'),
- defaultUrls: {
- embedding: 'https://api.jina.ai/v1',
- rerank: 'https://api.jina.ai/v1'
- },
- description: t('model.editor.providers.jina.description'),
- modelTypes: ['embedding', 'rerank']
- },
- {
- value: 'nvidia',
- label: t('model.editor.providers.nvidia.label'),
- defaultUrls: {
- chat: 'https://integrate.api.nvidia.com/v1',
- embedding: 'https://integrate.api.nvidia.com/v1',
- rerank: 'https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking',
- vllm: 'https://integrate.api.nvidia.com/v1',
- },
- description: t('model.editor.providers.nvidia.description'),
- modelTypes: ['chat', 'embedding', 'rerank', 'vllm']
- },
- {
- value: 'novita',
- label: t('model.editor.providers.novita.label'),
- defaultUrls: {
- chat: 'https://api.novita.ai/openai/v1',
- embedding: 'https://api.novita.ai/openai/v1',
- vllm: 'https://api.novita.ai/openai/v1',
- },
- description: t('model.editor.providers.novita.description'),
- modelTypes: ['chat', 'embedding', 'vllm']
- },
- {
- value: 'generic',
- label: t('model.editor.providers.generic.label'),
- defaultUrls: {},
- description: t('model.editor.providers.generic.description'),
- modelTypes: ['chat', 'embedding', 'rerank', 'vllm', 'asr']
- },
-])
+// 厂商列表完全来自后端目录(store 按模型类型缓存);前端不再维护任何厂商表。
+const loadingProviders = computed(() => providersStore.isLoading(activeModelType.value))
-// 从 API 获取 Provider 列表
const loadProviders = async () => {
- loadingProviders.value = true
try {
- const providers = await listModelProviders(activeModelType.value)
- if (providers.length > 0) {
- apiProviderOptions.value = providers
- }
+ await providersStore.ensureLoaded(activeModelType.value)
} catch (error) {
- console.error('Failed to load providers from API, using fallback', error)
- } finally {
- loadingProviders.value = false
- }
-}
-
-// 根据当前模型类型过滤的 Provider 列表
-// API 返回的 defaultUrls/modelTypes 数据优先,但 label/description 使用 i18n
-const providerOptions = computed(() => {
- // API 数据可用时,用 API 的结构数据 + i18n 的显示文本
- if (apiProviderOptions.value.length > 0) {
- return apiProviderOptions.value.map(p => ({
- ...p,
- label: te(`model.editor.providers.${p.value}.label`)
- ? t(`model.editor.providers.${p.value}.label`)
- : p.label,
- description: te(`model.editor.providers.${p.value}.description`)
- ? t(`model.editor.providers.${p.value}.description`)
- : p.description,
- }))
- }
- // 回退到硬编码值,按 modelTypes 过滤
- return fallbackProviderOptions.value.filter(p =>
- p.modelTypes.includes(activeModelType.value)
- )
+ console.error('Failed to load providers from API', error)
+ }
+}
+
+const providerOptions = computed<ModelProviderOption[]>(() => providersStore.providersFor(activeModelType.value))
+
+const selectedProvider = computed<ModelProviderOption | undefined>(() => {
+ const id = formData.value.provider
+ if (!id) return undefined
+ return providerOptions.value.find(p => p.value === id) || providersStore.providerById(id)
})
-const dialogVisible = computed({
- get: () => props.visible,
- set: (val) => {
- if (!saving.value) emit('update:visible', val)
- }
+const currentLocale = computed(() => String(locale.value || ''))
+const providerDisplayLabel = (p: ModelProviderOption) => providerLabel(p, currentLocale.value)
+const providerDisplayDescription = (p: ModelProviderOption) => providerDescription(p, currentLocale.value)
+const selectedProviderIcon = computed(() => providerIcon(selectedProvider.value))
+/** Localized vendor name, or the raw stored id when the catalog no longer has it. */
+const selectedProviderDisplayLabel = computed(() => (
+ selectedProvider.value
+ ? providerDisplayLabel(selectedProvider.value)
+ : (formData.value.provider || '')
+))
+/**
+ * Pin a select's dropdown to the width of its input.
+ *
+ * TDesign sizes a select popup as max(popup content, trigger)
+ * (select-input/hooks/useOverlayInnerStyle), so one long option — a vendor
+ * whose description lists half a dozen model ids — stretches the whole menu
+ * past the field it belongs to, leaving a wide band of empty space and
+ * pushing the tick mark far from the text. Passing a function here replaces
+ * that matching outright (the hook keeps a function as-is), and the option
+ * rows already ellipsize, so the long ones simply truncate.
+ */
+const matchTriggerWidth = (triggerElement: HTMLElement) => ({
+ width: `${triggerElement.offsetWidth}px`,
+})
+
+const extraFieldDisplayLabel = (field: ModelProviderExtraField) => extraFieldLabel(field, currentLocale.value)
+
+/**
+ * Vendors whose API is not a bearer-token API name their first credential
+ * themselves (LKEAP rerank takes a SecretId, Volcengine rerank an Access Key
+ * ID). Falling back to the generic "API Key" wording is what led operators to
+ * paste an `sk-` token into a signature field.
+ */
+const credentialLabel = computed(() =>
+ credentialLabelForModelType(selectedProvider.value?.credentialLabels, activeModelType.value),
+)
+const apiKeyLabel = computed(() => {
+ const label = credentialLabel.value
+ return label ? pickLocalized(label.labels, currentLocale.value, label.label) : t('model.editor.apiKeyOptional')
+})
+const apiKeyRequired = computed(
+ () => credentialLabel.value?.required === true || (!!selectedProvider.value?.requiresAuth && !isEdit.value),
+)
+const apiKeyHint = computed(() => {
+ const label = credentialLabel.value
+ if (!label?.hint) return ''
+ return pickLocalized(label.hints, currentLocale.value, label.hint)
})
-const showThinkingControlField = computed(() =>
- activeModelType.value === 'chat' && formData.value.source === 'remote',
+// 厂商额外字段:按当前模型类型过滤;secret 字段走 app_secret 凭证,其余进 extra_config。
+const visibleExtraFields = computed<ModelProviderExtraField[]>(() =>
+ extraFieldsForModelType(selectedProvider.value?.extraFields, activeModelType.value)
+ .filter(field => !RESERVED_EXTRA_CONFIG_KEYS.has(field.key)),
+)
+/**
+ * A credential-bearing vendor field. `secret` is the backend's own marker;
+ * `type: 'password'` is treated the same way so a vendor that forgets the flag
+ * still cannot get its value echoed back from GET /models into extra_config.
+ */
+const isSecretExtraField = (field: ModelProviderExtraField) => field.secret === true || field.type === 'password'
+// Only one credential slot (app_secret) exists per model, so the first such
+// field wins; vendors today declare at most one (LKEAP / Volcengine rerank).
+const secretExtraField = computed<ModelProviderExtraField | undefined>(() =>
+ visibleExtraFields.value.find(isSecretExtraField),
+)
+const plainExtraFields = computed<ModelProviderExtraField[]>(() =>
+ visibleExtraFields.value.filter(field => !isSecretExtraField(field)),
)
-const resolvedThinkingControl = (): ThinkingControlValue =>
- defaultThinkingControl(
- formData.value.provider || '',
- formData.value.modelName || '',
- )
+/** extra_config keys that belong to the connection, not to the vendor. */
+const VENDOR_NEUTRAL_EXTRA_CONFIG_KEYS = ['api', 'remote_model_name'] as const
-/** 用户是否手动改过思考参数格式(改过则不再自动覆盖,直到换服务商) */
-const thinkingControlManual = ref(false)
-/** 正在从 modelData 灌入表单,忽略厂商/来源控件的程序化 change 副作用 */
-const hydratingForm = ref(false)
+/** What survives a vendor (or model-type) switch: everything else is vendor-specific. */
+const keepVendorNeutralExtraConfig = (): Record<string, string> => {
+ const keep: Record<string, string> = {}
+ for (const key of VENDOR_NEUTRAL_EXTRA_CONFIG_KEYS) {
+ const value = formData.value.extraConfig?.[key]
+ if (value) keep[key] = value
+ }
+ return keep
+}
-const onThinkingControlManualPick = () => {
- thinkingControlManual.value = true
+const setExtraConfig = (key: string, value: string | null | undefined) => {
+ const next = { ...(formData.value.extraConfig || {}) }
+ const normalized = value == null ? '' : String(value)
+ if (normalized === '') delete next[key]
+ else next[key] = normalized
+ formData.value.extraConfig = next
}
-const syncThinkingControlToForm = (force = false) => {
- if (!showThinkingControlField.value) return
- if (!force && !isEdit.value && thinkingControlManual.value) return
- formData.value.thinkingControl = resolvedThinkingControl()
+const extraConfigBool = (key: string) => {
+ const raw = (formData.value.extraConfig?.[key] || '').trim().toLowerCase()
+ return raw === 'true' || raw === '1' || raw === 'yes'
}
-const applyThinkingControlFromModelData = () => {
- if (!props.modelData || activeModelType.value !== 'chat' || formData.value.source !== 'remote') return
- thinkingControlManual.value = !!props.modelData.thinkingControl
- formData.value.thinkingControl = resolveThinkingControl(
- props.modelData.thinkingControl,
- formData.value.provider || props.modelData.provider || '',
- formData.value.modelName || props.modelData.modelName || '',
- )
+/** Pre-fill vendor defaults for fields the user has not touched. */
+const applyExtraFieldDefaults = () => {
+ for (const field of plainExtraFields.value) {
+ if (!field.default) continue
+ if ((formData.value.extraConfig?.[field.key] ?? '') === '') {
+ setExtraConfig(field.key, field.default)
+ }
+ }
}
-const thinkingControlOptions = computed(() => {
- const keys = ['none', 'chatTemplateKwargs', 'enableThinking', 'thinkingType'] as const
- const values = ['none', 'chat_template_kwargs', 'enable_thinking', 'thinking_type'] as const
- return keys.map((key, i) => ({
- value: values[i],
- label: t(`model.editor.thinkingControl.${key}.label`),
- hint: t(`model.editor.thinkingControl.${key}.hint`),
+// 内置模型目录 → 模型名下拉候选(可自由输入)
+interface CatalogModelOption {
+ value: string
+ label: string
+ contextWindow: string
+ dimension?: number
+ reasoning: boolean
+ vision: boolean
+ entry?: ModelCatalogEntry
+}
+
+const catalogEntries = computed<ModelCatalogEntry[]>(() => {
+ // The list is already scoped: providers are fetched per model type, so the
+ // backend returned exactly the entries that type can use. Filtering again
+ // here on entry.type was wrong for 视觉 — a VLM entry is a chat model that
+ // accepts images, so it arrives typed "chat" and every one of them was
+ // dropped, leaving the picker empty for every vendor.
+ return selectedProvider.value?.models || []
+})
+
+const catalogModelOptions = computed<CatalogModelOption[]>(() => {
+ const options: CatalogModelOption[] = catalogEntries.value.map(entry => ({
+ value: entry.id,
+ label: entry.name || entry.id,
+ contextWindow: entry.context_window ? formatTokenCount(entry.context_window) : '',
+ dimension: entry.dimension || undefined,
+ reasoning: !!entry.reasoning || (entry.thinking_levels?.length ?? 0) > 0,
+ vision: Array.isArray(entry.input) && entry.input.includes('image'),
+ entry,
}))
+ const current = (formData.value.modelName || '').trim()
+ if (current && !options.some(o => o.value === current)) {
+ options.unshift({ value: current, label: current, contextWindow: '', reasoning: false, vision: false })
+ }
+ return options
+})
+
+const findCatalogEntry = (name: string) => catalogEntries.value.find(m => m.id === name)
+
+/**
+ * Where to read about what is configured right now.
+ *
+ * Prefer the page the selected model's facts were taken from — that is the
+ * page listing its context window, thinking levels and price — and fall back
+ * to the vendor's own site when the model is not in the catalog. Both come
+ * from the catalog, so a new vendor gets the link without a UI change.
+ */
+const vendorDocLink = computed(() => {
+ const provider = selectedProvider.value
+ if (!provider) return ''
+ const entry = findCatalogEntry((formData.value.modelName || '').trim())
+ const url = entry?.source || provider.website || ''
+ return /^https?:\/\//i.test(url) ? url : ''
})
+/**
+ * What applyCatalogEntry filled in for the model currently selected.
+ *
+ * Switching vendor has to take those values back — a context window from the
+ * previous vendor's model is exactly the "填大会导致压缩不触发、上游直接拒绝"
+ * case this field warns about — but it must not touch a number the operator
+ * typed. Remembering what was filled, and only clearing a field that still
+ * holds it, separates the two.
+ */
+const catalogFilled = ref<Partial<ModelFormData>>({})
+
+/** Fill blank capability fields from a catalog entry the user just picked. */
+const applyCatalogEntry = (entry: ModelCatalogEntry) => {
+ if (activeModelType.value === 'chat' || activeModelType.value === 'vllm') {
+ if (!formData.value.contextWindow && entry.context_window) {
+ formData.value.contextWindow = entry.context_window
+ catalogFilled.value.contextWindow = entry.context_window
+ }
+ if (!formData.value.maxOutputTokens && entry.max_output_tokens) {
+ formData.value.maxOutputTokens = entry.max_output_tokens
+ catalogFilled.value.maxOutputTokens = entry.max_output_tokens
+ }
+ }
+ if (activeModelType.value === 'chat' && !formData.value.supportsVision && Array.isArray(entry.input) && entry.input.includes('image')) {
+ formData.value.supportsVision = true
+ catalogFilled.value.supportsVision = true
+ }
+ if (activeModelType.value === 'embedding' && !formData.value.dimension && entry.dimension) {
+ formData.value.dimension = entry.dimension
+ catalogFilled.value.dimension = entry.dimension
+ }
+}
+
+const handleCatalogModelCreate = (value: string | number | boolean | bigint) => {
+ formData.value.modelName = String(value ?? '').trim()
+}
+
+const handleCatalogModelChange = (value: unknown) => {
+ const name = typeof value === 'string' ? value.trim() : ''
+ if (!name) return
+ const entry = findCatalogEntry(name)
+ if (entry) applyCatalogEntry(entry)
+}
+
+// 接入诊断(只读):厂商 / 模型名 / Base URL / 协议覆盖变化后 400ms 防抖调用目录解析
+const resolved = ref<ResolvedModelCatalog | null>(null)
+const resolving = ref(false)
+const resolveFailed = ref(false)
+/** Human-readable detail of the last failure; '' when the error carried none. */
+const resolveError = ref('')
+let resolveTimer: ReturnType<typeof setTimeout> | null = null
+let resolveRevision = 0
+
+/** 目录解析出的协议 / 思考等级 / 上下文窗口只对对话与 VLM 模型有意义。 */
+const isChatLike = computed(() => activeModelType.value === 'chat' || activeModelType.value === 'vllm')
+
+const showResolvedPanel = computed(() =>
+ isChatLike.value
+ && formData.value.source === 'remote'
+ && !!formData.value.provider
+ && formData.value.provider !== 'weknoracloud',
+)
+
+const resolvedThinkingLevels = computed(() => supportedLevels(resolved.value?.capabilities))
+
+const runResolve = async () => {
+ const revision = ++resolveRevision
+ const provider = (formData.value.provider || '').trim()
+ // Embedding / ReRank / ASR never render the panel, so do not spend a
+ // request (and do not leave a stale chat result behind) for them.
+ if (!props.visible || !showResolvedPanel.value || !provider) {
+ resolved.value = null
+ resolving.value = false
+ resolveFailed.value = false
+ resolveError.value = ''
+ return
+ }
+ resolving.value = true
+ try {
+ const result = await resolveModelCatalog({
+ provider,
+ model: formData.value.modelName || '',
+ base_url: formData.value.baseUrl || '',
+ model_type: activeModelType.value,
+ api: formData.value.extraConfig?.api || '',
+ thinking_control: formData.value.thinkingControl || '',
+ remote_model_name: formData.value.extraConfig?.remote_model_name || '',
+ // Vendor fields decide the request too — Azure's api_version picks
+ // between the v1 data plane and the dated deployments path — so the
+ // preview has to see them or it describes a different request than
+ // the one this row will make. Secret fields never travel in a query
+ // string; plainExtraFields already excludes them.
+ ...Object.fromEntries(
+ plainExtraFields.value
+ .map(field => [field.key, formData.value.extraConfig?.[field.key] || ''])
+ .filter(([, value]) => !!value),
+ ),
+ })
+ if (revision !== resolveRevision) return
+ resolved.value = result
+ resolveFailed.value = false
+ resolveError.value = ''
+ } catch (error: any) {
+ if (revision !== resolveRevision) return
+ resolved.value = null
+ resolveFailed.value = true
+ const detail = typeof error === 'string'
+ ? error
+ : (error?.message || error?.error?.message || error?.error)
+ resolveError.value = typeof detail === 'string' ? detail.trim() : ''
+ } finally {
+ if (revision === resolveRevision) resolving.value = false
+ }
+}
+
+const scheduleResolve = () => {
+ if (resolveTimer) clearTimeout(resolveTimer)
+ resolveTimer = setTimeout(() => {
+ resolveTimer = null
+ void runResolve()
+ }, 400)
+}
+
+// 高级折叠区
+const advancedOpen = ref(false)
+/** Set when the loaded row carried thinking_control, so the select stays visible after clearing it. */
+const legacyThinkingControlLoaded = ref(false)
+const showLegacyThinkingControl = computed(() =>
+ activeModelType.value === 'chat' && !!(formData.value.thinkingControl || legacyThinkingControlLoaded.value),
+)
+
+const specCompatError = computed(() => {
+ const text = (formData.value.specCompat || '').trim()
+ if (!text) return ''
+ try {
+ const parsed = JSON.parse(text)
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+ return t('model.editor.advanced.compat.mustBeObject')
+ }
+ return ''
+ } catch (error: any) {
+ return error?.message || 'invalid JSON'
+ }
+})
+
+const dialogVisible = computed({
+ get: () => props.visible,
+ set: (val) => {
+ if (!saving.value) emit('update:visible', val)
+ }
+})
+
+/** 正在从 modelData 灌入表单,忽略厂商/来源控件的程序化 change 副作用 */
+const hydratingForm = ref(false)
+
// Header icon for the SettingDrawer — uses the same TDesign icon name table
// as the model card list, so the drawer's leading badge visually matches the
// card the user just clicked on.
@@ -755,55 +1078,17 @@ const modelTypeIcon = computed(() => {
return map[activeModelType.value] || 'setting'
})
-const isLkeapRerank = computed(
- () => activeModelType.value === 'rerank' && formData.value.provider === 'lkeap',
-)
-const isVolcengineRerank = computed(
- () => activeModelType.value === 'rerank' && formData.value.provider === 'volcengine',
-)
-const isSignedRerank = computed(
- () => isLkeapRerank.value || isVolcengineRerank.value,
-)
-const signedRerankAccessKeyLabel = computed(() => (
- isVolcengineRerank.value
- ? t('model.editor.volcengine.accessKeyLabel')
- : t('model.editor.lkeap.secretIdLabel')
-))
-const signedRerankAccessKeyPlaceholder = computed(() => (
- isVolcengineRerank.value
- ? t('model.editor.volcengine.accessKeyPlaceholder')
- : t('model.editor.lkeap.secretIdPlaceholder')
-))
-const signedRerankSecretKeyLabel = computed(() => (
- isVolcengineRerank.value
- ? t('model.editor.volcengine.secretKeyLabel')
- : t('model.editor.lkeap.secretKeyLabel')
-))
-const signedRerankSecretKeyPlaceholder = computed(() => (
- isVolcengineRerank.value
- ? t('model.editor.volcengine.secretKeyPlaceholder')
- : t('model.editor.lkeap.secretKeyPlaceholder')
-))
-const signedRerankCredentialHint = computed(() => (
- isVolcengineRerank.value
- ? t('model.editor.volcengine.rerankCredentialHint')
- : t('model.editor.lkeap.rerankCredentialHint')
-))
-
// Credential resource binding for the shared <CredentialResource> component.
+// A vendor-declared secret extra field (LKEAP / Volcengine rerank SecretKey)
+// is stored as the app_secret credential, so it shows up here in edit mode.
const credentialFields = computed<CredentialFieldDef<ModelCredentialField>[]>(() => {
const fields: CredentialFieldDef<ModelCredentialField>[] = [
- {
- key: 'api_key',
- label: (isSignedRerank.value
- ? signedRerankAccessKeyLabel.value
- : t('model.editor.apiKeyOptional')) as string,
- },
+ { key: 'api_key', label: t('model.editor.apiKeyOptional') as string },
]
if (formData.value.provider === 'weknoracloud') {
fields.push({ key: 'app_secret', label: 'App Secret' })
- } else if (isSignedRerank.value) {
- fields.push({ key: 'app_secret', label: signedRerankSecretKeyLabel.value as string })
+ } else if (secretExtraField.value) {
+ fields.push({ key: 'app_secret', label: extraFieldDisplayLabel(secretExtraField.value) })
}
return fields
})
@@ -831,7 +1116,11 @@ const credentialMeta = computed(() => (props.modelData as any)?.credentials ?? {
// Placeholder hint for the create-mode API key input. Edit mode replaces
// this input entirely with a <CredentialResource> card.
-const apiKeyPlaceholder = computed(() => t('model.editor.apiKeyPlaceholder'))
+const apiKeyPlaceholder = computed(() => {
+ const label = credentialLabel.value
+ if (label?.placeholder) return pickLocalized(label.placeholders, currentLocale.value, label.placeholder)
+ return t('model.editor.apiKeyPlaceholder')
+})
const formRef = ref()
const saving = ref(false)
@@ -946,10 +1235,13 @@ const formData = ref<ModelFormData>({
supportsVision: false,
contextWindow: undefined,
maxConcurrency: undefined,
- thinkingControl: defaultThinkingControl('generic', ''),
+ maxOutputTokens: undefined,
+ thinkingControl: '',
+ extraConfig: {},
+ specCompat: '',
+ spec: null,
customHeaders: [],
appSecret: '',
- lkeapRegion: 'ap-guangzhou',
})
const rules = computed(() => ({
@@ -992,6 +1284,19 @@ const rules = computed(() => ({
]
}))
+// 接入诊断的触发源:可见性 / 来源 / 厂商 / 模型名 / Base URL / 高级覆盖 / 模型类型
+watch(
+ () => [
+ props.visible, formData.value.source, formData.value.provider, formData.value.modelName,
+ formData.value.baseUrl, formData.value.extraConfig?.api, formData.value.extraConfig?.remote_model_name,
+ formData.value.thinkingControl, activeModelType.value,
+ ],
+ () => {
+ if (!props.visible) return
+ scheduleResolve()
+ },
+)
+
// 获取弹窗描述文字
const getModalDescription = () => {
const key = `model.editor.description.${activeModelType.value}` as const
@@ -1082,7 +1387,6 @@ const selectModelType = async (type: EditorModelType) => {
}
if (type !== 'chat') {
formData.value.supportsVision = false
- thinkingControlManual.value = false
}
remoteChecked.value = false
remoteAvailable.value = false
@@ -1093,13 +1397,13 @@ const selectModelType = async (type: EditorModelType) => {
if (!supported) {
formData.value.provider = 'generic'
formData.value.baseUrl = ''
+ // 只丢厂商相关的 extra_config;协议 / 远端模型名是用户对这次接入的选择,
+ // 与厂商无关,和 handleProviderChange 保持同一套规则。
+ formData.value.extraConfig = keepVendorNeutralExtraConfig()
+ formData.value.appSecret = ''
} else {
handleProviderChange(formData.value.provider || 'generic')
}
- if (showThinkingControlField.value && !isEdit.value) {
- thinkingControlManual.value = false
- syncThinkingControlToForm(true)
- }
}
// 监听 visible 变化,初始化表单
@@ -1108,8 +1412,11 @@ watch(() => props.visible, (val) => {
// 检查Ollama服务状态
checkOllamaServiceStatus()
- // 从 API 加载 Model Provider 列表
- loadProviders()
+ // 从 API 加载 Model Provider 列表(编辑已有行时顺便补齐额外字段默认值)
+ loadProviders().then(() => {
+ if (props.visible && !isEdit.value) applyExtraFieldDefaults()
+ })
+ advancedOpen.value = false
// 每次打开都清理上一次遗留的校验/检测结果,避免编辑别的模型时
// 直接显示上一次的“连接成功”
@@ -1131,14 +1438,26 @@ watch(() => props.visible, (val) => {
// 编辑:始终用最新的 modelData 覆盖。apiKey field is left blank — in
// edit mode the credential is owned by the <CredentialResource> card,
// not by this form's apiKey field.
+ const loadedExtra: Record<string, string> = {}
+ for (const [key, value] of Object.entries(props.modelData.extraConfig || {})) {
+ if (RESERVED_EXTRA_CONFIG_KEYS.has(key)) continue
+ if (value != null && String(value) !== '') loadedExtra[key] = String(value)
+ }
+ const loadedSpec = props.modelData.spec || null
formData.value = {
...props.modelData,
apiKey: '',
+ appSecret: '',
+ extraConfig: loadedExtra,
+ thinkingControl: props.modelData.thinkingControl || '',
+ spec: loadedSpec,
+ specCompat: props.modelData.specCompat
+ ?? (loadedSpec?.compat ? JSON.stringify(loadedSpec.compat, null, 2) : ''),
customHeaders: Array.isArray(props.modelData.customHeaders)
? props.modelData.customHeaders.map(h => ({ key: h.key, value: h.value }))
: [],
}
- applyThinkingControlFromModelData()
+ legacyThinkingControlLoaded.value = !!props.modelData.thinkingControl
} else if (lastOpenedModelId.value !== null || !formData.value.id) {
// 上次是编辑某个模型,或第一次新增 → 重置成空白
resetForm()
@@ -1156,11 +1475,6 @@ watch(() => props.visible, (val) => {
if (formData.value.provider === 'weknoracloud') {
checkWkcCredentialStatus()
}
-
- if (showThinkingControlField.value && !isEdit.value) {
- thinkingControlManual.value = false
- syncThinkingControlToForm(true)
- }
} finally {
nextTick(() => {
hydratingForm.value = false
@@ -1175,7 +1489,7 @@ watch(
formData.value.provider, formData.value.modelName, formData.value.baseUrl,
formData.value.apiKey, formData.value.appSecret, formData.value.customHeaders,
formData.value.dimension, formData.value.supportsDimensionOverride,
- formData.value.lkeapRegion, formData.value.thinkingControl,
+ formData.value.extraConfig, formData.value.thinkingControl,
],
() => {
if (!applyingDetectedDimension) invalidateConnectionTest(props.visible && !hydratingForm.value)
@@ -1190,7 +1504,7 @@ watch(() => props.visible, () => {
// 重置表单
const resetForm = () => {
- thinkingControlManual.value = false
+ legacyThinkingControlLoaded.value = false
formData.value = {
id: generateId(),
name: '', // 保留字段但不使用,保存时用 modelName
@@ -1207,11 +1521,17 @@ const resetForm = () => {
supportsVision: false,
contextWindow: undefined,
maxConcurrency: undefined,
- thinkingControl: defaultThinkingControl('generic', ''),
+ maxOutputTokens: undefined,
+ thinkingControl: '',
+ extraConfig: {},
+ specCompat: '',
+ spec: null,
customHeaders: [],
appSecret: '',
- lkeapRegion: 'ap-guangzhou',
}
+ resolved.value = null
+ resolveFailed.value = false
+ resolveError.value = ''
modelChecked.value = false
modelAvailable.value = false
remoteChecked.value = false
@@ -1223,66 +1543,70 @@ const resetForm = () => {
}
// 处理厂商选择变化 (自动填充默认 URL)
+/**
+ * Drop a model name the new vendor does not serve, along with whatever the
+ * catalog filled in for it.
+ *
+ * The same id does exist at several vendors — deepseek-v4-pro is sold by
+ * DeepSeek, Aliyun, Volcengine and the gateways — so switching between them
+ * should keep the selection. Anything else is a name from the previous
+ * vendor: left in place it is saved verbatim, resolves as an uncatalogued
+ * model and fails at the first call.
+ */
+const resetModelSelectionForVendor = () => {
+ const current = (formData.value.modelName || '').trim()
+ if (!current || findCatalogEntry(current)) return
+
+ formData.value.modelName = ''
+ // Take back only the values applyCatalogEntry put there; a number the
+ // operator typed is theirs and survives the switch.
+ const filled = catalogFilled.value
+ if (filled.contextWindow && formData.value.contextWindow === filled.contextWindow) {
+ formData.value.contextWindow = undefined
+ }
+ if (filled.maxOutputTokens && formData.value.maxOutputTokens === filled.maxOutputTokens) {
+ formData.value.maxOutputTokens = undefined
+ }
+ if (filled.dimension && formData.value.dimension === filled.dimension) {
+ formData.value.dimension = undefined
+ }
+ if (filled.supportsVision && formData.value.supportsVision) {
+ formData.value.supportsVision = false
+ }
+ catalogFilled.value = {}
+ modelChecked.value = false
+ modelAvailable.value = false
+ dimensionChecked.value = false
+ dimensionSuccess.value = false
+ dimensionMessage.value = ''
+}
+
const handleProviderChange = (value: string) => {
const provider = providerOptions.value.find(opt => opt.value === value)
- if (provider && provider.defaultUrls) {
+ if (provider?.defaultUrls) {
// 根据当前模型类型获取对应的默认 URL
const defaultUrl = provider.defaultUrls[activeModelType.value]
if (defaultUrl) {
formData.value.baseUrl = defaultUrl
}
- if (value === 'lkeap' && activeModelType.value === 'rerank' && !formData.value.modelName?.trim()) {
- formData.value.modelName = 'lke-reranker-base'
- }
- if (value === 'volcengine' && activeModelType.value === 'rerank' && !formData.value.modelName?.trim()) {
- formData.value.modelName = 'doubao-seed-rerank'
- }
- // 重置校验状态
- remoteChecked.value = false
- remoteAvailable.value = false
- remoteMessage.value = ''
}
+ // 重置校验状态:它描述的是上一家厂商的连通性,跟新厂商无关。放在 defaultUrls
+ // 判断之外,否则切到没有默认地址的厂商时会留着一条"连接正常"的旧结论。
+ remoteChecked.value = false
+ remoteAvailable.value = false
+ remoteMessage.value = ''
// WeKnoraCloud: 检查凭证状态
if (value === 'weknoracloud') {
checkWkcCredentialStatus()
}
if (hydratingForm.value) return
- if (activeModelType.value !== 'chat' || formData.value.source !== 'remote') return
- if (!isEdit.value) {
- thinkingControlManual.value = false
- syncThinkingControlToForm(true)
- return
- }
- // 编辑时仅用户主动换厂商才跟随默认
- thinkingControlManual.value = false
- syncThinkingControlToForm(true)
+ resetModelSelectionForVendor()
+ // 换厂商:丢掉上一家的厂商字段(保留协议 / 远端模型名等高级覆盖),再灌入新厂商默认值
+ formData.value.extraConfig = keepVendorNeutralExtraConfig()
+ formData.value.appSecret = ''
+ applyExtraFieldDefaults()
}
-watch(
- () => [formData.value.source, formData.value.provider, formData.value.modelName] as const,
- ([source, provider, modelName], [prevSource, prevProvider, prevModelName]) => {
- if (hydratingForm.value || isEdit.value) return
- if (activeModelType.value !== 'chat' || source !== 'remote') return
- if (source === prevSource && provider === prevProvider && modelName === prevModelName) return
-
- const providerChanged = provider !== prevProvider
-
- if (providerChanged) {
- thinkingControlManual.value = false
- syncThinkingControlToForm(true)
- return
- }
- if (!thinkingControlManual.value) {
- syncThinkingControlToForm(true)
- return
- }
- const prevDefault = defaultThinkingControl(prevProvider || '', prevModelName || '')
- if (formData.value.thinkingControl === prevDefault) {
- syncThinkingControlToForm(true)
- }
- },
-)
-
// 监听来源变化,重置校验状态(已合并到下面的 watch)
// 生成唯一ID
@@ -1430,6 +1754,20 @@ const checkOllamaDimension = async () => {
}
}
+/** extra_config exactly as it will be persisted: trimmed, empty values dropped. */
+const buildExtraConfig = (): Record<string, string> => {
+ const out: Record<string, string> = {}
+ for (const [key, value] of Object.entries(formData.value.extraConfig || {})) {
+ const trimmed = (value ?? '').toString().trim()
+ if (key && trimmed) out[key] = trimmed
+ }
+ const legacy = (formData.value.thinkingControl || '').trim()
+ if (legacy && activeModelType.value === 'chat' && formData.value.source === 'remote') {
+ out.thinking_control = legacy
+ }
+ return out
+}
+
// 检查 Remote API 连接(根据模型类型调用不同的接口)
const checkRemoteAPI = async () => {
if (checking.value || saving.value) return
@@ -1471,6 +1809,14 @@ const checkRemoteAPI = async () => {
? { modelId: props.modelData.id as string }
: {}
+ // extra_config 与真正保存时完全一致(厂商字段 + 高级覆盖 + 旧 thinking_control),
+ // 使测试连接走与生产调用相同的目录解析路径。
+ const extraConfig = buildExtraConfig()
+ const extraPayload = {
+ ...(Object.keys(extraConfig).length > 0 ? { extraConfig } : {}),
+ ...(formData.value.appSecret?.trim() ? { appSecret: formData.value.appSecret.trim() } : {}),
+ }
+
switch (activeModelType.value) {
case 'chat':
// 对话模型(KnowledgeQA)
@@ -1481,6 +1827,7 @@ const checkRemoteAPI = async () => {
provider: formData.value.provider,
...idPayload,
...headerPayload,
+ ...extraPayload,
})
break
@@ -1496,27 +1843,14 @@ const checkRemoteAPI = async () => {
provider: formData.value.provider,
...idPayload,
...headerPayload,
+ ...extraPayload,
})
// 如果测试成功且返回了维度,自动填充
if (revision !== connectionRevision) return
if (result.available && result.dimension) applyDetectedDimension(result.dimension)
break
- case 'rerank': {
- const signedRerankExtra = isSignedRerank.value
- ? {
- ...(isLkeapRerank.value
- ? {
- extraConfig: {
- region: (formData.value.lkeapRegion || 'ap-guangzhou').trim(),
- },
- }
- : {}),
- ...(formData.value.appSecret?.trim()
- ? { appSecret: formData.value.appSecret.trim() }
- : {}),
- }
- : {}
+ case 'rerank':
result = await checkRerankModel({
modelName: formData.value.modelName,
baseUrl: formData.value.baseUrl || '',
@@ -1524,10 +1858,9 @@ const checkRemoteAPI = async () => {
provider: formData.value.provider,
...idPayload,
...headerPayload,
- ...signedRerankExtra,
+ ...extraPayload,
})
break
- }
case 'vllm':
// VLLM 模型(多模态)
@@ -1539,6 +1872,7 @@ const checkRemoteAPI = async () => {
provider: formData.value.provider,
...idPayload,
...headerPayload,
+ ...extraPayload,
})
break
@@ -1551,6 +1885,7 @@ const checkRemoteAPI = async () => {
provider: formData.value.provider,
...idPayload,
...headerPayload,
+ ...extraPayload,
})
break
@@ -1609,6 +1944,25 @@ const handleConfirm = async () => {
}
}
+ if (formData.value.source === 'remote' && formData.value.provider !== 'weknoracloud') {
+ // 厂商声明的必填额外字段
+ for (const field of plainExtraFields.value) {
+ if (field.required && !(formData.value.extraConfig?.[field.key] || '').trim()) {
+ MessagePlugin.warning(t('model.editor.validation.extraFieldRequired', { name: extraFieldDisplayLabel(field) }))
+ return
+ }
+ }
+ if (!isEdit.value && secretExtraField.value?.required && !(formData.value.appSecret || '').trim()) {
+ MessagePlugin.warning(t('model.editor.validation.extraFieldRequired', { name: extraFieldDisplayLabel(secretExtraField.value) }))
+ return
+ }
+ if (specCompatError.value) {
+ advancedOpen.value = true
+ MessagePlugin.warning(`${t('model.editor.advanced.compat.invalid')}: ${specCompatError.value}`)
+ return
+ }
+ }
+
// 执行表单验证
const validation = await formRef.value?.validate()
if (validation !== undefined && validation !== true) return
@@ -1624,6 +1978,7 @@ const handleConfirm = async () => {
await props.saveModel({
...formData.value,
+ extraConfig: buildExtraConfig(),
...(isEdit.value ? {} : { modelType: activeModelType.value }),
})
emit('update:visible', false)
@@ -1730,6 +2085,11 @@ const startDownload = async (modelName: string) => {
onUnmounted(() => {
window.removeEventListener('keydown', handleSaveEscape, true)
invalidateConnectionTest(false)
+ if (resolveTimer) {
+ clearTimeout(resolveTimer)
+ resolveTimer = null
+ }
+ resolveRevision++
if (downloadInterval) {
clearInterval(downloadInterval)
}
@@ -1756,16 +2116,6 @@ watch(() => formData.value.source, () => {
downloading.value = false
downloadProgress.value = 0
currentDownloadModel.value = ''
-
- if (
- !hydratingForm.value
- && !isEdit.value
- && formData.value.source === 'remote'
- && activeModelType.value === 'chat'
- ) {
- thinkingControlManual.value = false
- syncThinkingControlToForm(true)
- }
})
// 监听模型名称变化,清理维度检测状态
@@ -1785,6 +2135,22 @@ const handleCancel = () => {
</script>
<style lang="less" scoped>
+.provider-doc-link {
+ margin-top: 6px;
+
+ a {
+ display: inline-flex;
+ align-items: center;
+ gap: 3px;
+ color: var(--td-text-color-link);
+ text-decoration: none;
+
+ &:hover {
+ text-decoration: underline;
+ }
+ }
+}
+
// 原生 t-form-item 容器置空(本组件使用自定义 .form-item + 手写 label)
:deep(.t-form) {
.t-form-item {
@@ -1819,16 +2185,22 @@ const handleCancel = () => {
}
}
-.model-type-options {
+.model-type-options,
+.source-options {
display: flex;
flex-wrap: wrap;
gap: 8px;
}
-.model-type-option {
+// 「模型类型」和「模型来源」都是单选,就用同一种按钮。模型来源原本是灰底轨道
+// 的 segmented:#e7e7e7 的轨道在浅色表单里是一整块深灰,白色药丸又浮不起来,
+// 而且紧挨着的模型类型是另一套长相。取消轨道后两组自然成为一族。
+.model-type-option,
+.source-option {
display: inline-flex;
align-items: center;
gap: 6px;
+ font-family: inherit;
padding: 6px 12px;
min-height: 32px;
border: 1px solid var(--td-component-stroke);
@@ -1854,9 +2226,12 @@ const handleCancel = () => {
color: var(--td-text-color-primary);
}
+ // 选中态与下面的「模型来源」分段一致:白底 + 主题色描边 + 主题色文字。
+ // 原先还铺了一层 10% 的主题色底,五个按钮里那一块是整屏最重的色块,而且
+ // 和下拉里刚去掉的整行绿底是同一个毛病。
&.is-active {
border-color: var(--td-brand-color);
- background: color-mix(in srgb, var(--td-brand-color) 10%, transparent);
+ background: var(--td-bg-color-container);
color: var(--td-brand-color);
font-weight: 500;
}
@@ -1867,62 +2242,16 @@ const handleCancel = () => {
}
}
-// 模型来源分段:紧凑单行 pill 形 segmented。容器自身是浅底圆角条,
-// 选中按钮通过实色背景 + 主题色描边浮出,未选中态接近透明,节省纵向空间。
-.source-options {
- display: inline-flex;
- align-items: center;
- gap: 4px;
- padding: 3px;
- background: var(--td-bg-color-component);
- border: 1px solid var(--td-component-stroke);
- border-radius: var(--app-radius-md);
-}
-
-.source-option {
- display: inline-flex;
- align-items: center;
- gap: 6px;
- padding: 5px 12px;
- height: 28px;
- background: transparent;
- border: 1px solid transparent;
- border-radius: var(--app-radius-sm);
- cursor: pointer;
- font-family: inherit;
- font-size: var(--app-text-md);
- color: var(--td-text-color-secondary);
- line-height: 1;
- transition: all var(--app-motion-fast) ease;
- &:hover:not(.is-disabled):not(.is-active) {
- color: var(--td-text-color-primary);
- background: var(--td-bg-color-container-hover);
- }
-
- &.is-active {
- background: var(--td-bg-color-container);
- border-color: var(--td-brand-color);
- color: var(--td-brand-color);
- font-weight: 500;
- box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04);
- }
+.source-option {
+ // 外观来自上面那条共用规则;这里只补禁用态(Ollama 未就绪 / rerank 不支持)。
&.is-disabled {
cursor: not-allowed;
opacity: 0.45;
}
}
-.source-option__icon {
- font-size: var(--app-text-base);
- flex-shrink: 0;
-}
-
-.source-option__label {
- white-space: nowrap;
-}
-
// 输入框样式:只在最外层 .t-input 上调字号,避免在内部 wrap/inner 上重复加边
// 与 border-radius,造成视觉上"嵌套圆角容器"的错觉
:deep(.t-input),
@@ -2306,6 +2635,169 @@ const handleCancel = () => {
&--warn {
color: var(--td-warning-color);
}
+
+ &--error {
+ color: var(--td-error-color);
+ }
+}
+
+// 已选厂商:图标 + 名称,嵌在 t-select 的 valueDisplay 里
+.provider-value {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+ min-width: 0;
+ max-width: 100%;
+
+ &__name {
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+}
+
+.provider-icon {
+ width: 18px;
+ height: 18px;
+ flex-shrink: 0;
+ border-radius: 4px;
+ object-fit: contain;
+
+ &--placeholder {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ font-size: var(--app-text-xs);
+ font-weight: 600;
+ color: var(--td-text-color-secondary);
+ background: var(--td-bg-color-secondarycontainer);
+ }
+}
+
+// 目录内 / 推理 / 视觉 等弱化徽标(与卡片上的 chip 同调)
+.catalog-badge {
+ display: inline-flex;
+ align-items: center;
+ padding: 0 6px;
+ height: 18px;
+ border-radius: 4px;
+ background: var(--td-bg-color-secondarycontainer);
+ color: var(--td-text-color-secondary);
+ font-size: var(--app-text-xs);
+ line-height: 18px;
+ white-space: nowrap;
+
+ & + & {
+ margin-left: 4px;
+ }
+
+ &--accent {
+ background: var(--td-brand-color-light);
+ color: var(--td-brand-color);
+ }
+}
+
+// 接入诊断面板:只读、浅底,避免与可编辑字段混淆
+.resolved-panel {
+ padding: 10px 12px;
+ border: 1px dashed var(--td-component-stroke);
+ border-radius: 8px;
+ background: var(--td-bg-color-container-hover);
+
+ &__header {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ margin-bottom: 6px;
+ }
+
+ &__icon {
+ font-size: var(--app-text-base);
+ color: var(--td-text-color-secondary);
+ }
+
+ &__title {
+ font-size: var(--app-text-sm);
+ font-weight: 500;
+ color: var(--td-text-color-secondary);
+ }
+
+ &__loading {
+ font-size: var(--app-text-md);
+ color: var(--td-text-color-placeholder);
+ animation: spin 1s linear infinite;
+ }
+
+ &__grid {
+ display: grid;
+ grid-template-columns: max-content minmax(0, 1fr);
+ column-gap: 12px;
+ row-gap: 4px;
+ margin: 0;
+ font-size: var(--app-text-sm);
+
+ dt {
+ color: var(--td-text-color-placeholder);
+ white-space: nowrap;
+ line-height: 18px;
+ }
+
+ dd {
+ margin: 0;
+ min-width: 0;
+ color: var(--td-text-color-primary);
+ line-height: 18px;
+ overflow-wrap: anywhere;
+ }
+
+ code {
+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+ font-size: var(--app-text-sm);
+ }
+ }
+}
+
+// 高级折叠:与知识库分块设置里的 advanced-toggle 保持同一视觉
+.advanced-toggle {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+ padding: 4px 0;
+ margin: 0;
+ background: transparent;
+ border: none;
+ cursor: pointer;
+ font-family: inherit;
+ font-size: var(--app-text-md);
+ font-weight: 500;
+ color: var(--td-text-color-secondary);
+ user-select: none;
+
+ &:hover {
+ color: var(--td-text-color-primary);
+ }
+
+ &:focus-visible {
+ outline: 2px solid var(--td-brand-color-focus);
+ outline-offset: 2px;
+ border-radius: 4px;
+ }
+
+ .toggle-arrow {
+ font-size: var(--app-text-base);
+ transition: transform 0.15s ease;
+
+ &.open {
+ transform: rotate(90deg);
+ }
+ }
+}
+
+.compat-textarea {
+ :deep(textarea) {
+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+ font-size: var(--app-text-sm);
+ }
}
.vision-toggle {
@@ -2404,9 +2896,7 @@ const handleCancel = () => {
<!-- 非 scoped 样式:t-select popup 渲染到 body 下,scoped 样式无法覆盖 -->
<style lang="less">
-.thinking-control-select-popup {
- min-width: 22rem;
- max-width: min(28rem, calc(100vw - 2rem));
+.catalog-model-select-popup {
padding: 4px;
.t-select-option {
@@ -2414,26 +2904,56 @@ const handleCancel = () => {
padding: 8px 10px;
border-radius: var(--app-radius-sm);
margin: 2px 0;
- white-space: normal;
}
}
-.thinking-control-option {
+.catalog-model-option {
display: flex;
- flex-direction: column;
- gap: 2px;
- line-height: 1.35;
+ align-items: center;
+ gap: 8px;
min-width: 0;
+ width: 100%;
- &__title {
+ &__name {
font-size: var(--app-text-md);
color: var(--td-text-color-primary);
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
}
- &__hint {
- font-size: var(--app-text-sm);
+ &__id {
+ font-size: var(--app-text-xs);
color: var(--td-text-color-placeholder);
- word-break: break-word;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ &__badges {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ margin-left: auto;
+ flex-shrink: 0;
+
+ .catalog-badge {
+ display: inline-flex;
+ align-items: center;
+ padding: 0 6px;
+ height: 18px;
+ border-radius: 4px;
+ background: var(--td-bg-color-secondarycontainer);
+ color: var(--td-text-color-secondary);
+ font-size: var(--app-text-xs);
+ line-height: 18px;
+ white-space: nowrap;
+
+ &--accent {
+ background: var(--td-brand-color-light);
+ color: var(--td-brand-color);
+ }
+ }
}
}
@@ -2441,6 +2961,21 @@ const handleCancel = () => {
// 容器留点呼吸:避免选项贴着 popup 圆角
padding: 4px;
+ // TDesign 给 select 浮层写死 max-height: 300px,而这里的选项是双行的
+ // (约 56px),正好只露出五条——下面还有二十多家厂商,但 macOS 的悬浮滚
+ // 动条不滚不显形,看上去就像"只有这几个"。放高到一屏能看到八九条,滚动
+ // 条也常驻,列表还有后续这件事才成立。&.wk-popover 只是为了压过 TDesign
+ // 自己那条同样两级的选择器。
+ &.wk-popover .t-popup__content {
+ max-height: min(480px, 60vh);
+ // Scrolling itself is restored for every skinned select in
+ // assets/theme/tdesign-overrides.less; this only makes the bar visible,
+ // because macOS overlay scrollbars stay hidden until something moves and
+ // a capped list then looks complete.
+ scrollbar-color: var(--td-component-border) transparent;
+ scrollbar-width: thin;
+ }
+
// TDesign 默认会在 t-select-option 上挂一个 overflow tooltip(浮在右侧
// 显示完整 label)。我们的选项排版是「主名称 + 次描述」两行,永远不会
// 触发省略,tooltip 反而成了视觉噪音 → 直接隐藏 popup 自带的提示。
@@ -2462,42 +2997,51 @@ const handleCancel = () => {
outline: none;
}
- // hover 态:用浅 brand 色而非强灰,跟主题色调一致
- &:hover:not(.t-is-selected) {
- background-color: var(--td-bg-color-container-hover);
- }
- }
- // 命中态:浅一点的底色 + 左侧主题色条作为 affordance,不再用全填的灰底
- .t-select-option.t-is-selected {
- background-color: var(--td-brand-color-light);
- color: var(--td-text-color-primary);
- font-weight: 500;
- position: relative;
-
- &::before {
- content: '';
- position: absolute;
- left: 0;
- top: 8px;
- bottom: 8px;
- width: 3px;
- background: var(--td-brand-color);
- border-radius: 0 2px 2px 0;
- }
+ }
- .provider-name {
- color: var(--td-brand-color);
- }
+ // 命中态不在这里定义:assets/theme/tdesign-overrides.less 已经把 TDesign
+ // 默认那条整行铺满的 --td-brand-color-light 换成了中性底色 + 一个主题色小
+ // 对勾,全站一致。这里再写一版只会让这个下拉跟「模型类型 / 模型来源」那两
+ // 排筛选对不上。选中行的主名称仍然点一下主题色,作为双行排版里的锚点。
+ .t-select-option.t-is-selected .provider-name {
+ color: var(--td-brand-color);
}
.provider-option {
display: flex;
- flex-direction: column;
- gap: 2px;
+ align-items: center;
+ gap: 10px;
width: 100%;
min-width: 0;
+ .provider-icon {
+ width: 18px;
+ height: 18px;
+ flex-shrink: 0;
+ border-radius: 4px;
+ object-fit: contain;
+
+ &--placeholder {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ font-size: var(--app-text-xs);
+ font-weight: 600;
+ color: var(--td-text-color-secondary);
+ background: var(--td-bg-color-secondarycontainer);
+ }
+ }
+
+ &__text {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ // 允许收缩,描述才能在浮层宽度内省略(浮层宽度由 matchTriggerWidth 钉死)。
+ min-width: 0;
+ flex: 1;
+ }
+
.provider-name {
font-size: var(--app-text-md);
font-weight: 500;
diff --git a/frontend/src/components/modelEditorFlow.test.ts b/frontend/src/components/modelEditorFlow.test.ts
index d87f52a16..6769c73e6 100644
--- a/frontend/src/components/modelEditorFlow.test.ts
+++ b/frontend/src/components/modelEditorFlow.test.ts
@@ -31,12 +31,25 @@ async function fixture(options: {
edit?: boolean
check?: (payload: any) => Promise<Result>
save?: (payload: any) => Promise<void>
+ providers?: any[]
+ resolve?: (params: any) => Promise<any>
} = {}) {
const requests: any[] = []
const saves: any[] = []
+ const resolves: any[] = []
+ const providers: any[] = options.providers || []
+ const providersStore = {
+ ensureLoaded: async () => providers,
+ providersFor: () => providers,
+ isLoading: () => false,
+ providerById: (id: string) => providers.find((p) => p.value === id),
+ iconFor: () => '',
+ labelFor: (id: string) => id,
+ descriptionFor: () => '',
+ }
const toasts: string[] = []
const visibility: boolean[] = []
- const props = reactive({
+ const props = reactive<{ visible: boolean; modelType: string; modelData: any }>({
visible: false,
modelType: options.type || 'chat',
modelData: options.edit ? {
@@ -50,12 +63,12 @@ async function fixture(options: {
}
const exports: any = {}
runInNewContext(compiled, {
- exports, URL, setInterval, clearInterval,
+ exports, URL, setInterval, clearInterval, setTimeout, clearTimeout, JSON,
window: { addEventListener() {}, removeEventListener() {} },
console: { error() {}, debug() {}, log() {} },
require(name: string) {
if (name === 'vue') return require('vue')
- if (name === 'vue-i18n') return { useI18n: () => ({ t: (key: string) => key, te: () => false }) }
+ if (name === 'vue-i18n') return { useI18n: () => ({ t: (key: string) => key, te: () => false, locale: { value: 'en-US' } }) }
if (name === '@/stores/ui') return { useUIStore: () => ({}) }
if (name === 'tdesign-vue-next') return {
MessagePlugin: Object.fromEntries(['success', 'error', 'warning', 'info'].map(key => [key, (text: string) => toasts.push(text)])),
@@ -63,8 +76,14 @@ async function fixture(options: {
if (name === '@/api/initialization') return {
checkRemoteModel: check, testEmbeddingModel: check, checkRerankModel: check, checkASRModel: check,
listModelProviders: async () => [], checkOllamaStatus: async () => ({ available: false }),
+ resolveModelCatalog: async (params: any) => { resolves.push(params); return options.resolve ? options.resolve(params) : {
+ provider: params.provider, api: 'openai-completions', base_url: params.base_url, remote_model: params.model,
+ cataloged: false, model: {}, capabilities: { provider: params.provider, api: 'openai-completions', cataloged: false, reasoning: false, thinking_levels: [], thinking_format: 'none' },
+ } },
}
- if (name === '@/utils/thinkingControl') return require('../utils/thinkingControl.ts')
+ if (name === '@/stores/modelProviders') return { useModelProvidersStore: () => providersStore }
+ if (name === '@/stores/modelProvidersState') return require('../stores/modelProvidersState.ts')
+ if (name === '@/utils/reasoningEffort') return require('../utils/reasoningEffort.ts')
if (name === '@/utils/contextWindow') return require('../utils/contextWindow.ts')
if (name === '@/components/modelEditorSourceState') return require('./modelEditorSourceState.ts')
return { default: {} }
@@ -92,7 +111,7 @@ async function fixture(options: {
Object.assign(vm.formData, { modelName: 'draft-model', baseUrl: 'https://example.com/v1', apiKey: options.edit ? '' : 'draft-key' })
vm.formRef = { validate: async () => true }
await nextTick()
- return { vm, props, requests, saves, toasts, visibility, close: () => app.unmount() }
+ return { vm, props, requests, saves, toasts, visibility, resolves, close: () => app.unmount() }
}
for (const type of ['chat', 'embedding', 'rerank', 'vllm', 'asr']) {
@@ -323,3 +342,473 @@ for (const edit of [false, true]) {
assert.equal(calls, 1, 'invalid drafts must not reach persistence')
})
}
+
+// --- Catalog-driven editor behaviour -------------------------------------
+
+// Objects built inside the vm context carry that realm's Object.prototype, so
+// strict deepEqual against literals fails; compare their JSON shape instead.
+const plain = (value: unknown) => JSON.parse(JSON.stringify(value))
+
+const catalogProviders = [{
+ value: 'lkeap', label: 'Tencent Cloud LKEAP', labels: { 'zh-CN': '腾讯云 LKEAP' }, description: '', order: 1,
+ icon: 'data:image/svg+xml;base64,PHN2Zy8+',
+ defaultUrls: { chat: 'https://api.lkeap.cloud.tencent.com/v1', rerank: 'https://lkeap.tencentcloudapi.com' },
+ modelTypes: ['chat', 'rerank'],
+ extraFields: [
+ { key: 'secret_key', label: 'Secret Key', type: 'password', required: true, model_types: ['Rerank'], secret: true },
+ { key: 'region', label: 'Region', type: 'string', default: 'ap-guangzhou', model_types: ['Rerank'] },
+ { key: 'api_version', label: 'API Version', type: 'string', default: '2024-10-21' },
+ ],
+ models: [
+ { id: 'deepseek-v3.1', name: 'DeepSeek V3.1', type: 'chat', reasoning: true, input: ['text', 'image'], context_window: 128000, max_output_tokens: 8192, thinking_levels: ['off', 'auto'] },
+ ],
+ thinking: { format: 'thinking.type', levels: ['off', 'auto'] },
+}]
+
+test('vendor extra fields: defaults are pre-filled per model type, secrets go to app_secret, and both reach the connection test', async () => {
+ const f = await fixture({ type: 'rerank', providers: catalogProviders })
+ try {
+ f.vm.formData.provider = 'lkeap'
+ f.vm.handleProviderChange('lkeap')
+ await nextTick()
+ assert.equal(f.vm.formData.baseUrl, 'https://lkeap.tencentcloudapi.com')
+ assert.deepEqual(f.vm.plainExtraFields.map((x: any) => x.key), ['region', 'api_version'])
+ assert.equal(f.vm.secretExtraField.key, 'secret_key')
+ assert.equal(f.vm.formData.extraConfig.region, 'ap-guangzhou')
+ assert.equal(f.vm.formData.extraConfig.api_version, '2024-10-21')
+ assert.equal(f.vm.credentialFields.some((x: any) => x.key === 'app_secret'), true)
+
+ f.vm.formData.modelName = 'lke-reranker-base'
+ f.vm.formData.appSecret = ' sk-secret '
+ f.vm.setExtraConfig('region', ' ap-beijing ')
+ await f.vm.checkRemoteAPI()
+ assert.equal(f.requests[0].appSecret, 'sk-secret')
+ assert.deepEqual(plain(f.requests[0].extraConfig), { region: 'ap-beijing', api_version: '2024-10-21' })
+
+ await f.vm.handleConfirm()
+ assert.equal(f.saves.length, 1)
+ assert.deepEqual(plain(f.saves[0].extraConfig), { region: 'ap-beijing', api_version: '2024-10-21' })
+ assert.equal(f.saves[0].appSecret, ' sk-secret ')
+ } finally { f.close() }
+})
+
+test('required vendor extra fields block saving until filled', async () => {
+ const f = await fixture({ type: 'rerank', providers: catalogProviders })
+ try {
+ f.vm.formData.provider = 'lkeap'
+ f.vm.handleProviderChange('lkeap')
+ await nextTick()
+ f.vm.formData.modelName = 'lke-reranker-base'
+ await f.vm.handleConfirm()
+ assert.equal(f.saves.length, 0, 'missing required secret_key must not save')
+ assert.equal(f.toasts.length, 1)
+ f.vm.formData.appSecret = 'sk'
+ await f.vm.handleConfirm()
+ assert.equal(f.saves.length, 1)
+ } finally { f.close() }
+})
+
+test('picking a catalog model fills blank capability fields only', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders })
+ try {
+ f.vm.formData.provider = 'lkeap'
+ await nextTick()
+ assert.deepEqual(f.vm.catalogModelOptions.map((o: any) => o.value), ['draft-model', 'deepseek-v3.1'])
+ f.vm.formData.contextWindow = 32000
+ f.vm.formData.modelName = 'deepseek-v3.1'
+ f.vm.handleCatalogModelChange('deepseek-v3.1')
+ assert.equal(f.vm.formData.contextWindow, 32000, 'user value wins')
+ assert.equal(f.vm.formData.maxOutputTokens, 8192)
+ assert.equal(f.vm.formData.supportsVision, true)
+ f.vm.handleCatalogModelCreate(' my-custom-model ')
+ assert.equal(f.vm.formData.modelName, 'my-custom-model')
+ assert.equal(f.vm.catalogModelOptions[0].value, 'my-custom-model', 'free text stays selectable')
+ } finally { f.close() }
+})
+
+test('resolve panel is refreshed once per 400ms burst of edits and ignored while hidden', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders })
+ try {
+ f.resolves.length = 0
+ f.vm.formData.provider = 'lkeap'
+ await nextTick()
+ f.vm.formData.modelName = 'deepseek-v3'
+ await nextTick()
+ f.vm.formData.modelName = 'deepseek-v3.1'
+ await nextTick()
+ assert.equal(f.resolves.length, 0, 'debounced')
+ await new Promise(resolve => setTimeout(resolve, 450))
+ assert.equal(f.resolves.length, 1)
+ assert.equal(f.resolves[0].model, 'deepseek-v3.1')
+ assert.equal(f.resolves[0].model_type, 'chat')
+ assert.equal(f.vm.resolved.api, 'openai-completions')
+ f.props.visible = false
+ await nextTick()
+ f.vm.formData.modelName = 'other'
+ await new Promise(resolve => setTimeout(resolve, 450))
+ assert.equal(f.resolves.length, 1, 'no resolve while the drawer is closed')
+ } finally { f.close() }
+})
+
+for (const type of ['embedding', 'rerank', 'asr']) {
+ test(`${type}: the catalog diagnosis panel is hidden and never fetched`, async () => {
+ const f = await fixture({ type, providers: catalogProviders })
+ try {
+ f.resolves.length = 0
+ f.vm.formData.provider = 'lkeap'
+ await nextTick()
+ f.vm.formData.modelName = 'whatever'
+ await new Promise(resolve => setTimeout(resolve, 450))
+ assert.equal(f.vm.showResolvedPanel, false, 'protocol / thinking levels are meaningless here')
+ assert.equal(f.vm.resolved, null)
+ assert.equal(f.resolves.length, 0, 'no request for a panel that is not rendered')
+ } finally { f.close() }
+ })
+}
+
+test('vllm keeps the catalog diagnosis panel', async () => {
+ const f = await fixture({ type: 'vllm', providers: catalogProviders })
+ try {
+ f.resolves.length = 0
+ f.vm.formData.provider = 'lkeap'
+ await nextTick()
+ await new Promise(resolve => setTimeout(resolve, 450))
+ assert.equal(f.vm.showResolvedPanel, true)
+ assert.equal(f.resolves.length, 1)
+ assert.equal(f.resolves[0].model_type, 'vllm')
+ } finally { f.close() }
+})
+
+test('an out-of-order resolve response cannot overwrite a newer one', async () => {
+ const pendings: Array<ReturnType<typeof deferred<any>>> = []
+ const f = await fixture({
+ type: 'chat', providers: catalogProviders,
+ resolve: (params: any) => {
+ const slot = deferred<any>()
+ pendings.push(slot)
+ return slot.promise.then((value: any) => ({ ...value, remote_model: params.model }))
+ },
+ })
+ try {
+ f.vm.formData.provider = 'lkeap'
+ f.vm.formData.modelName = 'first-model'
+ await new Promise(resolve => setTimeout(resolve, 450))
+ f.vm.formData.modelName = 'second-model'
+ await new Promise(resolve => setTimeout(resolve, 450))
+ assert.equal(pendings.length, 2, 'both requests are in flight')
+ pendings[1].resolve({ provider: 'lkeap', api: 'openai-completions', cataloged: true, capabilities: {} })
+ await nextTick()
+ pendings[0].resolve({ provider: 'lkeap', api: 'anthropic-messages', cataloged: false, capabilities: {} })
+ await new Promise(resolve => setTimeout(resolve, 10))
+ assert.equal(f.vm.resolved.remote_model, 'second-model', 'the stale answer must be dropped')
+ assert.equal(f.vm.resolved.api, 'openai-completions')
+ assert.equal(f.vm.resolving, false)
+ } finally { f.close() }
+})
+
+test('a resolve failure without a readable message shows no [object Object]', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders, resolve: async () => { throw { code: 500 } } })
+ try {
+ f.vm.formData.provider = 'lkeap'
+ await nextTick()
+ await new Promise(resolve => setTimeout(resolve, 450))
+ assert.equal(f.vm.resolveFailed, true)
+ assert.equal(f.vm.resolveError, '', 'no detail beats a stringified object')
+ assert.equal(f.vm.resolved, null)
+ } finally { f.close() }
+})
+
+test('a provider id missing from the catalog still shows in the selector', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders })
+ try {
+ f.vm.formData.provider = 'retired-vendor'
+ await nextTick()
+ assert.equal(f.vm.selectedProvider, undefined)
+ assert.equal(f.vm.selectedProviderDisplayLabel, 'retired-vendor')
+ assert.deepEqual(f.vm.plainExtraFields, [], 'an unknown vendor declares no extra fields')
+ } finally { f.close() }
+})
+
+test('editing preserves extra_config keys the current vendor does not declare', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders })
+ try {
+ f.props.visible = false
+ await nextTick()
+ f.props.modelData = {
+ id: 'legacy-extra', modelName: 'deepseek-v3.1', name: '', source: 'remote',
+ baseUrl: 'https://api.lkeap.cloud.tencent.com/v1', provider: 'lkeap', isDefault: false,
+ extraConfig: { api_version: 'v1', retired_knob: 'keep-me' },
+ spec: { reasoning: true, context_window: 64000, compat: { max_tokens_field: 'max_tokens' } },
+ }
+ f.props.visible = true
+ await nextTick()
+ await nextTick()
+ assert.deepEqual(plain(f.vm.formData.extraConfig), { api_version: 'v1', retired_knob: 'keep-me' })
+ await f.vm.handleConfirm()
+ assert.equal(f.saves.length, 1)
+ assert.deepEqual(plain(f.saves[0].extraConfig), { api_version: 'v1', retired_knob: 'keep-me' })
+ assert.deepEqual(
+ plain(f.saves[0].spec),
+ { reasoning: true, context_window: 64000, compat: { max_tokens_field: 'max_tokens' } },
+ 'spec fields other than compat survive the round-trip',
+ )
+ } finally { f.close() }
+})
+
+test('advanced overrides: invalid compat JSON blocks save, valid JSON and protocol override are persisted', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders })
+ try {
+ f.vm.formData.provider = 'lkeap'
+ f.vm.setExtraConfig('api', 'openai-responses')
+ f.vm.setExtraConfig('remote_model_name', '')
+ f.vm.formData.specCompat = '{ not json'
+ await nextTick()
+ assert.notEqual(f.vm.specCompatError, '')
+ await f.vm.handleConfirm()
+ assert.equal(f.saves.length, 0)
+ assert.equal(f.vm.advancedOpen, true, 'the advanced section opens to show the error')
+ f.vm.formData.specCompat = '["array"]'
+ await nextTick()
+ assert.equal(f.vm.specCompatError, 'model.editor.advanced.compat.mustBeObject')
+ f.vm.formData.specCompat = '{"max_tokens_field": "max_tokens"}'
+ await nextTick()
+ assert.equal(f.vm.specCompatError, '')
+ await f.vm.handleConfirm()
+ assert.equal(f.saves.length, 1)
+ assert.deepEqual(plain(f.saves[0].extraConfig), { api: 'openai-responses' })
+ assert.equal(f.saves[0].specCompat, '{"max_tokens_field": "max_tokens"}')
+ } finally { f.close() }
+})
+
+test('editing a legacy row keeps thinking_control until the user clears it', async () => {
+ const f = await fixture({ type: 'chat', providers: catalogProviders })
+ try {
+ f.props.visible = false
+ await nextTick()
+ f.props.modelData = {
+ id: 'legacy', modelName: 'qwen3-32b', name: '', source: 'remote', baseUrl: 'https://example.com/v1',
+ provider: 'aliyun', isDefault: false, thinkingControl: 'enable_thinking',
+ extraConfig: { thinking_control: 'enable_thinking', api_version: 'v1' },
+ spec: { compat: { max_tokens_field: 'max_tokens' }, context_window: 1 },
+ }
+ f.props.visible = true
+ await nextTick()
+ await nextTick()
+ assert.equal(f.vm.showLegacyThinkingControl, true)
+ assert.equal(f.vm.formData.thinkingControl, 'enable_thinking')
+ assert.deepEqual(plain(f.vm.formData.extraConfig), { api_version: 'v1' })
+ assert.equal(f.vm.formData.specCompat, JSON.stringify({ max_tokens_field: 'max_tokens' }, null, 2))
+ assert.deepEqual(plain(f.vm.buildExtraConfig()), { api_version: 'v1', thinking_control: 'enable_thinking' })
+ f.vm.formData.thinkingControl = ''
+ assert.equal(f.vm.showLegacyThinkingControl, true, 'select stays visible after clearing')
+ assert.deepEqual(plain(f.vm.buildExtraConfig()), { api_version: 'v1' })
+ } finally { f.close() }
+})
+
+test('parent save serializes extra_config, spec.compat and max_output_tokens from the editor payload', async () => {
+ const payloads: any[] = []
+ const save = runInNewContext(saveScript + '\nhandleModelSave', {
+ URL, console: { error() {} },
+ currentModelType: { value: 'chat' }, editingModel: { value: null },
+ getModelType: () => 'KnowledgeQA', t: (key: string) => key,
+ createModel: async (data: any) => { payloads.push(data) }, updateModelAPI: async () => {},
+ MessagePlugin: { success() {}, error() {}, warning() {} }, loadModels: async () => {},
+ })
+ await save({
+ modelName: 'gpt-5', source: 'remote', baseUrl: 'https://api.openai.com/v1', provider: 'openai',
+ extraConfig: { api: 'openai-responses', remote_model_name: ' gpt-5-2025 ', empty: ' ' },
+ thinkingControl: '', specCompat: '{"max_tokens_field":"max_completion_tokens"}',
+ spec: { compat: { old: true }, reasoning: true }, contextWindow: 400000, maxOutputTokens: 16384,
+ })
+ assert.equal(payloads.length, 1)
+ const params = payloads[0].parameters
+ assert.deepEqual(plain(params.extra_config), { api: 'openai-responses', remote_model_name: 'gpt-5-2025' })
+ assert.deepEqual(plain(params.spec), { reasoning: true, compat: { max_tokens_field: 'max_completion_tokens' } })
+ assert.equal(params.max_output_tokens, 16384)
+ assert.equal(params.context_window, 400000)
+ await assert.rejects(save({
+ modelName: 'gpt-5', source: 'remote', baseUrl: 'https://api.openai.com/v1', specCompat: '[1]',
+ }), /compat\.invalid/)
+})
+
+// PUT /models/:id restores the stored extra_config when the field is absent
+// (internal/handler/model.go), so clearing the last key has to be sent as {}.
+test('parent save sends an empty extra_config so cleared vendor fields really clear', async () => {
+ const updates: any[] = []
+ const creates: any[] = []
+ const save = runInNewContext(saveScript + '\nhandleModelSave', {
+ URL, console: { error() {} },
+ currentModelType: { value: 'chat' }, editingModel: { value: { id: 'saved-model' } },
+ getModelType: () => 'KnowledgeQA', t: (key: string) => key,
+ createModel: async (data: any) => { creates.push(data) },
+ updateModelAPI: async (_id: string, data: any) => { updates.push(data) },
+ MessagePlugin: { success() {}, error() {}, warning() {} }, loadModels: async () => {},
+ })
+ await save({
+ modelName: 'gpt-5', source: 'remote', baseUrl: 'https://api.openai.com/v1', provider: 'openai',
+ extraConfig: {}, thinkingControl: '',
+ })
+ assert.deepEqual(plain(updates[0].parameters.extra_config), {})
+ // Local rows never edit extra_config here, so they keep the omit-and-preserve path.
+ await save({ modelName: 'llama3', source: 'local', extraConfig: {}, thinkingControl: '' })
+ assert.equal('extra_config' in updates[1].parameters, false)
+ assert.equal(creates.length, 0)
+})
+
+// Two vendors that share one model id (deepseek-v4-pro is sold by DeepSeek,
+// Aliyun, Volcengine and the gateways alike) and one that does not.
+const switchProviders = [
+ {
+ value: 'vendor-a', label: 'Vendor A', description: '', order: 1, modelTypes: ['chat'],
+ defaultUrls: { chat: 'https://a.example.com/v1' },
+ models: [
+ { id: 'shared-model', name: 'Shared', type: 'chat', context_window: 128000, max_output_tokens: 8192 },
+ { id: 'only-on-a', name: 'Only on A', type: 'chat', context_window: 1000000, input: ['text', 'image'] },
+ ],
+ },
+ {
+ value: 'vendor-b', label: 'Vendor B', description: '', order: 2, modelTypes: ['chat'],
+ defaultUrls: { chat: 'https://b.example.com/v1' },
+ models: [
+ { id: 'shared-model', name: 'Shared', type: 'chat', context_window: 128000 },
+ ],
+ },
+]
+
+test('switching vendor drops a model the new vendor does not serve, and what the catalog filled for it', async () => {
+ const f = await fixture({ providers: switchProviders })
+ try {
+ f.vm.formData.provider = 'vendor-a'
+ f.vm.handleProviderChange('vendor-a')
+ await nextTick()
+ // The select's v-model writes the name; the change handler fills the
+ // capability fields from the catalog entry.
+ f.vm.formData.modelName = 'only-on-a'
+ f.vm.handleCatalogModelChange('only-on-a')
+ await nextTick()
+ assert.equal(f.vm.formData.modelName, 'only-on-a')
+ // The catalog filled these, so they belong to that model.
+ assert.equal(f.vm.formData.contextWindow, 1000000)
+ assert.equal(f.vm.formData.supportsVision, true)
+
+ f.vm.formData.provider = 'vendor-b'
+ f.vm.handleProviderChange('vendor-b')
+ await nextTick()
+ // Left in place the name would be saved verbatim and fail at first call.
+ assert.equal(f.vm.formData.modelName, '')
+ // A 1M window from another vendor's model is the exact mis-configuration
+ // the field warns about, so it goes with the name.
+ assert.equal(f.vm.formData.contextWindow, undefined)
+ assert.equal(f.vm.formData.supportsVision, false)
+ assert.equal(f.vm.formData.baseUrl, 'https://b.example.com/v1')
+ } finally { f.close() }
+})
+
+test('switching vendor keeps a model both vendors serve, and never discards typed values', async () => {
+ const f = await fixture({ providers: switchProviders })
+ try {
+ f.vm.formData.provider = 'vendor-a'
+ f.vm.handleProviderChange('vendor-a')
+ await nextTick()
+ f.vm.formData.modelName = 'shared-model'
+ f.vm.handleCatalogModelChange('shared-model')
+ await nextTick()
+ // The operator overrides the catalog's number by hand.
+ f.vm.formData.contextWindow = 64000
+ f.vm.formData.maxOutputTokens = 4096
+
+ f.vm.formData.provider = 'vendor-b'
+ f.vm.handleProviderChange('vendor-b')
+ await nextTick()
+ assert.equal(f.vm.formData.modelName, 'shared-model', 'both vendors serve it')
+ assert.equal(f.vm.formData.contextWindow, 64000, 'a typed value is the operator‘s')
+ assert.equal(f.vm.formData.maxOutputTokens, 4096)
+ } finally { f.close() }
+})
+
+test('switching vendor clears a connection result that described the old one', async () => {
+ const f = await fixture({ providers: switchProviders })
+ try {
+ f.vm.formData.provider = 'vendor-a'
+ f.vm.handleProviderChange('vendor-a')
+ await nextTick()
+ f.vm.formData.modelName = 'shared-model'
+ await f.vm.checkRemoteAPI()
+ assert.equal(f.vm.remoteChecked, true)
+
+ f.vm.formData.provider = 'vendor-b'
+ f.vm.handleProviderChange('vendor-b')
+ await nextTick()
+ assert.equal(f.vm.remoteChecked, false)
+ assert.equal(f.vm.remoteMessage, '')
+ } finally { f.close() }
+})
+
+// A VLM entry is a chat model that accepts images, so the backend — which
+// already scopes the provider list to the requested model type — returns it
+// typed "chat". Re-filtering on that type in the editor emptied the picker
+// for every vendor under 视觉.
+const vlmProviders = [{
+ value: 'vendor-v', label: 'Vendor V', description: '', order: 1, modelTypes: ['chat', 'vllm'],
+ defaultUrls: { chat: 'https://v.example.com/v1', vllm: 'https://v.example.com/v1' },
+ models: [
+ { id: 'sees-images', name: 'Sees Images', type: 'chat', input: ['text', 'image'], context_window: 128000 },
+ ],
+}]
+
+test('the vision picker lists the vendor models the backend scoped to it', async () => {
+ const f = await fixture({ type: 'vllm', providers: vlmProviders })
+ try {
+ f.vm.formData.provider = 'vendor-v'
+ f.vm.handleProviderChange('vendor-v')
+ await nextTick()
+ assert.deepEqual(f.vm.catalogModelOptions.map((o: any) => o.value), ['sees-images'])
+ assert.equal(f.vm.catalogModelOptions[0].vision, true)
+ } finally { f.close() }
+})
+
+test('rerank and asr pickers list their own entries', async () => {
+ for (const [type, id] of [['rerank', 'the-reranker'], ['asr', 'the-transcriber']]) {
+ const providers = [{
+ value: 'vendor-t', label: 'Vendor T', description: '', order: 1, modelTypes: [type],
+ defaultUrls: { [type]: 'https://t.example.com/v1' },
+ models: [{ id, name: id, type }],
+ }]
+ const f = await fixture({ type, providers })
+ try {
+ f.vm.formData.provider = 'vendor-t'
+ f.vm.handleProviderChange('vendor-t')
+ await nextTick()
+ assert.deepEqual(f.vm.catalogModelOptions.map((o: any) => o.value), [id], type)
+ } finally { f.close() }
+ }
+})
+
+// TDesign hides a select's popup when it has no options, which takes the
+// creatable "create" row with it: the field accepts keystrokes but offers no
+// way to commit them, and a blur throws the text away. That is every vendor
+// with no catalog for the current type — 自定义 (OpenAI 兼容接口) above all.
+test('a vendor with no catalog falls back to a plain text field', async () => {
+ const f = await fixture({ providers: switchProviders })
+ try {
+ f.vm.formData.provider = 'vendor-a'
+ f.vm.handleProviderChange('vendor-a')
+ await nextTick()
+ assert.ok(f.vm.catalogModelOptions.length > 0, 'a catalogued vendor keeps the picker')
+
+ const f2 = await fixture({ providers: [{
+ value: 'bare', label: 'Bare', description: '', order: 1, modelTypes: ['chat'],
+ defaultUrls: { chat: 'https://bare.example.com/v1' }, models: [],
+ }] })
+ try {
+ f2.vm.formData.provider = 'bare'
+ f2.vm.handleProviderChange('bare')
+ await nextTick()
+ assert.equal(f2.vm.catalogModelOptions.length, 0)
+ // Typing is the only way in, and it must survive as the model name.
+ f2.vm.formData.modelName = 'my-own-model'
+ await nextTick()
+ assert.equal(f2.vm.formData.modelName, 'my-own-model')
+ } finally { f2.close() }
+ } finally { f.close() }
+})
diff --git a/frontend/src/components/settings/SettingDrawer.vue b/frontend/src/components/settings/SettingDrawer.vue
index 11b30e479..828b08ee8 100644
--- a/frontend/src/components/settings/SettingDrawer.vue
+++ b/frontend/src/components/settings/SettingDrawer.vue
@@ -330,20 +330,19 @@ const handleCancel = () => {
gap: 10px;
flex: 1;
min-width: 0;
- padding: 2px 0;
}
.setting-drawer__header-icon {
flex-shrink: 0;
- width: 32px;
- height: 32px;
- border-radius: 9px;
+ width: 28px;
+ height: 28px;
+ border-radius: 8px;
display: flex;
align-items: center;
justify-content: center;
background: color-mix(in srgb, var(--td-brand-color) 10%, transparent);
color: var(--td-brand-color);
- font-size: var(--app-text-xl);
+ font-size: var(--app-text-lg);
transition: background var(--app-motion-base) ease;
}
@@ -557,7 +556,10 @@ const handleCancel = () => {
}
.t-drawer__header {
- padding: 14px 18px;
+ // 72px 的抽屉头在一屏设置里太重:图标 32px、上下各 14px,再加标题与副标题
+ // 两行。收到 60px(图标 28px、内边距 10px)够了,标题字号刻意不动——再小
+ // 就和正文里的字段标签一样大,层级会塌。
+ padding: 10px 18px;
border-bottom: 1px solid var(--td-component-stroke);
}
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index 396241eaf..22b4ce262 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -1114,6 +1114,8 @@ export default {
enabled: 'Agent enabled'
},
editor: {
+ reasoningEffortUnsupported: 'The selected model cannot think; every option except "Off" is ignored.',
+ reasoningEffortAlwaysOn: 'The selected model always reasons and cannot be switched off; only the effort level can be changed.',
createTitle: 'Create Agent',
editTitle: 'Edit Agent',
buttons: {
@@ -4593,6 +4595,28 @@ export default {
}
},
model: {
+ reasoning: {
+ levels: {
+ off: 'Off',
+ auto: 'Auto',
+ minimal: 'Minimal',
+ low: 'Low',
+ medium: 'Medium',
+ high: 'High',
+ xhigh: 'Extra high',
+ max: 'Max',
+ },
+ levelDescriptions: {
+ off: 'Thinking disabled; no thinking parameters are sent',
+ auto: 'Vendor default intensity; the model decides how much to think',
+ minimal: 'Least thinking, fastest responses',
+ low: 'Light thinking',
+ medium: 'Moderate thinking',
+ high: 'Deep thinking, slower responses',
+ xhigh: 'Very high thinking budget (select models only)',
+ max: 'Maximum thinking budget (select models only)',
+ },
+ },
modelName: 'Model Name',
defaultTag: 'Default',
addModelInSettings: 'Go to global settings to add models',
@@ -4600,6 +4624,53 @@ export default {
selectModelPlaceholder: 'Select a model',
searchPlaceholder: 'Search models...',
editor: {
+ maxOutputTokensLabel: 'Max output tokens',
+ maxOutputTokensPlaceholder: 'Leave empty for the catalog default',
+ maxOutputTokensDesc: 'Output cap per response. Leave empty to use the catalog default for this model.',
+ catalog: {
+ reasoning: 'Reasoning',
+ vision: 'Vision',
+ hint: 'Pick a model from the vendor catalog or type a custom model name.',
+ },
+ resolved: {
+ title: 'How this model is called',
+ empty: 'Fill in the vendor and model name to see how this model will be called',
+ failed: 'Resolve failed',
+ protocol: 'Request protocol',
+ catalog: 'Capabilities from',
+ catalogedYes: 'Built-in model profile',
+ catalogedNo: 'Vendor defaults (model not in the catalog)',
+ endpoint: 'Request endpoint',
+ thinkingFormat: 'Thinking switch sent as',
+ thinkingLevels: 'Selectable effort',
+ noThinking: 'This model cannot think',
+ },
+ advanced: {
+ toggle: 'Advanced',
+ api: {
+ label: 'Protocol override',
+ auto: 'Auto (from vendor / URL)',
+ desc: 'Force a request protocol; normally unnecessary.',
+ },
+ remoteModelName: {
+ label: 'Remote model name',
+ placeholder: 'Leave empty to use the model name',
+ desc: 'Model id actually sent to the vendor when it differs from the name above.',
+ },
+ legacyThinking: {
+ label: 'Thinking parameter format (legacy)',
+ catalog: 'Follow catalog default (recommended)',
+ none: 'Do not send thinking fields',
+ desc: 'This model still carries a legacy thinking_control setting. Choose "Follow catalog default" to let the catalog decide.',
+ },
+ compat: {
+ label: 'Protocol compat override (JSON)',
+ placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
+ desc: 'Compat switches merged over the catalog defaults for the resolved protocol; see catalog/compat.go on the backend. Leave empty for no override.',
+ invalid: 'Invalid JSON',
+ mustBeObject: 'Must be a JSON object',
+ },
+ },
addTitle: 'Add Model',
editTitle: 'Edit Model',
sectionType: 'Model Type',
@@ -4634,23 +4705,6 @@ export default {
baseUrlPlaceholderAsr: 'e.g. https://api.openai.com/v1',
apiKeyOptional: 'API Key (optional)',
apiKeyPlaceholder: 'Enter API Key',
- lkeap: {
- secretIdLabel: 'SecretId',
- secretIdPlaceholder: 'Tencent Cloud API SecretId',
- secretKeyLabel: 'SecretKey',
- secretKeyPlaceholder: 'Tencent Cloud API SecretKey',
- regionLabel: 'Region',
- regionPlaceholder: 'ap-guangzhou',
- regionDesc: 'RunRerank supports ap-beijing, ap-guangzhou, etc. Default: ap-guangzhou',
- rerankCredentialHint: 'Rerank uses Tencent Cloud API signature (not the OpenAI-style LKEAP API key). Create SecretId/SecretKey in the CAM console.'
- },
- volcengine: {
- accessKeyLabel: 'Access Key ID',
- accessKeyPlaceholder: 'Volcengine Access Key ID',
- secretKeyLabel: 'Secret Access Key',
- secretKeyPlaceholder: 'Volcengine Secret Access Key',
- rerankCredentialHint: 'Rerank uses VikingDB AK/SK signing, not an Ark API key. Recommended model: doubao-seed-rerank.'
- },
customHeadersLabel: 'Custom Request Headers (optional)',
customHeadersDesc: 'Extra HTTP headers appended to requests to the remote model API (e.g. for enterprise gateway auth or tracing). Reserved headers like Authorization / Content-Type are ignored.',
customHeadersAdd: 'Add Header',
@@ -4678,26 +4732,6 @@ export default {
maxConcurrencyLabel: 'Background concurrency limit',
maxConcurrencyPlaceholder: '0 = use global default',
maxConcurrencyDesc: 'Caps concurrent background (ingestion/enrichment) calls to this model, shared per model across all replicas. 0 or empty falls back to the global default; interactive chat is never affected.',
- thinkingControlLabel: 'Thinking mode request format',
- thinkingControlDesc: 'Controls how the agent’s “Thinking mode” on/off switch is written to the API. We pre-select based on vendor/model when possible; change it to match your API docs. With “Do not send”, the agent Thinking mode switch has no effect.',
- thinkingControl: {
- none: {
- label: 'Do not send thinking fields',
- hint: 'Agent “Thinking mode” switch has no effect; thinking parameters are not sent in requests'
- },
- chatTemplateKwargs: {
- label: 'chat_template_kwargs',
- hint: 'Custom OpenAI-compatible gateways, NVIDIA NIM, vLLM / local Qwen'
- },
- enableThinking: {
- label: 'enable_thinking',
- hint: 'Alibaba DashScope: qwen3, qwen-plus, qwen-max, qwen-turbo'
- },
- thinkingType: {
- label: 'thinking.type',
- hint: 'Volcengine Ark; Tencent LKEAP (DeepSeek V3, etc.; default for LKEAP; use “Do not send” for R1)'
- }
- },
dimensionHint: 'Model selected. Click "Detect Dimension" to fetch the vector dimension automatically.',
loadModelListFailed: 'Failed to load model list',
listRefreshed: 'List refreshed',
@@ -4719,6 +4753,7 @@ export default {
ollamaNotSupportRerank: 'Ollama does not support ReRank models, please use a remote API instead',
goToOllamaSettings: 'Open Settings',
validation: {
+ extraFieldRequired: 'Please fill in {name}',
modelNameRequired: 'Please enter the model name',
modelNameEmpty: 'Model name cannot be empty',
modelNameMax: 'Model name cannot exceed 100 characters',
@@ -4728,112 +4763,7 @@ export default {
},
providerLabel: 'Provider',
providerPlaceholder: 'Select model provider',
- providers: {
- openai: {
- label: 'OpenAI',
- description: 'gpt-5.2, gpt-5-mini, etc.'
- },
- anthropic: {
- label: 'Anthropic',
- description: 'Claude models via native Anthropic Messages API'
- },
- azure_openai: {
- label: 'Azure OpenAI',
- description: 'OpenAI service hosted on Microsoft Azure'
- },
- aliyun: {
- label: 'Aliyun DashScope',
- description: 'qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank, etc.'
- },
- zhipu: {
- label: 'Zhipu BigModel',
- description: 'glm-4.7, embedding-3, rerank, etc.'
- },
- openrouter: {
- label: 'OpenRouter',
- description: 'openai/gpt-5.2-chat, google/gemini-3-flash-preview, etc.'
- },
- litellm: {
- label: 'LiteLLM',
- description: 'Self-hosted proxy to 100+ providers (OpenAI, Anthropic, Gemini, Bedrock, etc.). Replace the placeholder URL; loopback hosts need SSRF_WHITELIST.'
- },
- requesty: {
- label: 'Requesty',
- description: 'openai/gpt-4o-mini, anthropic/claude-sonnet-4-5, etc.'
- },
- generic: {
- label: 'Custom (OpenAI-compatible)',
- description: 'Generic API endpoint'
- },
- siliconflow: {
- label: 'SiliconFlow',
- description: 'deepseek-ai/DeepSeek-V3.1, etc.'
- },
- jina: {
- label: 'Jina',
- description: 'jina-clip-v1, jina-embeddings-v2-base-zh, etc.'
- },
- volcengine: {
- label: 'Volcengine',
- description: 'doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615, etc.'
- },
- deepseek: {
- label: 'DeepSeek',
- description: 'deepseek-chat, deepseek-reasoner, etc.'
- },
- hunyuan: {
- label: 'Hunyuan',
- description: 'hunyuan-pro, hunyuan-standard, hunyuan-embedding, etc.'
- },
- minimax: {
- label: 'MiniMax',
- description: 'MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed, etc.'
- },
- mimo: {
- label: 'MiMo',
- description: 'mimo-v2-flash'
- },
- gemini: {
- label: 'Google Gemini',
- description: 'gemini-3-flash-preview, gemini-2.5-pro, etc.'
- },
- gpustack: {
- label: 'GPUStack',
- description: 'Choose your deployed model on GPUStack'
- },
- modelscope: {
- label: 'ModelScope',
- description: 'Qwen/Qwen3-8B, Qwen/Qwen3-Embedding-8B, etc.'
- },
- qiniu: {
- label: 'Qiniu Cloud',
- description: 'deepseek/deepseek-v3.2-251201, z-ai/glm-4.7, etc.'
- },
- moonshot: {
- label: 'Moonshot',
- description: 'kimi-k2-turbo-preview, moonshot-v1-8k-vision-preview, etc.'
- },
- qianfan: {
- label: 'Baidu Qianfan',
- description: 'ernie-5.0-thinking-preview, embedding-v1, bce-reranker-base, etc.'
- },
- longcat: {
- label: 'LongCat AI',
- description: 'LongCat-Flash-Chat, LongCat-Flash-Thinking, etc.'
- },
- lkeap: {
- label: 'Tencent Cloud LKEAP',
- description: 'DeepSeek-R1, DeepSeek-V3, lke-reranker-base, etc.'
- },
- nvidia: {
- label: 'NVIDIA',
- description: 'deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.'
- },
- novita: {
- label: 'Novita AI',
- description: 'moonshotai/kimi-k2.5, zai-org/glm-5, minimax/minimax-m2.7, qwen/qwen3-embedding-0.6b, etc.'
- }
- }
+ providerDocs: 'Read the {provider} model docs',
},
builtinTag: 'Built-in'
},
@@ -5199,6 +5129,8 @@ export default {
}
},
debug: {
+ reasoningEffort: 'Reasoning effort',
+ reasoningEffortDesc: 'Sends reasoning_effort using the levels reported by the model catalog',
title: 'Model Test',
description: 'Send a real request using saved model settings. Save pending edits before testing here.',
groupModel: 'Select model',
@@ -5221,15 +5153,11 @@ export default {
audioFile: 'Audio file',
chooseFile: 'Choose file',
parameters: 'Request parameters',
- thinking: 'Thinking mode',
- thinkingDesc: 'Only applies to models that support thinking',
systemPrompt: 'System Prompt',
systemPromptPlaceholder: 'Optional system prompt',
run: 'Run test',
copyResult: 'Copy result',
history: 'History',
- thinkOn: 'Thinking on',
- thinkOff: 'Thinking off',
runLabel: 'Run #{n}',
success: 'Request succeeded',
failed: 'Request failed',
@@ -5237,6 +5165,9 @@ export default {
requestPreview: 'Request preview',
requestFailed: 'Model test request failed',
metrics: {
+ api: 'Protocol',
+ thinkingFormat: 'Thinking format',
+ requestedReasoningEffort: 'Requested effort',
dimension: 'Dimensions',
resultCount: 'Result count',
answerChars: 'Answer chars',
diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.ts
index f1de7197d..8fcd47d3a 100644
--- a/frontend/src/i18n/locales/ja-JP.ts
+++ b/frontend/src/i18n/locales/ja-JP.ts
@@ -1114,6 +1114,8 @@ export default {
enabled: 'エージェントを有効化しました'
},
editor: {
+ reasoningEffortUnsupported: '選択中のモデルは思考に対応していません。「オフ」以外は無視されます。',
+ reasoningEffortAlwaysOn: '選択中のモデルは常に思考します。オフにはできず、強度のみ調整できます。',
createTitle: 'エージェントを作成',
editTitle: 'エージェントを編集',
buttons: {
@@ -4593,6 +4595,28 @@ export default {
}
},
model: {
+ reasoning: {
+ levels: {
+ off: 'オフ',
+ auto: '自動',
+ minimal: '最小',
+ low: '低',
+ medium: '中',
+ high: '高',
+ xhigh: '超高',
+ max: '最大',
+ },
+ levelDescriptions: {
+ off: '思考を無効化し、思考パラメータを送信しません',
+ auto: 'ベンダー既定の強度。思考量はモデルが決めます',
+ minimal: '最小限の思考、最速の応答',
+ low: '軽い思考',
+ medium: '中程度の思考',
+ high: '深い思考、応答は遅くなります',
+ xhigh: '超高の思考予算(一部モデルのみ)',
+ max: '最大の思考予算(一部モデルのみ)',
+ },
+ },
modelName: 'モデル名',
defaultTag: 'デフォルト',
addModelInSettings: 'モデルを追加するにはシステム設定を開いてください',
@@ -4600,6 +4624,53 @@ export default {
selectModelPlaceholder: 'モデルを選択',
searchPlaceholder: 'モデルを検索...',
editor: {
+ maxOutputTokensLabel: '最大出力トークン',
+ maxOutputTokensPlaceholder: '空欄でカタログ既定値',
+ maxOutputTokensDesc: '1 回の応答の出力上限。空欄ならこのモデルのカタログ既定値を使用します。',
+ catalog: {
+ reasoning: '推論',
+ vision: '画像',
+ hint: 'ベンダーのカタログから選ぶか、カスタムのモデル名を入力できます。',
+ },
+ resolved: {
+ title: '実際の呼び出し方',
+ empty: 'ベンダーとモデル名を入力すると、このモデルの呼び出し方を表示します',
+ failed: '解決に失敗',
+ protocol: 'リクエストプロトコル',
+ catalog: '能力の取得元',
+ catalogedYes: '内蔵モデルプロファイル',
+ catalogedNo: 'ベンダー既定(カタログ未収録)',
+ endpoint: 'リクエスト先',
+ thinkingFormat: '思考切替の送り方',
+ thinkingLevels: '選択できる思考強度',
+ noThinking: 'このモデルは思考できません',
+ },
+ advanced: {
+ toggle: '詳細設定',
+ api: {
+ label: 'プロトコル上書き',
+ auto: '自動(ベンダー / URL から推定)',
+ desc: 'リクエストプロトコルを強制します。通常は変更不要です。',
+ },
+ remoteModelName: {
+ label: 'リモートモデル名',
+ placeholder: '空欄でモデル名と同じ',
+ desc: '上のモデル名と異なる場合に、実際にベンダーへ送るモデル ID。',
+ },
+ legacyThinking: {
+ label: '思考パラメータ形式(旧設定)',
+ catalog: 'カタログ既定に従う(推奨)',
+ none: '思考パラメータを送信しない',
+ desc: 'このモデルには旧版の thinking_control 設定が残っています。「カタログ既定に従う」を選ぶとカタログが決定します。',
+ },
+ compat: {
+ label: 'プロトコル互換上書き(JSON)',
+ placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
+ desc: '解決されたプロトコルのカタログ既定値に上書きマージされる互換スイッチ。バックエンドの catalog/compat.go を参照。空欄で上書きなし。',
+ invalid: 'JSON が不正です',
+ mustBeObject: 'JSON オブジェクトが必要です',
+ },
+ },
addTitle: 'モデルを追加',
editTitle: 'モデルを編集',
sectionType: 'モデルタイプ',
@@ -4634,23 +4705,6 @@ export default {
baseUrlPlaceholderAsr: '例: https://api.openai.com/v1',
apiKeyOptional: 'APIキー(任意)',
apiKeyPlaceholder: 'APIキーを入力してください',
- lkeap: {
- secretIdLabel: 'SecretId',
- secretIdPlaceholder: 'Tencent Cloud APIのSecretId',
- secretKeyLabel: 'SecretKey',
- secretKeyPlaceholder: 'Tencent Cloud APIのSecretKey',
- regionLabel: 'リージョン',
- regionPlaceholder: 'ap-guangzhou',
- regionDesc: 'RunRerankはap-beijing、ap-guangzhouなどに対応しています。デフォルト値: ap-guangzhou',
- rerankCredentialHint: 'リランクはTencent CloudのAPI署名(OpenAI形式のLKEAP APIキーではありません)を使用します。SecretId/SecretKeyはCAMコンソールで作成してください。'
- },
- volcengine: {
- accessKeyLabel: 'Access Key ID',
- accessKeyPlaceholder: 'VolcengineのAccess Key ID',
- secretKeyLabel: 'Secret Access Key',
- secretKeyPlaceholder: 'VolcengineのSecret Access Key',
- rerankCredentialHint: 'リランクはArkのAPIキーではなく、VikingDBのAK/SK署名を使用します。推奨モデル: doubao-seed-rerank。'
- },
customHeadersLabel: 'カスタムリクエストヘッダー(任意)',
customHeadersDesc: 'リモートモデルAPIへのリクエストに追加するHTTPヘッダーです(企業ゲートウェイの認証やトレースなどに利用)。Authorization / Content-Typeなどの予約ヘッダーは無視されます。',
customHeadersAdd: 'ヘッダーを追加',
@@ -4678,26 +4732,6 @@ export default {
maxConcurrencyLabel: 'バックグラウンドの並列実行上限',
maxConcurrencyPlaceholder: '0 = グローバルのデフォルト値を使用',
maxConcurrencyDesc: 'このモデルへのバックグラウンド(取り込み・エンリッチメント)呼び出しの並列数を制限します。モデルごとにすべてのレプリカで共有されます。0または空欄の場合はグローバルのデフォルト値が使われます。対話型のチャットには影響しません。',
- thinkingControlLabel: '思考モードのリクエスト形式',
- thinkingControlDesc: 'エージェントの「思考モード」のオン/オフをAPIにどう送信するかを設定します。可能な場合はベンダやモデルに応じて自動選択されます。お使いのAPIドキュメントに合わせて変更してください。「送信しない」を選ぶと、エージェントの思考モードの切り替えは効果がありません。',
- thinkingControl: {
- none: {
- label: '思考関連のフィールドを送信しない',
- hint: 'エージェントの「思考モード」の切り替えは効果がなく、リクエストに思考パラメータは送信されません'
- },
- chatTemplateKwargs: {
- label: 'chat_template_kwargs',
- hint: 'OpenAI互換のカスタムゲートウェイ、NVIDIA NIM、vLLM / ローカルのQwen'
- },
- enableThinking: {
- label: 'enable_thinking',
- hint: 'Alibaba DashScope: qwen3、qwen-plus、qwen-max、qwen-turbo'
- },
- thinkingType: {
- label: 'thinking.type',
- hint: 'Volcengine Ark、Tencent LKEAP(DeepSeek V3など。LKEAPのデフォルト値。R1では「送信しない」を使用)'
- }
- },
dimensionHint: 'モデルを選択しました。「次元数を検出」をクリックするとベクトル次元数を自動取得できます。',
loadModelListFailed: 'モデル一覧の読み込みに失敗しました',
listRefreshed: '一覧を更新しました',
@@ -4719,6 +4753,7 @@ export default {
ollamaNotSupportRerank: 'Ollamaはリランクモデルに対応していません。リモートAPIを使用してください',
goToOllamaSettings: '設定を開く',
validation: {
+ extraFieldRequired: '{name} を入力してください',
modelNameRequired: 'モデル名を入力してください',
modelNameEmpty: 'モデル名は空にできません',
modelNameMax: 'モデル名は100文字以内で入力してください',
@@ -4728,112 +4763,7 @@ export default {
},
providerLabel: 'プロバイダ',
providerPlaceholder: 'モデルプロバイダを選択',
- providers: {
- openai: {
- label: 'OpenAI',
- description: 'gpt-5.2、gpt-5-miniなど'
- },
- anthropic: {
- label: 'Anthropic',
- description: 'ネイティブのAnthropic Messages API経由のClaudeモデル'
- },
- azure_openai: {
- label: 'Azure OpenAI',
- description: 'Microsoft AzureでホストされるOpenAIサービス'
- },
- aliyun: {
- label: 'Aliyun DashScope',
- description: 'qwen-plus、tongyi-embedding-vision-plus、qwen3-rerankなど'
- },
- zhipu: {
- label: 'Zhipu BigModel',
- description: 'glm-4.7、embedding-3、rerankなど'
- },
- openrouter: {
- label: 'OpenRouter',
- description: 'openai/gpt-5.2-chat、google/gemini-3-flash-previewなど'
- },
- litellm: {
- label: 'LiteLLM',
- description: '100以上のプロバイダ(OpenAI、Anthropic、Gemini、Bedrockなど)へのセルフホスト型プロキシです。プレースホルダのURLを置き換えてください。ループバックのホストにはSSRF_WHITELISTの設定が必要です。'
- },
- requesty: {
- label: 'Requesty',
- description: 'openai/gpt-4o-mini、anthropic/claude-sonnet-4-5など'
- },
- generic: {
- label: 'カスタム(OpenAI互換)',
- description: '汎用のAPIエンドポイント'
- },
- siliconflow: {
- label: 'SiliconFlow',
- description: 'deepseek-ai/DeepSeek-V3.1など'
- },
- jina: {
- label: 'Jina',
- description: 'jina-clip-v1、jina-embeddings-v2-base-zhなど'
- },
- volcengine: {
- label: 'Volcengine',
- description: 'doubao-1-5-pro-32k-250115、doubao-embedding-vision-250615など'
- },
- deepseek: {
- label: 'DeepSeek',
- description: 'deepseek-chat、deepseek-reasonerなど'
- },
- hunyuan: {
- label: 'Hunyuan',
- description: 'hunyuan-pro、hunyuan-standard、hunyuan-embeddingなど'
- },
- minimax: {
- label: 'MiniMax',
- description: 'MiniMax-M3、MiniMax-M2.7、MiniMax-M2.7-highspeedなど'
- },
- mimo: {
- label: 'MiMo',
- description: 'mimo-v2-flash'
- },
- gemini: {
- label: 'Google Gemini',
- description: 'gemini-3-flash-preview、gemini-2.5-proなど'
- },
- gpustack: {
- label: 'GPUStack',
- description: 'GPUStackにデプロイ済みのモデルを選択してください'
- },
- modelscope: {
- label: 'ModelScope',
- description: 'Qwen/Qwen3-8B、Qwen/Qwen3-Embedding-8Bなど'
- },
- qiniu: {
- label: 'Qiniu Cloud',
- description: 'deepseek/deepseek-v3.2-251201、z-ai/glm-4.7など'
- },
- moonshot: {
- label: 'Moonshot',
- description: 'kimi-k2-turbo-preview、moonshot-v1-8k-vision-previewなど'
- },
- qianfan: {
- label: 'Baidu Qianfan',
- description: 'ernie-5.0-thinking-preview、embedding-v1、bce-reranker-baseなど'
- },
- longcat: {
- label: 'LongCat AI',
- description: 'LongCat-Flash-Chat、LongCat-Flash-Thinkingなど'
- },
- lkeap: {
- label: 'Tencent Cloud LKEAP',
- description: 'DeepSeek-R1、DeepSeek-V3、lke-reranker-baseなど'
- },
- nvidia: {
- label: 'NVIDIA',
- description: 'deepseek-ai-deepseek-v3_1、nv-embed-v1、rerank-qa-mistral-4bなど'
- },
- novita: {
- label: 'Novita AI',
- description: 'moonshotai/kimi-k2.5、zai-org/glm-5、minimax/minimax-m2.7、qwen/qwen3-embedding-0.6bなど'
- }
- }
+ providerDocs: '{provider} のモデルドキュメントを見る',
},
builtinTag: '組み込み'
},
@@ -5199,6 +5129,8 @@ export default {
}
},
debug: {
+ reasoningEffort: '思考強度',
+ reasoningEffortDesc: 'モデルカタログが報告するレベルで reasoning_effort を送信します',
title: 'モデルテスト',
description: '保存済みのモデル設定でリクエストを送信します。編集中の変更は保存後に反映されます。',
groupModel: 'モデルを選択',
@@ -5221,15 +5153,11 @@ export default {
audioFile: '音声ファイル',
chooseFile: 'ファイルを選択',
parameters: 'リクエストパラメータ',
- thinking: '思考モード',
- thinkingDesc: '思考に対応したモデルにのみ適用されます',
systemPrompt: 'システムプロンプト',
systemPromptPlaceholder: 'システムプロンプト(任意)',
run: 'テストを実行',
copyResult: '結果をコピー',
history: '履歴',
- thinkOn: '思考オン',
- thinkOff: '思考オフ',
runLabel: '実行 #{n}',
success: 'リクエストに成功しました',
failed: 'リクエストに失敗しました',
@@ -5237,6 +5165,9 @@ export default {
requestPreview: 'リクエストのプレビュー',
requestFailed: 'モデルテストのリクエストに失敗しました',
metrics: {
+ api: 'プロトコル',
+ thinkingFormat: '思考形式',
+ requestedReasoningEffort: '要求した強度',
dimension: '次元数',
resultCount: '結果件数',
answerChars: '回答文字数',
diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts
index 11c6a4b31..5e85677a3 100755
--- a/frontend/src/i18n/locales/ko-KR.ts
+++ b/frontend/src/i18n/locales/ko-KR.ts
@@ -2373,6 +2373,8 @@ export default {
}
},
debug: {
+ reasoningEffort: '사고 강도',
+ reasoningEffortDesc: '모델 카탈로그가 보고한 수준으로 reasoning_effort를 보냅니다',
title: '모델 테스트',
description: '저장된 모델 설정으로 요청을 보냅니다. 편집 중인 변경 사항은 저장 후 반영됩니다.',
groupModel: '모델 선택',
@@ -2395,15 +2397,11 @@ export default {
audioFile: '오디오 파일',
chooseFile: '파일 선택',
parameters: '요청 매개변수',
- thinking: '사고 모드',
- thinkingDesc: '사고 모드를 지원하는 모델에만 적용됩니다',
systemPrompt: 'System Prompt',
systemPromptPlaceholder: '선택 사항, 시스템 프롬프트 입력',
run: '테스트 실행',
copyResult: '결과 복사',
history: '기록',
- thinkOn: '사고 켜짐',
- thinkOff: '사고 꺼짐',
runLabel: '{n}번째 실행',
success: '호출 성공',
failed: '호출 실패',
@@ -2411,6 +2409,9 @@ export default {
requestPreview: '요청 미리보기',
requestFailed: '모델 테스트 요청 실패',
metrics: {
+ api: '프로토콜',
+ thinkingFormat: '사고 형식',
+ requestedReasoningEffort: '요청한 강도',
dimension: '벡터 차원',
resultCount: '결과 수',
answerChars: '답변 문자 수',
@@ -2753,6 +2754,28 @@ export default {
languageSaved: '언어 설정이 저장되었습니다'
},
model: {
+ reasoning: {
+ levels: {
+ off: '끄기',
+ auto: '자동',
+ minimal: '최소',
+ low: '낮음',
+ medium: '중간',
+ high: '높음',
+ xhigh: '매우 높음',
+ max: '최대',
+ },
+ levelDescriptions: {
+ off: '사고를 끄고 사고 파라미터를 보내지 않습니다',
+ auto: '공급사 기본 강도, 사고량은 모델이 결정합니다',
+ minimal: '최소 사고, 가장 빠른 응답',
+ low: '가벼운 사고',
+ medium: '중간 강도 사고',
+ high: '깊은 사고, 응답이 느려집니다',
+ xhigh: '매우 높은 사고 예산(일부 모델만)',
+ max: '최대 사고 예산(일부 모델만)',
+ },
+ },
modelName: '모델 이름',
defaultTag: '기본값',
addModelInSettings: '전역 설정에서 모델 추가하기',
@@ -2761,6 +2784,53 @@ export default {
searchPlaceholder: '모델 검색...',
builtinTag: '내장',
editor: {
+ maxOutputTokensLabel: '최대 출력 토큰',
+ maxOutputTokensPlaceholder: '비워 두면 카탈로그 기본값',
+ maxOutputTokensDesc: '응답 1회의 출력 상한입니다. 비워 두면 이 모델의 카탈로그 기본값을 사용합니다.',
+ catalog: {
+ reasoning: '추론',
+ vision: '비전',
+ hint: '공급사 카탈로그에서 선택하거나 사용자 지정 모델 이름을 입력할 수 있습니다.',
+ },
+ resolved: {
+ title: '실제 호출 방식',
+ empty: '공급사와 모델 이름을 입력하면 이 모델이 어떻게 호출되는지 표시합니다',
+ failed: '해석 실패',
+ protocol: '요청 프로토콜',
+ catalog: '기능 출처',
+ catalogedYes: '내장 모델 프로필',
+ catalogedNo: '공급사 기본값(카탈로그 미수록)',
+ endpoint: '요청 엔드포인트',
+ thinkingFormat: '사고 전환 전달 방식',
+ thinkingLevels: '선택 가능한 사고 강도',
+ noThinking: '이 모델은 사고를 지원하지 않습니다',
+ },
+ advanced: {
+ toggle: '고급',
+ api: {
+ label: '프로토콜 재정의',
+ auto: '자동(공급사 / URL 기준)',
+ desc: '요청 프로토콜을 강제합니다. 일반적으로 변경할 필요가 없습니다.',
+ },
+ remoteModelName: {
+ label: '원격 모델 이름',
+ placeholder: '비워 두면 모델 이름과 동일',
+ desc: '위 모델 이름과 다를 때 실제로 공급사에 보내는 모델 ID입니다.',
+ },
+ legacyThinking: {
+ label: '사고 파라미터 형식(레거시)',
+ catalog: '카탈로그 기본값 따르기(권장)',
+ none: '사고 파라미터를 보내지 않음',
+ desc: '이 모델에는 이전 버전의 thinking_control 설정이 남아 있습니다. "카탈로그 기본값 따르기"를 선택하면 카탈로그가 결정합니다.',
+ },
+ compat: {
+ label: '프로토콜 호환 재정의(JSON)',
+ placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
+ desc: '해석된 프로토콜의 카탈로그 기본값 위에 병합되는 호환 스위치입니다. 백엔드 catalog/compat.go 참조. 비워 두면 재정의하지 않습니다.',
+ invalid: '잘못된 JSON',
+ mustBeObject: 'JSON 객체여야 합니다',
+ },
+ },
addTitle: '모델 추가',
editTitle: '모델 편집',
sectionType: '모델 유형',
@@ -2807,8 +2877,6 @@ export default {
maxConcurrencyLabel: '백그라운드 동시 실행 상한',
maxConcurrencyPlaceholder: '0이면 전역 기본값 사용',
maxConcurrencyDesc: '문서 인덱싱/보강 등 백그라운드 작업이 이 모델을 호출하는 동시 실행 수를 제한합니다(모델별로 모든 복제본이 공유). 0 또는 비워 두면 전역 기본값을 사용하며, 대화형 채팅에는 영향을 주지 않습니다.',
- thinkingControlLabel: '사고 모드 매개변수 형식',
- thinkingControlDesc: '에이전트 「사고 모드」 켜기/끄기 시 API에 어떻게 기록할지 결정합니다. 벤더/모델에 따라 미리 선택되며, 실제 API와 다르면 문서에 맞게 수정하세요. 「전송 안 함」을 선택하면 에이전트 「사고 모드」 스위치가 효과가 없습니다.',
dimensionHint: '모델이 선택되었습니다. "차원 감지" 버튼을 클릭하여 벡터 차원을 자동으로 가져옵니다',
loadModelListFailed: '모델 목록 로드 실패',
listRefreshed: '목록이 새로고침되었습니다',
@@ -2831,113 +2899,9 @@ export default {
goToOllamaSettings: '설정 보기',
providerLabel: '프로바이더',
providerPlaceholder: '모델 프로바이더 선택',
- providers: {
- novita: {
- label: 'Novita AI',
- description: 'moonshotai/kimi-k2.5, zai-org/glm-5, minimax/minimax-m2.7, qwen/qwen3-embedding-0.6b 등'
- },
- nvidia: {
- label: 'NVIDIA',
- description: 'deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.'
- },
- lkeap: {
- label: '텐센트 클라우드 LKEAP',
- description: 'DeepSeek-R1, DeepSeek-V3, lke-reranker-base 등'
- },
- longcat: {
- label: 'LongCat AI',
- description: 'LongCat-Flash-Chat, LongCat-Flash-Thinking, etc.'
- },
- qianfan: {
- label: 'Baidu Qianfan',
- description: 'ernie-5.0-thinking-preview, embedding-v1, bce-reranker-base, etc.'
- },
- moonshot: {
- label: 'Moonshot',
- description: 'kimi-k2-turbo-preview, moonshot-v1-8k-vision-preview, etc.'
- },
- qiniu: {
- label: 'Qiniu Cloud',
- description: 'deepseek/deepseek-v3.2-251201, z-ai/glm-4.7, etc.'
- },
- modelscope: {
- label: 'ModelScope',
- description: 'Qwen/Qwen3-8B, Qwen/Qwen3-Embedding-8B, etc.'
- },
- gpustack: {
- label: 'GPUStack',
- description: 'Choose your deployed model on GPUStack'
- },
- gemini: {
- label: 'Google Gemini',
- description: 'gemini-3-flash-preview, gemini-2.5-pro 등'
- },
- mimo: {
- label: 'MiMo',
- description: 'mimo-v2-flash'
- },
- minimax: {
- label: 'MiniMax',
- description: 'MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed 등'
- },
- hunyuan: {
- label: 'Hunyuan',
- description: 'hunyuan-pro, hunyuan-standard, hunyuan-embedding 등'
- },
- deepseek: {
- label: 'DeepSeek',
- description: 'deepseek-chat, deepseek-reasoner 등'
- },
- volcengine: {
- label: 'Volcengine',
- description: 'doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615 등'
- },
- jina: {
- label: 'Jina',
- description: 'jina-clip-v1, jina-embeddings-v2-base-zh, etc.'
- },
- siliconflow: {
- label: 'SiliconFlow',
- description: 'deepseek-ai/DeepSeek-V3.1 등'
- },
- generic: {
- label: '사용자 정의 (OpenAI 호환)',
- description: 'Generic API endpoint'
- },
- requesty: {
- label: 'Requesty',
- description: 'openai/gpt-4o-mini, anthropic/claude-sonnet-4-5 등'
- },
- openrouter: {
- label: 'OpenRouter',
- description: 'openai/gpt-5.2-chat, google/gemini-3-flash-preview 등'
- },
- litellm: {
- label: 'LiteLLM',
- description: '자체 호스팅 프록시로 OpenAI, Anthropic, Gemini, Bedrock 등 100+ 공급자를 연결합니다. 플레이스홀더 URL을 실제 주소로 바꾸세요. localhost는 SSRF_WHITELIST에 추가해야 합니다.'
- },
- zhipu: {
- label: 'Zhipu BigModel',
- description: 'glm-4.7, embedding-3, rerank, etc.'
- },
- aliyun: {
- label: 'Aliyun DashScope',
- description: 'qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank 등'
- },
- azure_openai: {
- label: 'Azure OpenAI',
- description: 'Microsoft Azure에서 호스팅되는 OpenAI 서비스'
- },
- anthropic: {
- label: 'Anthropic',
- description: 'Claude models via native Anthropic Messages API'
- },
- openai: {
- label: 'OpenAI',
- description: 'gpt-5.2, gpt-5-mini 등'
- }
- },
+ providerDocs: '{provider} 모델 문서 보기',
validation: {
+ extraFieldRequired: '{name}을(를) 입력하세요',
modelNameRequired: '모델 이름을 입력해주세요',
modelNameEmpty: '모델 이름은 비워둘 수 없습니다',
modelNameMax: '모델 이름은 100자를 초과할 수 없습니다',
@@ -2945,41 +2909,6 @@ export default {
baseUrlEmpty: 'Base URL은 비워둘 수 없습니다',
baseUrlInvalid: 'Base URL 형식이 올바르지 않습니다. 유효한 URL을 입력해주세요'
},
- thinkingControl: {
- thinkingType: {
- label: 'thinking.type',
- hint: 'Volcengine Ark; Tencent LKEAP (DeepSeek V3 등, LKEAP 기본값; R1은 「전송 안 함」)'
- },
- enableThinking: {
- label: 'enable_thinking',
- hint: 'Alibaba DashScope: qwen3, qwen-plus, qwen-max, qwen-turbo'
- },
- chatTemplateKwargs: {
- label: 'chat_template_kwargs',
- hint: '사용자 정의 OpenAI 호환, NVIDIA NIM, vLLM / 로컬 Qwen 배포'
- },
- none: {
- label: '사고 매개변수 전송 안 함',
- hint: '에이전트 「사고 모드」 스위치가 효과 없음, 요청에 사고 관련 매개변수를 보내지 않음'
- }
- },
- volcengine: {
- accessKeyLabel: 'Access Key ID',
- accessKeyPlaceholder: 'Volcengine Access Key ID',
- secretKeyLabel: 'Secret Access Key',
- secretKeyPlaceholder: 'Volcengine Secret Access Key',
- rerankCredentialHint: 'Rerank은 Ark API 키가 아닌 VikingDB AK/SK 서명을 사용합니다. 권장 모델: doubao-seed-rerank.'
- },
- lkeap: {
- secretIdLabel: 'SecretId',
- secretIdPlaceholder: 'Tencent Cloud API SecretId',
- secretKeyLabel: 'SecretKey',
- secretKeyPlaceholder: 'Tencent Cloud API SecretKey',
- regionLabel: 'Region',
- regionPlaceholder: 'ap-guangzhou',
- regionDesc: 'RunRerank supports ap-beijing, ap-guangzhou, etc. Default: ap-guangzhou',
- rerankCredentialHint: 'Rerank uses Tencent Cloud API signature (not the OpenAI-style LKEAP API key). Create SecretId/SecretKey in the CAM console.'
- },
modelNamePlaceholder: {
local: '예: llama2:latest',
remote: '예: gpt-4, claude-3-opus',
@@ -6392,6 +6321,8 @@ export default {
capabilityUnconfigured: '미구성'
},
editor: {
+ reasoningEffortUnsupported: '선택한 모델은 사고를 지원하지 않습니다. "끄기" 외의 옵션은 무시됩니다.',
+ reasoningEffortAlwaysOn: '선택한 모델은 항상 사고하며 끌 수 없습니다. 강도만 조정할 수 있습니다.',
createTitle: '에이전트 만들기',
editTitle: '에이전트 편집',
buttons: {
diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts
index 85017f8f3..929d56033 100755
--- a/frontend/src/i18n/locales/ru-RU.ts
+++ b/frontend/src/i18n/locales/ru-RU.ts
@@ -2373,6 +2373,8 @@ export default {
}
},
debug: {
+ reasoningEffort: 'Интенсивность размышлений',
+ reasoningEffortDesc: 'Отправляет reasoning_effort с уровнями, которые сообщает каталог модели',
title: 'Тест модели',
description: 'Запрос с сохранёнными настройками модели. Перед проверкой сохраните изменения.',
groupModel: 'Выбор модели',
@@ -2395,15 +2397,11 @@ export default {
audioFile: 'Аудиофайл',
chooseFile: 'Выбрать файл',
parameters: 'Параметры запроса',
- thinking: 'Режим размышления',
- thinkingDesc: 'Применяется только к моделям с поддержкой размышления',
systemPrompt: 'System Prompt',
systemPromptPlaceholder: 'Необязательно: системный промпт',
run: 'Запустить тест',
copyResult: 'Копировать результат',
history: 'История',
- thinkOn: 'Размышление вкл.',
- thinkOff: 'Размышление выкл.',
runLabel: 'Запуск №{n}',
success: 'Запрос выполнен',
failed: 'Запрос не выполнен',
@@ -2411,6 +2409,9 @@ export default {
requestPreview: 'Просмотр запроса',
requestFailed: 'Не удалось выполнить тест модели',
metrics: {
+ api: 'Протокол',
+ thinkingFormat: 'Формат размышлений',
+ requestedReasoningEffort: 'Запрошенная интенсивность',
dimension: 'Размерность вектора',
resultCount: 'Количество результатов',
answerChars: 'Символов в ответе',
@@ -2753,6 +2754,28 @@ export default {
languageSaved: 'Настройки языка сохранены'
},
model: {
+ reasoning: {
+ levels: {
+ off: 'Выкл',
+ auto: 'Авто',
+ minimal: 'Минимальный',
+ low: 'Низкий',
+ medium: 'Средний',
+ high: 'Высокий',
+ xhigh: 'Очень высокий',
+ max: 'Максимальный',
+ },
+ levelDescriptions: {
+ off: 'Размышления отключены, параметры размышления не отправляются',
+ auto: 'Интенсивность по умолчанию поставщика; модель сама решает, сколько думать',
+ minimal: 'Минимум размышлений, самые быстрые ответы',
+ low: 'Лёгкие размышления',
+ medium: 'Умеренные размышления',
+ high: 'Глубокие размышления, ответы медленнее',
+ xhigh: 'Очень большой бюджет размышлений (только некоторые модели)',
+ max: 'Максимальный бюджет размышлений (только некоторые модели)',
+ },
+ },
modelName: 'Название модели',
defaultTag: 'По умолчанию',
addModelInSettings: 'Перейти в общие настройки для добавления моделей',
@@ -2761,6 +2784,53 @@ export default {
searchPlaceholder: 'Поиск моделей...',
builtinTag: 'Built-in',
editor: {
+ maxOutputTokensLabel: 'Макс. выходных токенов',
+ maxOutputTokensPlaceholder: 'Пусто — значение из каталога',
+ maxOutputTokensDesc: 'Лимит вывода на один ответ. Оставьте пустым, чтобы использовать значение каталога для этой модели.',
+ catalog: {
+ reasoning: 'Рассуждение',
+ vision: 'Зрение',
+ hint: 'Выберите модель из каталога поставщика или введите своё имя модели.',
+ },
+ resolved: {
+ title: 'Как вызывается модель',
+ empty: 'Укажите поставщика и имя модели, чтобы увидеть, как она будет вызвана',
+ failed: 'Не удалось определить',
+ protocol: 'Протокол запроса',
+ catalog: 'Источник возможностей',
+ catalogedYes: 'Встроенный профиль модели',
+ catalogedNo: 'Настройки поставщика (модели нет в каталоге)',
+ endpoint: 'Адрес запроса',
+ thinkingFormat: 'Переключатель размышлений',
+ thinkingLevels: 'Доступная интенсивность',
+ noThinking: 'Модель не умеет размышлять',
+ },
+ advanced: {
+ toggle: 'Дополнительно',
+ api: {
+ label: 'Переопределение протокола',
+ auto: 'Авто (по поставщику / URL)',
+ desc: 'Принудительно задать протокол запросов; обычно не требуется.',
+ },
+ remoteModelName: {
+ label: 'Имя модели у поставщика',
+ placeholder: 'Пусто — совпадает с именем модели',
+ desc: 'ID модели, который реально отправляется поставщику, если отличается от имени выше.',
+ },
+ legacyThinking: {
+ label: 'Формат параметров размышления (устаревший)',
+ catalog: 'Следовать каталогу (рекомендуется)',
+ none: 'Не отправлять параметры размышления',
+ desc: 'У этой модели сохранилась устаревшая настройка thinking_control. Выберите «Следовать каталогу», чтобы решение принимал каталог.',
+ },
+ compat: {
+ label: 'Переопределение совместимости протокола (JSON)',
+ placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
+ desc: 'Переключатели совместимости, накладываемые на значения каталога для определённого протокола; см. catalog/compat.go на бэкенде. Пусто — без переопределения.',
+ invalid: 'Некорректный JSON',
+ mustBeObject: 'Должен быть JSON-объект',
+ },
+ },
addTitle: 'Добавить модель',
editTitle: 'Редактировать модель',
sectionType: 'Тип модели',
@@ -2807,8 +2877,6 @@ export default {
maxConcurrencyLabel: 'Лимит фоновой параллельности',
maxConcurrencyPlaceholder: '0 — использовать глобальное значение',
maxConcurrencyDesc: 'Ограничивает число одновременных фоновых вызовов (индексация/обогащение) к этой модели, общее для модели по всем репликам. 0 или пусто — используется глобальное значение по умолчанию; интерактивный чат не затрагивается.',
- thinkingControlLabel: 'Формат параметров режима размышления',
- thinkingControlDesc: 'Определяет, как переключатель «Режим размышления» агента записывается в API. При возможности выбирается по поставщику/модели; при несоответствии измените по документации API. При выборе «Не отправлять» переключатель «Режим размышления» агента не действует.',
dimensionHint: 'Модель выбрана. Нажмите «Определить размерность», чтобы автоматически получить значение.',
loadModelListFailed: 'Не удалось загрузить список моделей',
listRefreshed: 'Список обновлён',
@@ -2831,113 +2899,9 @@ export default {
goToOllamaSettings: 'Открыть настройки',
providerLabel: 'Провайдер',
providerPlaceholder: 'Выберите провайдера модели',
- providers: {
- novita: {
- label: 'Novita AI',
- description: 'moonshotai/kimi-k2.5, zai-org/glm-5, minimax/minimax-m2.7, qwen/qwen3-embedding-0.6b, etc.'
- },
- nvidia: {
- label: 'NVIDIA',
- description: 'deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.'
- },
- lkeap: {
- label: 'Tencent Cloud LKEAP',
- description: 'DeepSeek-R1, DeepSeek-V3, lke-reranker-base и др.'
- },
- longcat: {
- label: 'LongCat AI',
- description: 'LongCat-Flash-Chat, LongCat-Flash-Thinking, etc.'
- },
- qianfan: {
- label: 'Baidu Qianfan',
- description: 'ernie-5.0-thinking-preview, embedding-v1, bce-reranker-base, etc.'
- },
- moonshot: {
- label: 'Moonshot',
- description: 'kimi-k2-turbo-preview, moonshot-v1-8k-vision-preview, etc.'
- },
- qiniu: {
- label: 'Qiniu Cloud',
- description: 'deepseek/deepseek-v3.2-251201, z-ai/glm-4.7, etc.'
- },
- modelscope: {
- label: 'ModelScope',
- description: 'Qwen/Qwen3-8B, Qwen/Qwen3-Embedding-8B, etc.'
- },
- gpustack: {
- label: 'GPUStack',
- description: 'Choose your deployed model on GPUStack'
- },
- gemini: {
- label: 'Google Gemini',
- description: 'gemini-3-flash-preview, gemini-2.5-pro, etc.'
- },
- mimo: {
- label: 'MiMo',
- description: 'mimo-v2-flash'
- },
- minimax: {
- label: 'MiniMax',
- description: 'MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed, etc.'
- },
- hunyuan: {
- label: 'Hunyuan',
- description: 'hunyuan-pro, hunyuan-standard, hunyuan-embedding, etc.'
- },
- deepseek: {
- label: 'DeepSeek',
- description: 'deepseek-chat, deepseek-reasoner, etc.'
- },
- volcengine: {
- label: 'Volcengine',
- description: 'doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615, etc.'
- },
- jina: {
- label: 'Jina',
- description: 'jina-clip-v1, jina-embeddings-v2-base-zh, etc.'
- },
- siliconflow: {
- label: 'SiliconFlow',
- description: 'deepseek-ai/DeepSeek-V3.1, etc.'
- },
- generic: {
- label: 'Пользовательский (OpenAI-совместимый)',
- description: 'Generic API endpoint'
- },
- requesty: {
- label: 'Requesty',
- description: 'openai/gpt-4o-mini, anthropic/claude-sonnet-4-5, etc.'
- },
- openrouter: {
- label: 'OpenRouter',
- description: 'openai/gpt-5.2-chat, google/gemini-3-flash-preview, etc.'
- },
- litellm: {
- label: 'LiteLLM',
- description: 'Self-hosted прокси к 100+ провайдерам (OpenAI, Anthropic, Gemini, Bedrock и др.). Замените URL-заглушку; localhost нужно добавить в SSRF_WHITELIST.'
- },
- zhipu: {
- label: 'Zhipu BigModel',
- description: 'glm-4.7, embedding-3, rerank, etc.'
- },
- aliyun: {
- label: 'Aliyun DashScope',
- description: 'qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank, etc.'
- },
- azure_openai: {
- label: 'Azure OpenAI',
- description: 'Сервис OpenAI на платформе Microsoft Azure'
- },
- anthropic: {
- label: 'Anthropic',
- description: 'Claude models via native Anthropic Messages API'
- },
- openai: {
- label: 'OpenAI',
- description: 'gpt-5.2, gpt-5-mini, etc.'
- }
- },
+ providerDocs: 'Документация моделей {provider}',
validation: {
+ extraFieldRequired: 'Заполните {name}',
modelNameRequired: 'Введите название модели',
modelNameEmpty: 'Название модели не может быть пустым',
modelNameMax: 'Название модели не может превышать 100 символов',
@@ -2945,41 +2909,6 @@ export default {
baseUrlEmpty: 'Base URL не может быть пустым',
baseUrlInvalid: 'Недопустимый Base URL, введите корректный адрес'
},
- thinkingControl: {
- thinkingType: {
- label: 'thinking.type',
- hint: 'Volcengine Ark; Tencent LKEAP (DeepSeek V3 и др.; по умолчанию для LKEAP; для R1 — «Не отправлять»)'
- },
- enableThinking: {
- label: 'enable_thinking',
- hint: 'Alibaba DashScope: qwen3, qwen-plus, qwen-max, qwen-turbo'
- },
- chatTemplateKwargs: {
- label: 'chat_template_kwargs',
- hint: 'Пользовательские OpenAI-совместимые шлюзы, NVIDIA NIM, vLLM / локальный Qwen'
- },
- none: {
- label: 'Не отправлять параметры размышления',
- hint: 'Переключатель «Режим размышления» агента не действует; параметры размышления не отправляются в запросе'
- }
- },
- volcengine: {
- accessKeyLabel: 'Access Key ID',
- accessKeyPlaceholder: 'Volcengine Access Key ID',
- secretKeyLabel: 'Secret Access Key',
- secretKeyPlaceholder: 'Volcengine Secret Access Key',
- rerankCredentialHint: 'Rerank использует подпись VikingDB AK/SK, а не Ark API key. Рекомендуемая модель: doubao-seed-rerank.'
- },
- lkeap: {
- secretIdLabel: 'SecretId',
- secretIdPlaceholder: 'Tencent Cloud API SecretId',
- secretKeyLabel: 'SecretKey',
- secretKeyPlaceholder: 'Tencent Cloud API SecretKey',
- regionLabel: 'Region',
- regionPlaceholder: 'ap-guangzhou',
- regionDesc: 'RunRerank supports ap-beijing, ap-guangzhou, etc. Default: ap-guangzhou',
- rerankCredentialHint: 'Rerank uses Tencent Cloud API signature (not the OpenAI-style LKEAP API key). Create SecretId/SecretKey in the CAM console.'
- },
modelNamePlaceholder: {
local: 'например: llama2:latest',
remote: 'например: gpt-4, claude-3-opus',
@@ -6392,6 +6321,8 @@ export default {
capabilityUnconfigured: 'Not set'
},
editor: {
+ reasoningEffortUnsupported: 'Выбранная модель не поддерживает размышления; все варианты, кроме «Выкл», игнорируются.',
+ reasoningEffortAlwaysOn: 'Выбранная модель всегда размышляет, её нельзя отключить — можно менять только уровень усилий.',
createTitle: 'Create Agent',
editTitle: 'Edit Agent',
buttons: {
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index e4727925d..05fa62fac 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -2375,6 +2375,8 @@ export default {
}
},
debug: {
+ reasoningEffort: '思考强度',
+ reasoningEffortDesc: '按模型目录上报的等级发送 reasoning_effort',
title: '模型测试',
description: '使用已保存的模型配置发送真实请求;编辑中的修改需保存后才会生效',
groupModel: '选择模型',
@@ -2397,15 +2399,11 @@ export default {
audioFile: '音频文件',
chooseFile: '选择文件',
parameters: '请求参数',
- thinking: '思考模式',
- thinkingDesc: '仅对支持思考模式的模型生效',
systemPrompt: 'System Prompt',
systemPromptPlaceholder: '可选,输入系统提示词',
run: '运行测试',
copyResult: '复制结果',
history: '历史记录',
- thinkOn: '思考开启',
- thinkOff: '思考关闭',
runLabel: '第 {n} 次运行',
success: '调用成功',
failed: '调用失败',
@@ -2413,6 +2411,9 @@ export default {
requestPreview: '请求预览',
requestFailed: '模型测试请求失败',
metrics: {
+ api: '协议',
+ thinkingFormat: '思考格式',
+ requestedReasoningEffort: '请求思考强度',
dimension: '向量维度',
resultCount: '结果数量',
answerChars: '回答字符数',
@@ -2755,6 +2756,28 @@ export default {
languageSaved: '语言设置已保存'
},
model: {
+ reasoning: {
+ levels: {
+ off: '关闭',
+ auto: '自动',
+ minimal: '极低',
+ low: '低',
+ medium: '中',
+ high: '高',
+ xhigh: '极高',
+ max: '最大',
+ },
+ levelDescriptions: {
+ off: '关闭思考,不写入任何思考参数',
+ auto: '厂商默认强度,由模型自行决定思考深度',
+ minimal: '最少思考,响应最快',
+ low: '轻度思考',
+ medium: '中等思考强度',
+ high: '深度思考,响应更慢',
+ xhigh: '超高强度思考(仅部分模型支持)',
+ max: '最大思考预算(仅部分模型支持)',
+ },
+ },
modelName: '模型名称',
defaultTag: '默认',
addModelInSettings: '前往全局设置添加模型',
@@ -2763,6 +2786,53 @@ export default {
searchPlaceholder: '搜索模型...',
builtinTag: '内置',
editor: {
+ maxOutputTokensLabel: '最大输出 tokens',
+ maxOutputTokensPlaceholder: '留空使用目录默认',
+ maxOutputTokensDesc: '单次回复的输出上限。留空则沿用目录中该模型的默认值。',
+ catalog: {
+ reasoning: '推理',
+ vision: '视觉',
+ hint: '可从厂商内置目录选择,也可直接输入自定义模型名。',
+ },
+ resolved: {
+ title: '实际调用方式',
+ empty: '填写厂商与模型名后,这里会显示这个模型将被怎样调用',
+ failed: '解析失败',
+ protocol: '请求协议',
+ catalog: '能力来源',
+ catalogedYes: '内置模型档案',
+ catalogedNo: '厂商通用默认(未收录此模型)',
+ endpoint: '请求地址',
+ thinkingFormat: '思考开关传参',
+ thinkingLevels: '可选思考强度',
+ noThinking: '该模型不支持思考',
+ },
+ advanced: {
+ toggle: '高级',
+ api: {
+ label: '协议覆盖',
+ auto: '自动(按厂商 / URL 推断)',
+ desc: '强制使用指定的请求协议;一般无需修改。',
+ },
+ remoteModelName: {
+ label: '远端模型名',
+ placeholder: '留空与模型名相同',
+ desc: '实际发送给厂商的模型 ID,与上面的模型名不同时填写。',
+ },
+ legacyThinking: {
+ label: '思考参数格式(旧配置)',
+ catalog: '遵循目录默认(推荐)',
+ none: '不写入思考参数',
+ desc: '此模型仍带有旧版 thinking_control 设置。选择「遵循目录默认」后由目录决定思考参数的写法。',
+ },
+ compat: {
+ label: '协议兼容覆盖(JSON)',
+ placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
+ desc: '按协议合并到目录默认值的兼容开关,字段见后端 catalog/compat.go。留空表示不覆盖。',
+ invalid: 'JSON 格式不正确',
+ mustBeObject: '必须是 JSON 对象',
+ },
+ },
addTitle: '添加模型',
editTitle: '编辑模型',
sectionType: '模型类型',
@@ -2809,8 +2879,6 @@ export default {
maxConcurrencyLabel: '后台并发上限',
maxConcurrencyPlaceholder: '0 表示使用全局默认',
maxConcurrencyDesc: '限制文档入库/富化等后台任务对该模型的并发调用数(按模型全副本共享)。0 或留空表示沿用全局默认;不影响交互式对话。',
- thinkingControlLabel: '思考模式参数格式',
- thinkingControlDesc: '决定智能体「思考模式」开/关时如何写入 API。已尝试按厂商/模型预选,若与实际情况不符请按 API 文档手动修改;选「不写入」时,智能体「思考模式」开关不生效。',
dimensionHint: '模型已选择,点击"检测维度"按钮自动获取向量维度',
loadModelListFailed: '加载模型列表失败',
listRefreshed: '列表已刷新',
@@ -2833,113 +2901,9 @@ export default {
goToOllamaSettings: '查看设置',
providerLabel: '服务商',
providerPlaceholder: '选择模型服务商',
- providers: {
- novita: {
- label: 'Novita AI',
- description: 'moonshotai/kimi-k2.5, zai-org/glm-5, minimax/minimax-m2.7, qwen/qwen3-embedding-0.6b 等'
- },
- nvidia: {
- label: 'NVIDIA',
- description: 'deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.'
- },
- lkeap: {
- label: '腾讯云 LKEAP',
- description: 'DeepSeek-R1、DeepSeek-V3、lke-reranker-base 等'
- },
- longcat: {
- label: 'LongCat AI',
- description: 'LongCat-Flash-Chat, LongCat-Flash-Thinking, etc.'
- },
- qianfan: {
- label: '百度千帆 Baidu Cloud',
- description: 'ernie-5.0-thinking-preview, embedding-v1, bce-reranker-base, etc.'
- },
- moonshot: {
- label: '月之暗面 Moonshot',
- description: 'kimi-k2-turbo-preview, moonshot-v1-8k-vision-preview, etc.'
- },
- qiniu: {
- label: '七牛云 Qiniu',
- description: 'deepseek/deepseek-v3.2-251201, z-ai/glm-4.7, etc.'
- },
- modelscope: {
- label: '魔搭 ModelScope',
- description: 'Qwen/Qwen3-8B, Qwen/Qwen3-Embedding-8B, etc.'
- },
- gpustack: {
- label: 'GPUStack',
- description: 'Choose your deployed model on GPUStack'
- },
- gemini: {
- label: 'Google Gemini',
- description: 'gemini-3-flash-preview, gemini-2.5-pro 等'
- },
- mimo: {
- label: '小米 MiMo',
- description: 'mimo-v2-flash'
- },
- minimax: {
- label: 'MiniMax',
- description: 'MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed 等'
- },
- hunyuan: {
- label: '腾讯混元 Hunyuan',
- description: 'hunyuan-pro, hunyuan-standard, hunyuan-embedding, etc.'
- },
- deepseek: {
- label: 'DeepSeek',
- description: 'deepseek-chat, deepseek-reasoner 等'
- },
- volcengine: {
- label: '火山引擎 Volcengine',
- description: 'doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615, etc.'
- },
- jina: {
- label: 'Jina',
- description: 'jina-clip-v1, jina-embeddings-v2-base-zh, etc.'
- },
- siliconflow: {
- label: '硅基流动 SiliconFlow',
- description: 'deepseek-ai/DeepSeek-V3.1, etc.'
- },
- generic: {
- label: '自定义 (OpenAI兼容接口)',
- description: 'Generic API endpoint (OpenAI-compatible)'
- },
- requesty: {
- label: 'Requesty',
- description: 'openai/gpt-4o-mini, anthropic/claude-sonnet-4-5, etc.'
- },
- openrouter: {
- label: 'OpenRouter',
- description: 'openai/gpt-5.2-chat, google/gemini-3-flash-preview, etc.'
- },
- litellm: {
- label: 'LiteLLM',
- description: '自托管代理,统一接入 OpenAI、Anthropic、Gemini、Bedrock 等 100+ 厂商。请将占位 URL 换成可访问地址;localhost 需加入 SSRF_WHITELIST。'
- },
- zhipu: {
- label: '智谱 BigModel',
- description: 'glm-4.7, embedding-3, rerank, etc.'
- },
- aliyun: {
- label: '阿里云 DashScope',
- description: 'qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank, etc.'
- },
- azure_openai: {
- label: 'Azure OpenAI',
- description: 'Microsoft Azure 上的 OpenAI 服务'
- },
- anthropic: {
- label: 'Anthropic',
- description: 'Claude models via native Anthropic Messages API'
- },
- openai: {
- label: 'OpenAI',
- description: 'gpt-5.2, gpt-5-mini, etc.'
- }
- },
+ providerDocs: '查看 {provider} 的模型文档',
validation: {
+ extraFieldRequired: '请填写 {name}',
modelNameRequired: '请输入模型名称',
modelNameEmpty: '模型名称不能为空',
modelNameMax: '模型名称不能超过100个字符',
@@ -2947,41 +2911,6 @@ export default {
baseUrlEmpty: 'Base URL 不能为空',
baseUrlInvalid: 'Base URL 格式不正确,请输入有效的 URL'
},
- thinkingControl: {
- thinkingType: {
- label: 'thinking.type',
- hint: '火山引擎 Ark;腾讯云 LKEAP(DeepSeek V3 等,选 LKEAP 时默认此项;R1 请改「不写入」)'
- },
- enableThinking: {
- label: 'enable_thinking',
- hint: '阿里云 DashScope:qwen3、qwen-plus、qwen-max、qwen-turbo'
- },
- chatTemplateKwargs: {
- label: 'chat_template_kwargs',
- hint: '自定义 OpenAI 兼容、NVIDIA NIM、vLLM / 本地 Qwen 部署'
- },
- none: {
- label: '不写入思考参数',
- hint: '智能体「思考模式」开关不生效,不会在请求中写入思考相关参数'
- }
- },
- volcengine: {
- accessKeyLabel: 'Access Key ID',
- accessKeyPlaceholder: '火山引擎访问密钥 Access Key ID',
- secretKeyLabel: 'Secret Access Key',
- secretKeyPlaceholder: '火山引擎访问密钥 Secret Access Key',
- rerankCredentialHint: 'Rerank 使用 VikingDB AK/SK 签名(非方舟 API Key),模型建议填写 doubao-seed-rerank。'
- },
- lkeap: {
- secretIdLabel: 'SecretId',
- secretIdPlaceholder: '腾讯云 API 密钥 SecretId',
- secretKeyLabel: 'SecretKey',
- secretKeyPlaceholder: '腾讯云 API 密钥 SecretKey',
- regionLabel: '地域',
- regionPlaceholder: 'ap-guangzhou',
- regionDesc: 'RunRerank 支持 ap-beijing、ap-guangzhou 等,默认 ap-guangzhou',
- rerankCredentialHint: 'Rerank 使用腾讯云 API 签名(非 OpenAI API Key)。请在云 API 密钥控制台创建 SecretId/SecretKey。'
- },
modelNamePlaceholder: {
local: '例如:llama2:latest',
remote: '例如:gpt-4, claude-3-opus',
@@ -6394,6 +6323,8 @@ export default {
capabilityUnconfigured: '未配置'
},
editor: {
+ reasoningEffortUnsupported: '当前所选模型不支持思考,除「关闭」外的选项将被忽略。',
+ reasoningEffortAlwaysOn: '当前所选模型始终开启思考,无法关闭,只能调整思考强度。',
createTitle: '创建智能体',
editTitle: '编辑智能体',
buttons: {
diff --git a/frontend/src/stores/modelProviders.ts b/frontend/src/stores/modelProviders.ts
new file mode 100644
index 000000000..f82be5761
--- /dev/null
+++ b/frontend/src/stores/modelProviders.ts
@@ -0,0 +1,105 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+import i18n from '@/i18n'
+import { listModelProviders, type ModelProviderOption } from '@/api/initialization'
+import {
+ loadProvidersForType,
+ mergeProviderIndex,
+ providerDescription,
+ providerIcon,
+ providerLabel,
+} from '@/stores/modelProvidersState'
+
+/**
+ * Vendor catalog cache. Every component that renders a vendor (model
+ * editor, model cards, debug drawer) reads through this store so the
+ * frontend keeps no vendor table or naming heuristics of its own — the
+ * backend catalog (GET /api/v1/models/providers) is the single source.
+ *
+ * Providers are fetched once per model type (the backend filters the
+ * built-in model list by type) and merged into an id index so lookups by
+ * provider id work regardless of which type loaded them first.
+ */
+export const useModelProvidersStore = defineStore('modelProviders', () => {
+ const byType = ref<Record<string, ModelProviderOption[]>>({})
+ const byId = ref<Record<string, ModelProviderOption>>({})
+ const loadingByType = ref<Record<string, boolean>>({})
+ const pending = new Map<string, Promise<ModelProviderOption[]>>()
+
+ const currentLocale = computed(() => String(i18n.global.locale.value || ''))
+
+ const normalizeType = (modelType?: string) => (modelType || '').trim().toLowerCase()
+
+ /**
+ * Load providers for one model type (once); concurrent callers share the
+ * request. Never rejects: a failed fetch resolves to [] and is NOT cached,
+ * so the next component to mount retries instead of rendering an empty
+ * vendor dropdown for the rest of the session.
+ */
+ const ensureLoaded = async (modelType?: string, force = false): Promise<ModelProviderOption[]> => {
+ const key = normalizeType(modelType)
+ if (!force && byType.value[key]) return byType.value[key]
+ const inflight = pending.get(key)
+ if (inflight && !force) return inflight
+
+ const request = (async () => {
+ loadingByType.value = { ...loadingByType.value, [key]: true }
+ try {
+ const { providers, cacheable } = await loadProvidersForType(listModelProviders, key)
+ if (!cacheable) return providers
+ byType.value = { ...byType.value, [key]: providers }
+ byId.value = mergeProviderIndex(byId.value, providers)
+ return providers
+ } finally {
+ loadingByType.value = { ...loadingByType.value, [key]: false }
+ }
+ })()
+ pending.set(key, request)
+ // Only drop our own entry: a concurrent force-reload may have replaced it.
+ void request.finally(() => {
+ if (pending.get(key) === request) pending.delete(key)
+ })
+ return request
+ }
+
+ const providersFor = (modelType?: string): ModelProviderOption[] => byType.value[normalizeType(modelType)] || []
+
+ const isLoading = (modelType?: string): boolean => !!loadingByType.value[normalizeType(modelType)]
+
+ const providerById = (id?: string | null): ModelProviderOption | undefined => {
+ if (!id) return undefined
+ return byId.value[id]
+ }
+
+ const iconFor = (id?: string | null): string => providerIcon(providerById(id))
+
+ const labelFor = (id?: string | null, locale?: string): string => {
+ const provider = providerById(id)
+ if (!provider) return id || ''
+ return providerLabel(provider, locale ?? currentLocale.value)
+ }
+
+ const descriptionFor = (id?: string | null, locale?: string): string =>
+ providerDescription(providerById(id), locale ?? currentLocale.value)
+
+ const reset = () => {
+ byType.value = {}
+ byId.value = {}
+ loadingByType.value = {}
+ pending.clear()
+ }
+
+ return {
+ byType,
+ byId,
+ currentLocale,
+ ensureLoaded,
+ providersFor,
+ isLoading,
+ providerById,
+ iconFor,
+ labelFor,
+ descriptionFor,
+ reset,
+ }
+})
diff --git a/frontend/src/stores/modelProvidersState.test.ts b/frontend/src/stores/modelProvidersState.test.ts
new file mode 100644
index 000000000..3e8e5dd0e
--- /dev/null
+++ b/frontend/src/stores/modelProvidersState.test.ts
@@ -0,0 +1,224 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import type { ModelProviderOption } from '@/api/initialization'
+
+import {
+ credentialLabelForModelType,
+ extraFieldLabel,
+ extraFieldsForModelType,
+ loadProvidersForType,
+ mergeProviderIndex,
+ normalizeModelType,
+ pickLocalized,
+ providerDescription,
+ providerIcon,
+ providerLabel,
+ sortProviders,
+} from './modelProvidersState.ts'
+
+/** loadProvidersForType logs failures; keep the test output readable. */
+async function withoutConsoleError<T>(run: () => Promise<T>): Promise<T> {
+ const original = console.error
+ console.error = () => {}
+ try {
+ return await run()
+ } finally {
+ console.error = original
+ }
+}
+
+const svgIcon = 'data:image/svg+xml;base64,PHN2Zy8+'
+
+function provider(overrides: Partial<ModelProviderOption> & Pick<ModelProviderOption, 'value'>): ModelProviderOption {
+ return {
+ label: overrides.value,
+ description: '',
+ defaultUrls: {},
+ modelTypes: ['chat'],
+ ...overrides,
+ }
+}
+
+test('providerLabel uses labels[locale], then the same language, then label', () => {
+ const lkeap = provider({
+ value: 'lkeap',
+ label: 'Tencent Cloud LKEAP',
+ labels: { 'zh-CN': '腾讯云 LKEAP' },
+ })
+ assert.equal(providerLabel(lkeap, 'zh-CN'), '腾讯云 LKEAP')
+ assert.equal(providerLabel(lkeap, 'zh-TW'), '腾讯云 LKEAP', 'language match without exact region')
+ assert.equal(providerLabel(lkeap, 'en-US'), 'Tencent Cloud LKEAP')
+ assert.equal(providerLabel(lkeap, 'ja-JP'), 'Tencent Cloud LKEAP')
+ assert.equal(providerLabel(lkeap), 'Tencent Cloud LKEAP')
+ assert.equal(providerLabel(null, 'zh-CN'), '')
+})
+
+test('providerLabel falls back to the id when the vendor ships no label', () => {
+ assert.equal(providerLabel(provider({ value: 'custom', label: '' }), 'en-US'), 'custom')
+})
+
+test('pickLocalized ignores empty localized strings', () => {
+ assert.equal(pickLocalized({ 'zh-CN': ' ' }, 'zh-CN', 'fallback'), 'fallback')
+ assert.equal(pickLocalized(undefined, 'zh-CN', 'fallback'), 'fallback')
+ assert.equal(pickLocalized({ 'zh-CN': 'x' }, undefined, 'fallback'), 'fallback')
+})
+
+test('providerDescription mirrors the label lookup', () => {
+ const p = provider({ value: 'x', description: 'gpt-4o, o3', descriptions: { 'zh-CN': 'gpt-4o、o3 等' } })
+ assert.equal(providerDescription(p, 'zh-CN'), 'gpt-4o、o3 等')
+ assert.equal(providerDescription(p, 'ru-RU'), 'gpt-4o, o3')
+})
+
+test('providerIcon only accepts data image URIs', () => {
+ assert.equal(providerIcon(provider({ value: 'a', icon: svgIcon })), svgIcon)
+ assert.equal(providerIcon(provider({ value: 'b' })), '')
+ assert.equal(providerIcon(provider({ value: 'c', icon: 'https://evil.example/x.svg' })), '')
+ assert.equal(providerIcon(undefined), '')
+})
+
+test('extraFieldsForModelType honours model_types in either naming scheme', () => {
+ const fields = [
+ { key: 'api_version', label: 'API Version', type: 'string' },
+ { key: 'secret_key', label: 'Secret Key', type: 'password', model_types: ['Rerank'], secret: true },
+ { key: 'region', label: 'Region', type: 'string', model_types: ['rerank'] },
+ { key: '', label: 'broken', type: 'string' },
+ ]
+ assert.deepEqual(extraFieldsForModelType(fields, 'rerank').map((f) => f.key), ['api_version', 'secret_key', 'region'])
+ assert.deepEqual(extraFieldsForModelType(fields, 'chat').map((f) => f.key), ['api_version'])
+ assert.deepEqual(extraFieldsForModelType(fields, 'KnowledgeQA').map((f) => f.key), ['api_version'])
+ assert.deepEqual(extraFieldsForModelType(undefined, 'chat'), [])
+})
+
+test('normalizeModelType maps backend names onto editor names', () => {
+ assert.equal(normalizeModelType('KnowledgeQA'), 'chat')
+ assert.equal(normalizeModelType('VLLM'), 'vllm')
+ assert.equal(normalizeModelType('embedding'), 'embedding')
+ assert.equal(normalizeModelType(''), '')
+})
+
+test('extraFieldLabel localizes with the same fallback chain', () => {
+ const field = { key: 'region', label: 'Region', labels: { 'zh-CN': '地域' }, type: 'string' }
+ assert.equal(extraFieldLabel(field, 'zh-CN'), '地域')
+ assert.equal(extraFieldLabel(field, 'en-US'), 'Region')
+ assert.equal(extraFieldLabel({ key: 'k', label: '', type: 'string' }), 'k')
+})
+
+test('sortProviders orders by backend order then label', () => {
+ const sorted = sortProviders([
+ provider({ value: 'generic', label: 'Custom', order: 99 }),
+ provider({ value: 'openai', label: 'OpenAI', order: 30 }),
+ provider({ value: 'zeta', label: 'Zeta' }),
+ provider({ value: 'aliyun', label: 'Aliyun', order: 30 }),
+ ])
+ assert.deepEqual(sorted.map((p) => p.value), ['aliyun', 'openai', 'generic', 'zeta'])
+})
+
+test('sortProviders survives rows with neither label nor value', () => {
+ const sorted = sortProviders([
+ { description: '', defaultUrls: {}, modelTypes: [] } as unknown as ModelProviderOption,
+ provider({ value: 'openai', label: 'OpenAI' }),
+ ])
+ assert.equal(sorted.length, 2)
+})
+
+test('loadProvidersForType caches a successful list, sorted and id-filtered', async () => {
+ const seen: Array<string | undefined> = []
+ const result = await loadProvidersForType(async (type) => {
+ seen.push(type)
+ return [
+ provider({ value: 'zeta', label: 'Zeta' }),
+ { value: '', label: 'broken' },
+ null,
+ provider({ value: 'openai', label: 'OpenAI', order: 1 }),
+ ]
+ }, 'chat')
+ assert.deepEqual(seen, ['chat'])
+ assert.equal(result.cacheable, true)
+ assert.deepEqual(result.providers.map((p) => p.value), ['openai', 'zeta'])
+})
+
+test('loadProvidersForType passes undefined for the all-types key', async () => {
+ const seen: Array<string | undefined> = []
+ await loadProvidersForType(async (type) => { seen.push(type); return [] }, '')
+ assert.deepEqual(seen, [undefined])
+})
+
+test('loadProvidersForType caches a genuinely empty catalog', async () => {
+ const result = await loadProvidersForType(async () => [], 'rerank')
+ assert.deepEqual(result, { providers: [], cacheable: true })
+})
+
+test('loadProvidersForType never caches a failed or malformed response', async () => {
+ await withoutConsoleError(async () => {
+ const failed = await loadProvidersForType(async () => { throw new Error('502') }, 'chat')
+ assert.deepEqual(failed, { providers: [], cacheable: false }, 'a transient failure must be retried')
+ })
+ for (const malformed of [null, undefined, { data: [] }, 'nope']) {
+ const result = await loadProvidersForType(async () => malformed, 'chat')
+ assert.deepEqual(result, { providers: [], cacheable: false })
+ }
+})
+
+test('mergeProviderIndex keeps catalog models collected across model types', () => {
+ const chat = provider({ value: 'openai', models: [{ id: 'gpt-4o', name: 'GPT-4o', type: 'chat' }] })
+ const embedding = provider({
+ value: 'openai',
+ models: [
+ { id: 'text-embedding-3-large', name: 'Embedding 3 Large', type: 'embedding' },
+ { id: 'gpt-4o', name: 'GPT-4o', type: 'chat' },
+ ],
+ })
+ const index = mergeProviderIndex(mergeProviderIndex({}, [chat]), [embedding])
+ assert.deepEqual(index.openai.models?.map((m) => m.id), ['gpt-4o', 'text-embedding-3-large'])
+ assert.equal(Object.keys(index).length, 1)
+})
+
+test('mergeProviderIndex tolerates missing values and model lists', () => {
+ const base = mergeProviderIndex({}, [
+ provider({ value: 'openai' }),
+ { label: 'no id' } as unknown as ModelProviderOption,
+ ])
+ assert.deepEqual(Object.keys(base), ['openai'])
+ // A later fetch without `models` must not wipe what an earlier one collected.
+ const withModels = mergeProviderIndex(
+ mergeProviderIndex({}, [provider({ value: 'openai', models: [{ id: 'gpt-4o', name: 'GPT-4o', type: 'chat' }] })]),
+ [provider({ value: 'openai', label: 'OpenAI' })],
+ )
+ assert.deepEqual(withModels.openai.models?.map((m) => m.id), ['gpt-4o'])
+ assert.equal(withModels.openai.label, 'OpenAI', 'fresh metadata still wins')
+})
+
+test('credentialLabelForModelType follows the vendor declaration, not a hardcoded table', () => {
+ const labels = [
+ {
+ label: 'SecretId',
+ labels: { 'zh-CN': 'SecretId(TC3 签名)' },
+ placeholder: 'AKID...',
+ hint: 'not an sk- key',
+ model_types: ['Rerank'],
+ required: true,
+ },
+ ]
+ // The signed rerank API renames the field; chat on the same vendor does not.
+ const rerank = credentialLabelForModelType(labels, 'rerank')
+ assert.equal(rerank?.label, 'SecretId')
+ assert.equal(rerank?.required, true)
+ assert.equal(credentialLabelForModelType(labels, 'chat'), null)
+ assert.equal(credentialLabelForModelType(labels, 'embedding'), null)
+
+ // Backend spelling of the model type resolves the same way.
+ assert.equal(credentialLabelForModelType(labels, 'Rerank')?.label, 'SecretId')
+
+ // Vendors that take a plain API key declare nothing.
+ assert.equal(credentialLabelForModelType(undefined, 'rerank'), null)
+ assert.equal(credentialLabelForModelType([], 'rerank'), null)
+
+ // An entry without a model_types filter applies to every type.
+ const everywhere = [{ label: 'Access Key' }]
+ assert.equal(credentialLabelForModelType(everywhere, 'chat')?.label, 'Access Key')
+
+ // Localization goes through the same picker as every other vendor string.
+ assert.equal(pickLocalized(rerank?.labels, 'zh-CN', rerank!.label), 'SecretId(TC3 签名)')
+ assert.equal(pickLocalized(rerank?.labels, 'en-US', rerank!.label), 'SecretId')
+})
diff --git a/frontend/src/stores/modelProvidersState.ts b/frontend/src/stores/modelProvidersState.ts
new file mode 100644
index 000000000..2e0acc39a
--- /dev/null
+++ b/frontend/src/stores/modelProvidersState.ts
@@ -0,0 +1,166 @@
+/**
+ * Pure helpers behind the modelProviders store. Kept free of Pinia / API
+ * imports so they can be unit-tested under node:test.
+ *
+ * Every vendor fact the UI renders (name, description, icon, extra fields,
+ * catalog models) comes from the backend catalog (internal/handler/
+ * model_catalog.go); these helpers only pick the right locale / model type.
+ */
+import type {
+ ModelProviderCredentialLabel,
+ ModelProviderExtraField,
+ ModelProviderOption,
+} from '@/api/initialization'
+
+/** Editor model types → backend ModelType names used by ExtraField.model_types. */
+const FRONTEND_TO_BACKEND_MODEL_TYPE: Record<string, string> = {
+ chat: 'KnowledgeQA',
+ embedding: 'Embedding',
+ rerank: 'Rerank',
+ vllm: 'VLLM',
+ asr: 'ASR',
+}
+
+const BACKEND_TO_FRONTEND_MODEL_TYPE: Record<string, string> = Object.fromEntries(
+ Object.entries(FRONTEND_TO_BACKEND_MODEL_TYPE).map(([front, back]) => [back, front]),
+)
+
+/** Normalize either naming ("chat" / "KnowledgeQA") to the editor's lowercase form. */
+export function normalizeModelType(type: string | null | undefined): string {
+ if (!type) return ''
+ const trimmed = String(type).trim()
+ if (FRONTEND_TO_BACKEND_MODEL_TYPE[trimmed]) return trimmed
+ return BACKEND_TO_FRONTEND_MODEL_TYPE[trimmed] || trimmed.toLowerCase()
+}
+
+/** Whether a field's model_types filter admits the given editor model type. */
+export function extraFieldAppliesTo(field: Pick<ModelProviderExtraField, 'model_types'>, modelType: string): boolean {
+ const restricted = field.model_types
+ if (!restricted || restricted.length === 0) return true
+ const wanted = normalizeModelType(modelType)
+ return restricted.some((entry) => normalizeModelType(entry) === wanted)
+}
+
+/** Extra fields to render for a provider at one model type. */
+export function extraFieldsForModelType(
+ fields: ReadonlyArray<ModelProviderExtraField> | null | undefined,
+ modelType: string,
+): ModelProviderExtraField[] {
+ if (!fields || fields.length === 0) return []
+ return fields.filter((field) => !!field?.key && extraFieldAppliesTo(field, modelType))
+}
+
+/**
+ * The credential naming to use at one model type, or null when the vendor
+ * takes a plain API key. First match wins, and an entry without a
+ * `model_types` filter applies everywhere — same rule as extra fields.
+ */
+export function credentialLabelForModelType(
+ labels: ReadonlyArray<ModelProviderCredentialLabel> | null | undefined,
+ modelType: string,
+): ModelProviderCredentialLabel | null {
+ if (!labels || labels.length === 0) return null
+ return labels.find((label) => !!label?.label && extraFieldAppliesTo(label, modelType)) || null
+}
+
+/**
+ * Pick a localized string from a `labels`-style map.
+ *
+ * Order: exact locale (`zh-CN`) → same language with any region (`zh-*`) →
+ * the plain fallback. Empty strings never win.
+ */
+export function pickLocalized(
+ localized: Record<string, string> | null | undefined,
+ locale: string | null | undefined,
+ fallback: string,
+): string {
+ if (localized && locale) {
+ const exact = localized[locale]
+ if (typeof exact === 'string' && exact.trim()) return exact
+ const language = locale.split(/[-_]/)[0]?.toLowerCase()
+ if (language) {
+ for (const [key, value] of Object.entries(localized)) {
+ if (key.split(/[-_]/)[0]?.toLowerCase() === language && typeof value === 'string' && value.trim()) {
+ return value
+ }
+ }
+ }
+ }
+ return fallback
+}
+
+export function providerLabel(provider: ModelProviderOption | null | undefined, locale?: string): string {
+ if (!provider) return ''
+ return pickLocalized(provider.labels, locale, provider.label || provider.value || '')
+}
+
+export function providerDescription(provider: ModelProviderOption | null | undefined, locale?: string): string {
+ if (!provider) return ''
+ return pickLocalized(provider.descriptions, locale, provider.description || '')
+}
+
+/** `<img src>`-ready icon, or '' when the vendor ships none. */
+export function providerIcon(provider: ModelProviderOption | null | undefined): string {
+ const icon = provider?.icon
+ return typeof icon === 'string' && icon.startsWith('data:image/') ? icon : ''
+}
+
+export function extraFieldLabel(field: ModelProviderExtraField, locale?: string): string {
+ return pickLocalized(field.labels, locale, field.label || field.key)
+}
+
+/** Stable display order: backend `order`, then label. */
+export function sortProviders(providers: ReadonlyArray<ModelProviderOption>): ModelProviderOption[] {
+ return [...providers].sort((a, b) => {
+ const orderA = typeof a.order === 'number' ? a.order : Number.MAX_SAFE_INTEGER
+ const orderB = typeof b.order === 'number' ? b.order : Number.MAX_SAFE_INTEGER
+ if (orderA !== orderB) return orderA - orderB
+ return String(a.label || a.value || '').localeCompare(String(b.label || b.value || ''))
+ })
+}
+
+/**
+ * Fetch + normalize the vendor list for one model type.
+ *
+ * `cacheable` is false for a failed or malformed response so the caller keeps
+ * no cache entry and the next component to mount retries; caching a transient
+ * failure would blank the vendor dropdown for the rest of the session.
+ * An empty-but-valid list IS cacheable — that is a real answer.
+ */
+export async function loadProvidersForType(
+ fetcher: (modelType?: string) => Promise<unknown>,
+ modelType: string,
+): Promise<{ providers: ModelProviderOption[]; cacheable: boolean }> {
+ try {
+ const raw = await fetcher(modelType || undefined)
+ if (!Array.isArray(raw)) return { providers: [], cacheable: false }
+ const providers = (raw as ModelProviderOption[]).filter((p) => !!p && typeof p.value === 'string' && !!p.value)
+ return { providers: sortProviders(providers), cacheable: true }
+ } catch (error) {
+ console.error('Failed to load model providers', error)
+ return { providers: [], cacheable: false }
+ }
+}
+
+/** Merge a freshly fetched list into the id index without dropping models seen for other types. */
+export function mergeProviderIndex(
+ index: Record<string, ModelProviderOption>,
+ providers: ReadonlyArray<ModelProviderOption>,
+): Record<string, ModelProviderOption> {
+ const next = { ...index }
+ for (const provider of providers) {
+ if (!provider?.value) continue
+ const existing = next[provider.value]
+ if (!existing) {
+ next[provider.value] = provider
+ continue
+ }
+ const seen = new Set((existing.models || []).filter((model) => !!model?.id).map((model) => model.id))
+ const mergedModels = [
+ ...(existing.models || []),
+ ...(provider.models || []).filter((model) => !!model?.id && !seen.has(model.id)),
+ ]
+ next[provider.value] = { ...existing, ...provider, models: mergedModels }
+ }
+ return next
+}
diff --git a/frontend/src/utils/reasoningEffort.test.ts b/frontend/src/utils/reasoningEffort.test.ts
new file mode 100644
index 000000000..c1821327b
--- /dev/null
+++ b/frontend/src/utils/reasoningEffort.test.ts
@@ -0,0 +1,113 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+ FALLBACK_REASONING_LEVELS,
+ canonicalLevels,
+ clampLevel,
+ levelDescriptionKey,
+ levelEnablesThinking,
+ levelFromLegacy,
+ levelLabelKey,
+ modelCanThink,
+ modelCannotDisableThinking,
+ optionsFor,
+ supportedLevels,
+} from './reasoningEffort.ts'
+
+test('levelFromLegacy maps the boolean when no effort is stored', () => {
+ assert.equal(levelFromLegacy(true), 'auto')
+ assert.equal(levelFromLegacy(false), 'off')
+ assert.equal(levelFromLegacy(undefined), 'off')
+ assert.equal(levelFromLegacy(null, ''), 'off')
+ assert.equal(levelFromLegacy(true, ' '), 'auto')
+})
+
+test('levelFromLegacy prefers a valid effort over the boolean', () => {
+ assert.equal(levelFromLegacy(false, 'high'), 'high')
+ assert.equal(levelFromLegacy(true, 'off'), 'off')
+ assert.equal(levelFromLegacy(true, ' Medium '), 'medium')
+ assert.equal(levelFromLegacy(true, 'bogus'), 'auto', 'unknown effort falls back to the boolean')
+ assert.equal(levelFromLegacy(false, 'bogus'), 'off')
+})
+
+test('levelLabelKey and levelDescriptionKey point at the model.reasoning namespace', () => {
+ assert.equal(levelLabelKey('xhigh'), 'model.reasoning.levels.xhigh')
+ assert.equal(levelDescriptionKey('auto'), 'model.reasoning.levelDescriptions.auto')
+})
+
+test('levelEnablesThinking treats everything but off as enabled', () => {
+ assert.equal(levelEnablesThinking('off'), false)
+ assert.equal(levelEnablesThinking(''), false)
+ assert.equal(levelEnablesThinking(undefined), false)
+ assert.equal(levelEnablesThinking('auto'), true)
+ assert.equal(levelEnablesThinking('max'), true)
+})
+
+test('optionsFor offers the generic ladder without capabilities', () => {
+ assert.deepEqual(optionsFor(undefined), FALLBACK_REASONING_LEVELS)
+ assert.deepEqual(optionsFor(null), FALLBACK_REASONING_LEVELS)
+ assert.deepEqual(optionsFor({}), FALLBACK_REASONING_LEVELS)
+ assert.notEqual(optionsFor(undefined), FALLBACK_REASONING_LEVELS, 'callers get a fresh array')
+})
+
+test('optionsFor follows thinking_levels exactly, in ladder order', () => {
+ assert.deepEqual(optionsFor({ thinking_levels: ['high', 'low', 'medium'] }), ['low', 'medium', 'high'])
+ assert.deepEqual(optionsFor({ thinking_levels: ['auto', 'off'] }), ['off', 'auto'])
+ assert.deepEqual(optionsFor({ thinking_levels: ['max', 'weird', 'xhigh'] }), ['xhigh', 'max'])
+})
+
+test('optionsFor never offers off for an always-on reasoning model', () => {
+ // deepseek-reasoner / qwq-plus / gemini-3: the catalog maps `off` to null,
+ // so the backend cannot switch thinking off for them.
+ const alwaysOn = { thinking_levels: ['auto', 'minimal', 'low', 'medium', 'high'] }
+ assert.equal(optionsFor(alwaysOn).includes('off'), false)
+ assert.deepEqual(optionsFor(alwaysOn), ['auto', 'minimal', 'low', 'medium', 'high'])
+})
+
+test('optionsFor shows a lone off for a model that cannot think', () => {
+ assert.deepEqual(optionsFor({ thinking_levels: [] }), ['off'])
+ assert.deepEqual(optionsFor({ thinking_levels: ['nonsense'] }), ['off'])
+})
+
+test('modelCannotDisableThinking only fires for models with levels but no off', () => {
+ assert.equal(modelCannotDisableThinking({ thinking_levels: ['auto', 'high'] }), true)
+ assert.equal(modelCannotDisableThinking({ thinking_levels: ['off', 'auto'] }), false)
+ assert.equal(modelCannotDisableThinking({ thinking_levels: [] }), false)
+ assert.equal(modelCannotDisableThinking({}), false, 'no capabilities → nothing to claim')
+ assert.equal(modelCannotDisableThinking(undefined), false)
+ assert.equal(modelCannotDisableThinking(null), false)
+})
+
+test('clampLevel rescues a stored off when the model cannot be switched off', () => {
+ const alwaysOn = optionsFor({ thinking_levels: ['auto', 'low', 'high'] })
+ assert.equal(clampLevel('off', alwaysOn), 'auto')
+ assert.equal(clampLevel('medium', alwaysOn), 'auto')
+ assert.equal(clampLevel('high', alwaysOn), 'high')
+ // …and a stored graded level collapses to off for a model that cannot think.
+ assert.equal(clampLevel('high', optionsFor({ thinking_levels: [] })), 'off')
+})
+
+test('supportedLevels and modelCanThink reflect thinking_levels exactly', () => {
+ assert.deepEqual(supportedLevels({ thinking_levels: ['medium', 'off', 'low'] }), ['off', 'low', 'medium'])
+ assert.deepEqual(supportedLevels({ thinking_levels: [] }), [])
+ assert.deepEqual(supportedLevels(undefined), [])
+ assert.equal(modelCanThink({ thinking_levels: ['auto'] }), true)
+ assert.equal(modelCanThink({ thinking_levels: [] }), false)
+ assert.equal(modelCanThink(undefined), false)
+})
+
+test('canonicalLevels normalizes case, drops duplicates and unknown values', () => {
+ assert.deepEqual(canonicalLevels(['HIGH', 'high', 'nope', ' low ']), ['low', 'high'])
+ assert.deepEqual(canonicalLevels(null), [])
+})
+
+test('clampLevel keeps supported values and degrades gracefully', () => {
+ const options = ['off', 'auto', 'low', 'high'] as const
+ assert.equal(clampLevel('high', options), 'high')
+ assert.equal(clampLevel('medium', options), 'auto', 'unsupported graded level falls back to auto')
+ assert.equal(clampLevel('', options), 'off')
+ assert.equal(clampLevel(undefined, options), 'off')
+ assert.equal(clampLevel('medium', ['low', 'high']), 'low', 'no off/auto → first supported')
+ assert.equal(clampLevel('medium', []), 'off')
+})
diff --git a/frontend/src/utils/reasoningEffort.ts b/frontend/src/utils/reasoningEffort.ts
new file mode 100644
index 000000000..25f79a697
--- /dev/null
+++ b/frontend/src/utils/reasoningEffort.ts
@@ -0,0 +1,125 @@
+/**
+ * Reasoning-effort helpers shared by the agent editor, the model debug
+ * drawer and the model editor.
+ *
+ * Mirrors internal/models/api.ReasoningEffort: a protocol-neutral thinking
+ * level that vendors map onto their own knobs. `off` disables thinking,
+ * `auto` lets the vendor pick its default intensity, and the graded ladder
+ * (minimal ... max) is clamped by the backend to what the model supports.
+ *
+ * Legacy boolean semantics: `thinking: true` == `auto`, `thinking: false` == `off`.
+ */
+
+export const REASONING_LEVELS = [
+ 'off',
+ 'auto',
+ 'minimal',
+ 'low',
+ 'medium',
+ 'high',
+ 'xhigh',
+ 'max',
+] as const
+
+export type ReasoningLevel = (typeof REASONING_LEVELS)[number]
+
+/** Offered when the selected model has no catalog capabilities yet. */
+export const FALLBACK_REASONING_LEVELS: ReasoningLevel[] = ['off', 'auto', 'low', 'medium', 'high']
+
+/** Minimal shape of the backend `capabilities` object we rely on here. */
+export interface ThinkingCapabilities {
+ thinking_levels?: ReadonlyArray<string> | null
+}
+
+export function isReasoningLevel(value: unknown): value is ReasoningLevel {
+ return typeof value === 'string' && (REASONING_LEVELS as ReadonlyArray<string>).includes(value)
+}
+
+/** Sort levels into the canonical ladder order, dropping unknown values and duplicates. */
+export function canonicalLevels(levels: ReadonlyArray<string> | null | undefined): ReasoningLevel[] {
+ if (!levels || levels.length === 0) return []
+ const wanted = new Set(levels.map((level) => String(level).trim().toLowerCase()))
+ return REASONING_LEVELS.filter((level) => wanted.has(level))
+}
+
+/**
+ * Derive the graded level from a config that may carry only the legacy
+ * boolean. A valid `effort` always wins; otherwise `true` → `auto`,
+ * anything else → `off`.
+ */
+export function levelFromLegacy(thinking?: boolean | null, effort?: string | null): ReasoningLevel {
+ const normalized = typeof effort === 'string' ? effort.trim().toLowerCase() : ''
+ if (isReasoningLevel(normalized)) return normalized
+ return thinking === true ? 'auto' : 'off'
+}
+
+/** Whether a level asks the model to think at all. */
+export function levelEnablesThinking(level: string | null | undefined): boolean {
+ return !!level && level !== 'off'
+}
+
+/** i18n key of a level's short name. */
+export function levelLabelKey(level: string): string {
+ return `model.reasoning.levels.${level}`
+}
+
+/** i18n key of a level's one-line description. */
+export function levelDescriptionKey(level: string): string {
+ return `model.reasoning.levelDescriptions.${level}`
+}
+
+/** Whether the model can be asked to think (non-empty thinking_levels). */
+export function modelCanThink(capabilities?: ThinkingCapabilities | null): boolean {
+ return (capabilities?.thinking_levels?.length ?? 0) > 0
+}
+
+/**
+ * Levels the model itself reports, in ladder order. Empty when the model
+ * cannot think (or no capabilities are known).
+ */
+export function supportedLevels(capabilities?: ThinkingCapabilities | null): ReasoningLevel[] {
+ return canonicalLevels(capabilities?.thinking_levels)
+}
+
+/**
+ * Options for a reasoning-level selector.
+ *
+ * When the model reports capabilities, `thinking_levels` is authoritative and
+ * is followed EXACTLY — including the absence of `off`. Always-on reasoning
+ * models (deepseek-reasoner, qwq-plus, the gemini-3 family, ...) map `off` to
+ * null in the catalog, so offering "关闭" there would promise something the
+ * backend cannot deliver: no switch is sent and the model thinks anyway.
+ *
+ * With no capabilities at all (model list not loaded, local/Ollama model, ...)
+ * the generic off/auto/low/medium/high ladder is offered so the user can still
+ * express a preference; the backend clamps it later.
+ */
+export function optionsFor(capabilities?: ThinkingCapabilities | null): ReasoningLevel[] {
+ if (!capabilities || !Array.isArray(capabilities.thinking_levels)) {
+ return [...FALLBACK_REASONING_LEVELS]
+ }
+ const levels = canonicalLevels(capabilities.thinking_levels)
+ // A model that cannot think at all still needs one truthful value to show.
+ return levels.length > 0 ? levels : ['off']
+}
+
+/**
+ * Whether the model reports capabilities but cannot be switched off — the UI
+ * must say so, otherwise the absence of a "关闭" option looks like a bug.
+ */
+export function modelCannotDisableThinking(capabilities?: ThinkingCapabilities | null): boolean {
+ if (!capabilities || !Array.isArray(capabilities.thinking_levels)) return false
+ const levels = canonicalLevels(capabilities.thinking_levels)
+ return levels.length > 0 && !levels.includes('off')
+}
+
+/** Pick a level to show for a selector whose current value may be unsupported. */
+export function clampLevel(level: string | null | undefined, options: ReadonlyArray<ReasoningLevel>): ReasoningLevel {
+ if (options.length === 0) return 'off'
+ const normalized = typeof level === 'string' ? level.trim().toLowerCase() : ''
+ if (isReasoningLevel(normalized) && options.includes(normalized)) return normalized
+ // A stored level the model does not accept — an unsupported rung, or `off`
+ // on an always-on reasoning model — becomes the vendor default.
+ if (normalized && options.includes('auto')) return 'auto'
+ return options.includes('off') ? 'off' : options[0]
+}
diff --git a/frontend/src/utils/thinkingControl.test.ts b/frontend/src/utils/thinkingControl.test.ts
deleted file mode 100644
index 1840e34e6..000000000
--- a/frontend/src/utils/thinkingControl.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import assert from 'node:assert/strict'
-import test from 'node:test'
-
-import { defaultThinkingControl } from './thinkingControl.ts'
-
-// Cases mirror internal/models/chat/provider_test.go TestResolveProvider thinking defaults.
-test('defaultThinkingControl matches backend provider adapters', () => {
- const cases: Array<[string, string, ReturnType<typeof defaultThinkingControl>]> = [
- ['generic', 'anything', 'chat_template_kwargs'],
- ['nvidia', 'anything', 'chat_template_kwargs'],
- ['litellm', 'anything', 'chat_template_kwargs'],
- ['volcengine', 'doubao', 'thinking_type'],
- ['aliyun', 'qwen3-32b', 'enable_thinking'],
- ['aliyun', 'qwen-plus', 'enable_thinking'],
- ['aliyun', 'gpt-4', 'none'],
- ['lkeap', '', 'thinking_type'],
- ['lkeap', 'deepseek-v3.1', 'thinking_type'],
- ['lkeap', 'deepseek-r1', 'none'],
- ['openai', 'gpt-4o', 'none'],
- ['openai', 'gpt-5', 'none'],
- ['azure_openai', 'gpt-4', 'none'],
- ['deepseek', 'deepseek-chat', 'none'],
- ['zhipu', 'glm-4', 'none'],
- ['gemini', 'gemini-2.0', 'none'],
- ['siliconflow', 'qwen3-8b', 'none'],
- ['hunyuan', 'hunyuan-turbo', 'none'],
- ['moonshot', 'moonshot-v1-8k', 'none'],
- ['weknoracloud', 'anything', 'none'],
- ]
- for (const [provider, model, want] of cases) {
- assert.equal(
- defaultThinkingControl(provider, model),
- want,
- `${provider}/${model}`,
- )
- }
-})
diff --git a/frontend/src/utils/thinkingControl.ts b/frontend/src/utils/thinkingControl.ts
deleted file mode 100644
index 9ec34cbb7..000000000
--- a/frontend/src/utils/thinkingControl.ts
+++ /dev/null
@@ -1,90 +0,0 @@
-/** Mirrors backend internal/models/provider.IsQwenThinkingModel */
-export function isQwenThinkingModel(modelName: string): boolean {
- const lower = modelName.trim().toLowerCase()
- return (
- lower.startsWith('qwen3')
- || lower.startsWith('qwen-plus')
- || lower.startsWith('qwen-max')
- || lower.startsWith('qwen-turbo')
- )
-}
-
-/** Mirrors backend internal/models/provider.IsLKEAPDeepSeekR1Model */
-export function isLkeapDeepSeekR1Model(modelName: string): boolean {
- return modelName.toLowerCase().includes('deepseek-r1')
-}
-
-export type ThinkingControlValue =
- | 'none'
- | 'chat_template_kwargs'
- | 'enable_thinking'
- | 'thinking_type'
-
-const THINKING_CONTROL_VALUES: ThinkingControlValue[] = [
- 'none',
- 'chat_template_kwargs',
- 'enable_thinking',
- 'thinking_type',
-]
-
-/**
- * Default thinking_control for provider+model.
- * Must stay aligned with chat.resolveProvider(...).Thinking() in provider.go.
- */
-export function defaultThinkingControl(
- provider: string,
- modelName = '',
-): ThinkingControlValue {
- const p = provider.trim().toLowerCase()
- const model = modelName.trim()
-
- switch (p) {
- case 'aliyun':
- return isQwenThinkingModel(model) ? 'enable_thinking' : 'none'
- case 'lkeap':
- // R1 系列后端不发 thinking 参数;其余(含未填模型名)按 LKEAP 的 thinking.type 格式预选
- if (model && isLkeapDeepSeekR1Model(model)) return 'none'
- return 'thinking_type'
- case 'generic':
- case 'nvidia':
- case 'litellm':
- return 'chat_template_kwargs'
- case 'volcengine':
- return 'thinking_type'
- default:
- // openai, azure_openai, anthropic, zhipu, deepseek, gemini, siliconflow,
- // hunyuan, moonshot, openrouter, weknoracloud, … → baseProvider / noThinking
- return 'none'
- }
-}
-
-/** Resolve stored extra_config or fall back to the provider default. */
-export function resolveThinkingControl(
- saved: string | undefined,
- provider: string,
- modelName = '',
-): ThinkingControlValue {
- const v = saved?.trim().toLowerCase()
- if (THINKING_CONTROL_VALUES.includes(v as ThinkingControlValue)) {
- return v as ThinkingControlValue
- }
- return defaultThinkingControl(provider, modelName)
-}
-
-/** Whether the debug drawer should expose Think on/off for this saved model. */
-export function modelSupportsThinking(model: {
- type: string
- source: string
- name: string
- parameters: {
- provider?: string
- extra_config?: { thinking_control?: string }
- }
-}): boolean {
- if (model.type !== 'KnowledgeQA' || model.source !== 'remote') return false
- return resolveThinkingControl(
- model.parameters.extra_config?.thinking_control,
- model.parameters.provider || '',
- model.name || '',
- ) !== 'none'
-}
diff --git a/frontend/src/views/agent/AgentEditorModal.vue b/frontend/src/views/agent/AgentEditorModal.vue
index 2361df2ca..a947ffd8e 100644
--- a/frontend/src/views/agent/AgentEditorModal.vue
+++ b/frontend/src/views/agent/AgentEditorModal.vue
@@ -602,14 +602,29 @@
</div>
</div>
- <!-- 思考模式 -->
+ <!-- 思考强度:off / auto + 所选对话模型目录上报的等级 -->
<div class="setting-row">
<div class="setting-info">
<label>{{ $t('agent.editor.thinking') }}</label>
<p class="desc">{{ $t('agentEditor.desc.thinking') }}</p>
+ <p v-if="selectedChatModel && !selectedChatModelCanThink" class="desc">
+ {{ $t('agent.editor.reasoningEffortUnsupported') }}
+ </p>
+ <p v-else-if="selectedChatModelAlwaysThinks" class="desc">
+ {{ $t('agent.editor.reasoningEffortAlwaysOn') }}
+ </p>
</div>
<div class="setting-control">
- <t-switch v-model="thinkingEnabled" />
+ <t-select v-model="reasoningEffortLevel" class="reasoning-effort-select"
+ :popup-props="{ overlayClassName: 'reasoning-level-select-popup' }">
+ <t-option v-for="level in reasoningEffortOptions" :key="level" :value="level"
+ :label="$t(levelLabelKey(level))" :show-overflow-tooltip="false">
+ <div class="reasoning-level-option">
+ <span class="reasoning-level-option__title">{{ $t(levelLabelKey(level)) }}</span>
+ <span class="reasoning-level-option__hint">{{ $t(levelDescriptionKey(level)) }}</span>
+ </div>
+ </t-option>
+ </t-select>
</div>
</div>
@@ -1870,6 +1885,17 @@ import {
type RequirementMissKind,
type ScopeCapabilities,
} from '@/utils/tool-capabilities';
+import {
+ clampLevel,
+ levelDescriptionKey,
+ levelEnablesThinking,
+ levelFromLegacy,
+ levelLabelKey,
+ modelCanThink,
+ modelCannotDisableThinking,
+ optionsFor,
+ type ReasoningLevel,
+} from '@/utils/reasoningEffort';
// File extensions offered in the agent-level chat attachment parsing policy.
const CHAT_PARSER_EXTENSIONS = [
@@ -2755,6 +2781,7 @@ const defaultFormData = {
temperature: 0.7,
max_completion_tokens: 0,
thinking: false, // 默认禁用思考模式
+ reasoning_effort: 'off', // 思考强度;与 thinking 布尔保持同步
citation_enabled: true, // 默认输出知识库/网页来源引用
// Agent模式设置
max_iterations: 10,
@@ -3375,11 +3402,47 @@ const onAgentTypeChange = (val: AgentType) => {
}
};
-// 思考模式计算属性(直接绑定 boolean)
-const thinkingEnabled = computed({
- get: () => formData.value.config.thinking === true,
- set: (val: boolean) => { formData.value.config.thinking = val; }
+// 思考强度:reasoning_effort 为准,旧数据只有 thinking 布尔时按 true→auto / false→off 推导。
+// 写入时同步维护 thinking 布尔,保证旧后端 / 旧读取路径继续工作。
+const selectedChatModel = computed(() =>
+ allModels.value.find(model => model.id === formData.value.config.model_id),
+);
+const selectedChatModelCanThink = computed(() => modelCanThink(selectedChatModel.value?.capabilities));
+// 所选模型无法关闭思考(deepseek-reasoner / qwq-plus / gemini-3 等)时给出提示,
+// 否则下拉里没有「关闭」看起来像 bug。
+const selectedChatModelAlwaysThinks = computed(
+ () => modelCannotDisableThinking(selectedChatModel.value?.capabilities),
+);
+// 目录上报 capabilities 时严格按 thinking_levels 出选项(含「没有 off」这一事实);
+// 没有 capabilities 的模型(本地 / Ollama / 模型列表未加载)才退回通用梯度。
+const reasoningEffortOptions = computed<ReasoningLevel[]>(() => optionsFor(selectedChatModel.value?.capabilities));
+const reasoningEffortLevel = computed<ReasoningLevel>({
+ get: () => levelFromLegacy(formData.value.config.thinking, formData.value.config.reasoning_effort),
+ set: (level: ReasoningLevel) => {
+ formData.value.config.reasoning_effort = level;
+ formData.value.config.thinking = levelEnablesThinking(level);
+ },
});
+// 已存等级可能不在所选模型的可用集合里(换模型,或加载了一个旧智能体):
+// 夹到可用集合上,并同步 thinking 布尔(由 setter 负责),避免界面显示「关闭」
+// 而后端其实没下发任何开关、模型照样思考。
+//
+// 只在模型真正解析出来之后才夹:模型列表异步加载期间 capabilities 还是 undefined,
+// 此时的通用梯度会把已保存的 max/xhigh 误降级成 auto。
+const clampReasoningEffortToModel = () => {
+ if (editorInitializing.value || !selectedChatModel.value) return;
+ const clamped = clampLevel(reasoningEffortLevel.value, reasoningEffortOptions.value);
+ if (clamped !== reasoningEffortLevel.value) reasoningEffortLevel.value = clamped;
+};
+watch(
+ () => [
+ editorInitializing.value,
+ formData.value.config.model_id,
+ reasoningEffortOptions.value.join(','),
+ ].join('|'),
+ () => clampReasoningEffortToModel(),
+ { immediate: true },
+);
// 是否为内置智能体
const isBuiltinAgent = computed(() => {
@@ -3439,6 +3502,10 @@ watch(() => props.visible, async (val) => {
if (agentData.config.thinking == null) {
agentData.config.thinking = false;
}
+ // Legacy rows carry only the boolean: derive the graded level once so
+ // the selector and the persisted config agree (true → auto, false → off).
+ agentData.config.reasoning_effort = levelFromLegacy(agentData.config.thinking, agentData.config.reasoning_effort);
+ agentData.config.thinking = levelEnablesThinking(agentData.config.reasoning_effort);
agentData.config.question_suggestions = {
starters: {
@@ -5204,6 +5271,11 @@ const handleSave = async () => {
align-items: flex-start;
overflow: hidden;
+ .reasoning-effort-select {
+ width: 100%;
+ max-width: 220px;
+ }
+
&.setting-control-full {
width: 100%;
min-width: 100%;
@@ -6503,6 +6575,37 @@ const handleSave = async () => {
<!-- Non-scoped styles: TDesign teleports the popup outside this component, so
scoped selectors can't reach .agent-type-popup .t-select-option. -->
<style lang="less">
+.reasoning-level-select-popup {
+ padding: 4px;
+
+ .t-select-option {
+ height: auto !important;
+ padding: 6px 10px;
+ border-radius: 6px;
+ margin: 2px 0;
+ white-space: normal;
+ }
+}
+
+.reasoning-level-option {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ line-height: 1.35;
+ min-width: 0;
+
+ &__title {
+ font-size: var(--app-text-md);
+ color: var(--td-text-color-primary);
+ }
+
+ &__hint {
+ font-size: var(--app-text-sm);
+ color: var(--td-text-color-placeholder);
+ word-break: break-word;
+ }
+}
+
.agent-type-popup {
.t-select-option {
// 默认 option 是 32px 单行;我们要双行显示,取消固定高度并放宽 padding
diff --git a/frontend/src/views/settings/ModelSettings.vue b/frontend/src/views/settings/ModelSettings.vue
index 16e8fa40b..134acaf8b 100644
--- a/frontend/src/views/settings/ModelSettings.vue
+++ b/frontend/src/views/settings/ModelSettings.vue
@@ -102,7 +102,10 @@
</div>
</div>
<p class="model-card__subtitle">
- <span>{{ vendorLabel(model) }}</span>
+ <span class="model-card__vendor">
+ <img v-if="vendorIcon(model)" :src="vendorIcon(model)" class="model-card__vendor-icon" alt="" />
+ <span>{{ vendorLabel(model) }}</span>
+ </span>
<template v-if="model._modelType === 'embedding' && model.dimension">
<span class="model-card__sep">·</span>
<span>{{ $t('model.editor.dimensionLabel') }} {{ model.dimension }}</span>
@@ -293,16 +296,18 @@ import { useAuthStore } from '@/stores/auth'
import { useUIStore } from '@/stores/ui'
import { focusKbEditorSection } from '@/config/contextualGuides'
import { useChatResourcesStore } from '@/stores/chatResources'
+import { useModelProvidersStore } from '@/stores/modelProviders'
import {
formatContextWindow,
isDefaultContextWindow,
effectiveContextWindow,
} from '@/utils/contextWindow'
-const { t, te } = useI18n()
+const { t, locale } = useI18n()
const authStore = useAuthStore()
const uiStore = useUIStore()
const chatResources = useChatResourcesStore()
+const providersStore = useModelProvidersStore()
const router = useRouter()
type ModelType = 'chat' | 'embedding' | 'rerank' | 'vllm' | 'asr'
type FilterType = 'all' | ModelType
@@ -369,12 +374,17 @@ function convertToLegacyFormat(model: ModelConfig) {
supportsVision: model.parameters.supports_vision || false,
contextWindow: model.parameters.context_window || undefined,
maxConcurrency: model.parameters.max_concurrency,
+ maxOutputTokens: model.parameters.max_output_tokens || undefined,
customHeaders: model.parameters.custom_headers
? Object.entries(model.parameters.custom_headers).map(([key, value]) => ({ key, value: String(value) }))
: [],
- lkeapRegion: model.parameters.extra_config?.region || 'ap-guangzhou',
- // 原始存库值,编辑弹窗内再 resolve(避免打开时被推断值覆盖)
- thinkingControl: model.parameters.extra_config?.thinking_control,
+ // 厂商额外字段 / 高级覆盖原样带入编辑器(thinking_control 单独拆出,仅旧数据才有)
+ extraConfig: Object.fromEntries(
+ Object.entries(model.parameters.extra_config || {}).filter(([key]) => key !== 'thinking_control'),
+ ) as Record<string, string>,
+ thinkingControl: model.parameters.extra_config?.thinking_control || '',
+ spec: model.parameters.spec || null,
+ capabilities: model.capabilities,
_modelType: backendTypeToModelType[model.type] || 'chat' as ModelType,
// Preserve the credential metadata map so the editor dialog can render
// the "Configured" state without an extra round-trip.
@@ -423,15 +433,19 @@ const sourceLabel = (type: ModelType) => {
}
// Maps a backend `provider` id (e.g. "openai", "aliyun", "weknoracloud")
-// to its localized short label. Reuses the same i18n keys the editor's
-// provider dropdown uses, so the model card and the editor stay in sync
-// when a provider is renamed. Falls back to '' when the backend didn't
-// store a provider — caller falls back to sourceLabel().
+// to the vendor's localized name from the backend catalog (modelProviders
+// store), so the model card and the editor dropdown always agree. Falls
+// back to the raw id when the catalog has not loaded yet, and to '' when
+// the backend didn't store a provider — caller falls back to sourceLabel().
const providerLabel = (model: any): string => {
const id = model.provider
if (!id) return ''
- const key = `model.editor.providers.${id}.label`
- return te(key) ? t(key) : id
+ return providersStore.labelFor(id, String(locale.value || '')) || id
+}
+
+const vendorIcon = (model: any): string => {
+ if (model.source === 'local' || !model.provider) return ''
+ return providersStore.iconFor(model.provider)
}
// What the vendor chip on a card shows. Keeps the chip text uniformly
@@ -479,6 +493,8 @@ const emptyHint = computed(() => {
// 加载模型列表
const loadModels = async () => {
loading.value = true
+ // 厂商图标 / 本地化名称来自目录 store;与模型列表并行加载,失败不影响卡片渲染。
+ void providersStore.ensureLoaded('').catch(() => {})
try {
const models = await listModels()
allModels.value = models
@@ -596,21 +612,46 @@ const handleModelSave = async (modelData: any) => {
const trimmedAppSecret = (modelData.appSecret ?? '').trim()
const appSecretFields: { app_secret?: string } =
!editingModel.value && trimmedAppSecret ? { app_secret: trimmedAppSecret } : {}
+ // extra_config: vendor extra fields + advanced overrides (already trimmed
+ // by the editor) plus the legacy thinking_control for rows that still
+ // carry it. Empty values are dropped so cleared keys disappear.
const extraConfig: Record<string, string> = {}
- if (modelData.provider === 'lkeap' && saveType === 'rerank') {
- extraConfig.region = (modelData.lkeapRegion || 'ap-guangzhou').trim()
- }
- if (
- saveType === 'chat'
- && modelData.source === 'remote'
- && modelData.thinkingControl
- ) {
- extraConfig.thinking_control = modelData.thinkingControl
+ if (modelData.source === 'remote') {
+ for (const [key, value] of Object.entries(modelData.extraConfig || {})) {
+ const trimmed = String(value ?? '').trim()
+ if (key && trimmed) extraConfig[key] = trimmed
+ }
+ const legacyThinking = String(modelData.thinkingControl || '').trim()
+ if (saveType === 'chat' && legacyThinking) {
+ extraConfig.thinking_control = legacyThinking
+ } else {
+ delete extraConfig.thinking_control
+ }
}
- const extraConfigFields = Object.keys(extraConfig).length > 0
+ // Always send extra_config for remote models, even when it ends up empty:
+ // PUT /models/:id restores the stored map when the field is absent
+ // (internal/handler/model.go), so omitting it would make "clear the last
+ // vendor field / protocol override" silently no-op. Local rows keep the
+ // omit-when-empty behaviour — this form never edits their extra_config.
+ const extraConfigFields = modelData.source === 'remote'
? { extra_config: extraConfig }
: {}
+ // parameters.spec: keep whatever the row already had, replace compat with
+ // the (validated) JSON from the advanced textarea; drop spec when empty.
+ const specText = String(modelData.specCompat ?? '').trim()
+ const baseSpec = (modelData.spec && typeof modelData.spec === 'object') ? { ...modelData.spec } : {}
+ if (specText) {
+ const compat = JSON.parse(specText)
+ if (!compat || typeof compat !== 'object' || Array.isArray(compat)) {
+ throw new Error(t('model.editor.advanced.compat.invalid'))
+ }
+ baseSpec.compat = compat
+ } else {
+ delete baseSpec.compat
+ }
+ const specFields = Object.keys(baseSpec).length > 0 ? { spec: baseSpec } : {}
+
const apiModelData: ModelConfig = {
name: modelData.modelName.trim(),
display_name: modelData.displayName?.trim() || '',
@@ -640,6 +681,11 @@ const handleModelSave = async (modelData: any) => {
&& Number(modelData.contextWindow) >= 1024
? { context_window: Math.round(Number(modelData.contextWindow)) }
: {}),
+ ...((saveType === 'chat' || saveType === 'vllm')
+ && Number(modelData.maxOutputTokens) > 0
+ ? { max_output_tokens: Math.round(Number(modelData.maxOutputTokens)) }
+ : {}),
+ ...specFields,
// 后台并发上限:仅 chat/embedding/vllm 受治理,>0 才写入(0/空沿用全局默认)。
...(['chat', 'embedding', 'vllm'].includes(saveType)
&& Number(modelData.maxConcurrency) > 0
@@ -1055,15 +1101,50 @@ onMounted(() => {
}
.model-card__subtitle {
+ // A flex row, not inline text: .model-card__vendor is an inline-flex box
+ // whose baseline comes from its first item — the 14px icon, whose baseline
+ // is its bottom edge — so as inline content it sat a couple of pixels off
+ // the "· 200K" beside it. Aligning the row by centre instead of by
+ // baseline puts every part of the line on one optical line.
+ display: flex;
+ align-items: center;
+ min-width: 0;
margin: 2px 0 0;
font-size: var(--app-text-sm);
line-height: 1.5;
color: var(--td-text-color-secondary);
- overflow: hidden;
- text-overflow: ellipsis;
+}
+
+.model-card__vendor {
+ display: inline-flex;
+ align-items: center;
+ gap: 5px;
+ min-width: 0;
+
+ // The vendor name is the only part long enough to need truncating; the
+ // context window and the badges after it must stay readable.
+ > span {
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+}
+
+.model-card__sep,
+.model-card__ctx,
+.model-card__vision {
+ flex: none;
white-space: nowrap;
}
+.model-card__vendor-icon {
+ width: 14px;
+ height: 14px;
+ flex-shrink: 0;
+ border-radius: 3px;
+ object-fit: contain;
+}
+
.model-card__sep {
margin: 0 4px;
color: var(--td-text-color-placeholder);
diff --git a/internal/agent/context_debug.go b/internal/agent/context_debug.go
index 13791ff3e..62d8c56e9 100644
--- a/internal/agent/context_debug.go
+++ b/internal/agent/context_debug.go
@@ -56,7 +56,10 @@ func (e *AgentEngine) breakdownContext(messages []chat.Message, tools []chat.Too
}
}
- if reasoning := est.EstimateString(msg.ReasoningContent); reasoning > 0 {
+ // Reasoning is the text plus the opaque artifacts replayed with it, so
+ // the line stays comparable to the message total the estimator reports.
+ if reasoning := est.EstimateString(msg.ReasoningContent) +
+ est.EstimateReasoningArtifacts(msg); reasoning > 0 {
b.Reasoning += reasoning
}
for _, tc := range msg.ToolCalls {
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index dceea8f8e..ed4da6fb5 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -894,6 +894,8 @@ func (e *AgentEngine) runReActIteration(
Iteration: state.CurrentRound,
Thought: response.Content,
ReasoningContent: response.ReasoningContent,
+ ReasoningSignature: response.ReasoningSignature,
+ ReasoningMetadata: response.ReasoningMetadata,
ToolCalls: make([]types.ToolCall, 0),
Timestamp: time.Now(),
}
@@ -978,9 +980,11 @@ func (e *AgentEngine) runReActIteration(
canContinue := e.withinIterationBudget(nextRound) || e.steerOverruns < maxSteerOverruns
if canContinue {
*messagesPtr = append(*messagesPtr, chat.Message{
- Role: "assistant",
- Content: verdict.finalAnswer,
- ReasoningContent: response.ReasoningContent,
+ Role: "assistant",
+ Content: verdict.finalAnswer,
+ ReasoningContent: response.ReasoningContent,
+ ReasoningSignature: response.ReasoningSignature,
+ ReasoningMetadata: response.ReasoningMetadata,
})
injected := e.drainSteerMessages(ctx, state, messagesPtr, sessionID, assistantMessageID)
if injected > 0 {
diff --git a/internal/agent/observe.go b/internal/agent/observe.go
index 9c1e82337..4c0e3c613 100644
--- a/internal/agent/observe.go
+++ b/internal/agent/observe.go
@@ -914,12 +914,18 @@ func (e *AgentEngine) appendToolResults(
messages []chat.Message,
step types.AgentStep,
) []chat.Message {
- // Add assistant message with tool calls (if any)
- if step.Thought != "" || len(step.ToolCalls) > 0 || step.ReasoningContent != "" {
+ // Add assistant message with tool calls (if any). The reasoning artifacts
+ // count as content of their own: an Anthropic round can consist purely of
+ // a redacted_thinking block, and dropping the turn loses state the next
+ // request has to replay.
+ if step.Thought != "" || len(step.ToolCalls) > 0 || step.ReasoningContent != "" ||
+ step.ReasoningSignature != "" || len(step.ReasoningMetadata) > 0 {
assistantMsg := chat.Message{
- Role: "assistant",
- Content: step.Thought,
- ReasoningContent: step.ReasoningContent,
+ Role: "assistant",
+ Content: step.Thought,
+ ReasoningContent: step.ReasoningContent,
+ ReasoningSignature: step.ReasoningSignature,
+ ReasoningMetadata: step.ReasoningMetadata,
}
// Add tool calls to assistant message (following OpenAI format)
diff --git a/internal/agent/think.go b/internal/agent/think.go
index 94bfec210..83d1dae45 100644
--- a/internal/agent/think.go
+++ b/internal/agent/think.go
@@ -22,10 +22,14 @@ import (
type streamLLMResult struct {
Content string
ReasoningContent string // accumulated reasoning content, kept separate from answer
- ToolCalls []types.LLMToolCall
- Usage *types.TokenUsage
- FinishReason string // actual finish_reason from LLM (captured from last stream chunk)
- StreamError string // error message from stream (e.g., timeout), kept separate from Content
+ // ReasoningSignature / ReasoningMetadata arrive on the closing chunk's
+ // Data and must be persisted with the step for replay.
+ ReasoningSignature string
+ ReasoningMetadata types.ProviderMetadata
+ ToolCalls []types.LLMToolCall
+ Usage *types.TokenUsage
+ FinishReason string // actual finish_reason from LLM (captured from last stream chunk)
+ StreamError string // error message from stream (e.g., timeout), kept separate from Content
}
// streamLLMToEventBus streams LLM response through EventBus (generic method)
@@ -133,6 +137,12 @@ func (e *AgentEngine) streamLLMToEventBus(
if chunk.FinishReason != "" {
result.FinishReason = chunk.FinishReason
}
+ if sig, ok := chunk.Data["reasoning_signature"].(string); ok && sig != "" {
+ result.ReasoningSignature = sig
+ }
+ if md, ok := chunk.Data["reasoning_metadata"].(types.ProviderMetadata); ok && len(md) > 0 {
+ result.ReasoningMetadata = md
+ }
if emitFunc != nil {
emitFunc(&chunk, result.Content)
@@ -257,6 +267,7 @@ func (e *AgentEngine) streamThinkingToEventBus(
MaxCompletionTokens: budget,
Tools: tools,
Thinking: e.config.Thinking,
+ ReasoningEffort: chat.SanitizeReasoningEffort(ctx, e.config.ReasoningEffort, "agent config"),
ParallelToolCalls: &parallelToolCalls,
PromptCacheKey: sessionID,
}
@@ -456,11 +467,13 @@ func (e *AgentEngine) streamThinkingToEventBus(
}
resp := &types.ChatResponse{
- Content: fullContent,
- ReasoningContent: llmResult.ReasoningContent,
- ToolCalls: llmResult.ToolCalls,
- FinishReason: finishReason,
- AnswerStreamed: answerStreamed,
+ Content: fullContent,
+ ReasoningContent: llmResult.ReasoningContent,
+ ReasoningSignature: llmResult.ReasoningSignature,
+ ReasoningMetadata: llmResult.ReasoningMetadata,
+ ToolCalls: llmResult.ToolCalls,
+ FinishReason: finishReason,
+ AnswerStreamed: answerStreamed,
}
if answerStreamed {
resp.AnswerEventID = answerID
diff --git a/internal/agent/token/estimator.go b/internal/agent/token/estimator.go
index 7eeeb6514..eb489f734 100644
--- a/internal/agent/token/estimator.go
+++ b/internal/agent/token/estimator.go
@@ -20,8 +20,10 @@
package token
import (
+ "encoding/json"
"fmt"
"math"
+ "strings"
"sync/atomic"
"github.com/Tencent/WeKnora/internal/models/chat"
@@ -137,6 +139,13 @@ func (e *Estimator) EstimateString(s string) int {
// 26k — compaction then cut in the wrong place, freed almost nothing, and ran
// again the next round. Reasoning content is counted alongside text and tool
// calls for that reason.
+//
+// The reasoning artifacts that travel with it are counted too. They are opaque
+// to us but not to the provider's billing: an Anthropic thinking signature is a
+// few hundred base64 characters, and an OpenAI Responses encrypted reasoning
+// item (or an OpenRouter reasoning_details blob) is several kilobytes replayed
+// on every assistant turn. Leaving them out reproduces exactly the
+// under-measurement described above, one replayed turn at a time.
func (e *Estimator) EstimateMessage(msg *chat.Message) int {
tokens := perMessageOverhead
tokens += e.EstimateString(msg.Role)
@@ -144,17 +153,52 @@ func (e *Estimator) EstimateMessage(msg *chat.Message) int {
tokens += e.EstimateString(msg.Name)
tokens += e.EstimateString(msg.ToolCallID)
tokens += e.EstimateString(msg.ReasoningContent)
+ tokens += e.EstimateReasoningArtifacts(msg)
tokens += e.estimateImageParts(msg)
for _, tc := range msg.ToolCalls {
tokens += e.EstimateString(tc.Function.Name)
tokens += e.EstimateString(tc.Function.Arguments)
+ tokens += e.estimateProviderMetadata(tc.ProviderMetadata)
tokens += perToolCallOverhead
}
return tokens
}
+// EstimateReasoningArtifacts counts the opaque provider state replayed with an
+// assistant turn. The signature carries a protocol tag that is stripped before
+// it goes out, so only the payload after the tag is billed; the metadata is
+// sent as-is, one JSON value per namespace key.
+func (e *Estimator) EstimateReasoningArtifacts(msg *chat.Message) int {
+ tokens := 0
+ if sig := msg.ReasoningSignature; sig != "" {
+ if _, payload, found := strings.Cut(sig, ":"); found {
+ sig = payload
+ }
+ tokens += e.EstimateString(sig)
+ }
+ tokens += e.estimateProviderMetadata(msg.ReasoningMetadata)
+ return tokens
+}
+
+// estimateProviderMetadata counts one opaque provider-state map, one JSON
+// value per namespace key, the way it goes out on the wire.
+//
+// The same accounting applies per tool call as it does per turn: a Gemini
+// thought signature and an OpenAI Responses item id ride on the tool call, not
+// on the message, and are replayed on every subsequent turn. A signature runs
+// to kilobytes, so a round of parallel calls left uncounted under-measures the
+// context exactly the way the missing reasoning content did.
+func (e *Estimator) estimateProviderMetadata(md map[string]json.RawMessage) int {
+ tokens := 0
+ for key, raw := range md {
+ tokens += e.EstimateString(key)
+ tokens += e.EstimateString(string(raw))
+ }
+ return tokens
+}
+
// estimateImageParts counts multimodal content. MultiContent is the assembled
// representation actually sent to the provider, so when it is present the raw
// Images list is the same pictures counted a second time.
diff --git a/internal/agent/token/reasoning_artifacts_test.go b/internal/agent/token/reasoning_artifacts_test.go
new file mode 100644
index 000000000..3627e33e4
--- /dev/null
+++ b/internal/agent/token/reasoning_artifacts_test.go
@@ -0,0 +1,127 @@
+package token
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// TestEstimateMessageCountsReasoningArtifacts pins the fix for the compaction
+// trigger under-measuring replayed assistant turns. An OpenAI Responses
+// encrypted reasoning item or an Anthropic signature rides on every replayed
+// assistant message; leaving it out of the estimate is the same class of bug
+// the package comment describes for reasoning_content.
+func TestEstimateMessageCountsReasoningArtifacts(t *testing.T) {
+ est, err := NewEstimator()
+ if err != nil {
+ t.Fatalf("NewEstimator: %v", err)
+ }
+
+ plain := chat.Message{Role: "assistant", Content: "ok"}
+ blob, err := json.Marshal([]string{strings.Repeat("QUJDRA", 800)})
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ withArtifacts := plain
+ withArtifacts.ReasoningSignature = "anthropic-messages:" + strings.Repeat("c2ln", 200)
+ withArtifacts.ReasoningMetadata = types.ProviderMetadata{"openai_responses_reasoning": blob}
+
+ base := est.EstimateMessage(&plain)
+ full := est.EstimateMessage(&withArtifacts)
+ if full <= base {
+ t.Fatalf("reasoning artifacts not counted: base=%d full=%d", base, full)
+ }
+ // The blobs are kilobytes, so the delta must be substantial rather than
+ // the handful of tokens a key name alone would add.
+ if delta := full - base; delta < 500 {
+ t.Errorf("artifact cost looks under-counted: delta=%d", delta)
+ }
+}
+
+// TestEstimateReasoningArtifactsSkipsProtocolTag checks the stored signature's
+// "<protocol>:" prefix is not billed: api.SignatureFor strips it before the
+// signature goes out on the wire.
+func TestEstimateReasoningArtifactsSkipsProtocolTag(t *testing.T) {
+ est, err := NewEstimator()
+ if err != nil {
+ t.Fatalf("NewEstimator: %v", err)
+ }
+ payload := strings.Repeat("c2ln", 50)
+ tagged := &chat.Message{Role: "assistant", ReasoningSignature: "anthropic-messages:" + payload}
+ untagged := &chat.Message{Role: "assistant", ReasoningSignature: payload}
+ if got, want := est.EstimateReasoningArtifacts(tagged), est.EstimateReasoningArtifacts(untagged); got != want {
+ t.Errorf("protocol tag billed: tagged=%d untagged=%d", got, want)
+ }
+}
+
+// TestEstimateReasoningArtifactsEmpty keeps the common case free of cost.
+func TestEstimateReasoningArtifactsEmpty(t *testing.T) {
+ est, err := NewEstimator()
+ if err != nil {
+ t.Fatalf("NewEstimator: %v", err)
+ }
+ if got := est.EstimateReasoningArtifacts(&chat.Message{Role: "user", Content: "hi"}); got != 0 {
+ t.Errorf("expected 0 for a message without artifacts, got %d", got)
+ }
+}
+
+// Gemini thought signatures and OpenAI Responses item ids ride on the tool
+// call, not on the message, and are replayed on every later turn. Counting
+// only name+arguments under-measured a parallel tool round by kilobytes —
+// the same failure mode as the message-level artifacts above.
+func TestEstimateMessageCountsToolCallProviderMetadata(t *testing.T) {
+ est, err := NewEstimator()
+ if err != nil {
+ t.Fatalf("NewEstimator: %v", err)
+ }
+
+ signature, err := json.Marshal(strings.Repeat("CtoBCr8B", 400))
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ call := chat.ToolCall{
+ ID: "call_1", Type: "function",
+ Function: chat.FunctionCall{Name: "search", Arguments: `{"q":"x"}`},
+ }
+ plain := chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{call}}
+
+ withMetadata := call
+ withMetadata.ProviderMetadata = types.ToolCallMetadata{"thought_signature": signature}
+ annotated := chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{withMetadata}}
+
+ base := est.EstimateMessage(&plain)
+ full := est.EstimateMessage(&annotated)
+ if full <= base {
+ t.Fatalf("tool-call provider metadata not counted: base=%d full=%d", base, full)
+ }
+ // It must be accounted like the message-level artifacts: the payload, not
+ // just the namespace key.
+ if delta := full - base; delta < 500 {
+ t.Errorf("tool-call metadata looks under-counted: delta=%d", delta)
+ }
+}
+
+// Every call in a parallel round carries its own signature, so the cost has
+// to scale with the number of calls.
+func TestEstimateMessageCountsMetadataPerToolCall(t *testing.T) {
+ est, err := NewEstimator()
+ if err != nil {
+ t.Fatalf("NewEstimator: %v", err)
+ }
+ md := types.ToolCallMetadata{"thought_signature": json.RawMessage(`"` + strings.Repeat("CtoB", 200) + `"`)}
+ call := chat.ToolCall{
+ ID: "c", Type: "function",
+ Function: chat.FunctionCall{Name: "f", Arguments: "{}"}, ProviderMetadata: md,
+ }
+ one := chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{call}}
+ two := chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{call, call}}
+
+ single := est.EstimateMessage(&one) - est.EstimateMessage(&chat.Message{Role: "assistant"})
+ double := est.EstimateMessage(&two) - est.EstimateMessage(&chat.Message{Role: "assistant"})
+ if double < single*2-perToolCallOverhead {
+ t.Errorf("metadata counted once for a parallel round: single=%d double=%d", single, double)
+ }
+}
diff --git a/internal/agent/tool_images_test.go b/internal/agent/tool_images_test.go
index 9762800d6..063277866 100644
--- a/internal/agent/tool_images_test.go
+++ b/internal/agent/tool_images_test.go
@@ -2,10 +2,12 @@ package agent
import (
"context"
+ "encoding/json"
"errors"
"testing"
- "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/models/api/openaicompletions"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
@@ -28,9 +30,17 @@ func TestToolImagesReachNextModelTurnAfterAllReplies(t *testing.T) {
require.Equal(t, "user", messages[3].Role)
require.Equal(t, step.ToolCalls[0].Result.Images, messages[3].Images)
require.Contains(t, messages[3].Content, "untrusted tool evidence")
- wire := (&chat.RemoteAPIChat{}).ConvertMessages(messages)
- require.Len(t, wire[3].MultiContent, 2)
- require.Equal(t, step.ToolCalls[0].Result.Images[0], wire[3].MultiContent[0].ImageURL.URL)
+ client := openaicompletions.New(openaicompletions.Config{Settings: catalog.DefaultOpenAICompletions()})
+ body, err := client.BuildRequestBody(messages, nil, false)
+ require.NoError(t, err)
+ raw, err := json.Marshal(body["messages"])
+ require.NoError(t, err)
+ var wire []map[string]any
+ require.NoError(t, json.Unmarshal(raw, &wire))
+ parts := wire[3]["content"].([]any)
+ require.Len(t, parts, 2)
+ imagePart := parts[0].(map[string]any)["image_url"].(map[string]any)
+ require.Equal(t, step.ToolCalls[0].Result.Images[0], imagePart["url"])
} else {
require.Len(t, messages, 3)
require.Contains(t, messages[1].Content, "cannot view")
diff --git a/internal/application/service/agent_history.go b/internal/application/service/agent_history.go
index c04087563..78bca685d 100644
--- a/internal/application/service/agent_history.go
+++ b/internal/application/service/agent_history.go
@@ -507,15 +507,20 @@ func buildAgentStepMessages(step types.AgentStep) []chat.Message {
nonTerminalCalls := filterNonTerminalToolCalls(step.ToolCalls)
if len(nonTerminalCalls) == 0 {
if step.IntermediateAnswer && strings.TrimSpace(step.Thought) != "" {
- return []chat.Message{{Role: "assistant", Content: step.Thought, ReasoningContent: step.ReasoningContent}}
+ return []chat.Message{{
+ Role: "assistant", Content: step.Thought, ReasoningContent: step.ReasoningContent,
+ ReasoningSignature: step.ReasoningSignature, ReasoningMetadata: step.ReasoningMetadata,
+ }}
}
return nil
}
assistantMsg := chat.Message{
- Role: "assistant",
- Content: step.Thought,
- ReasoningContent: step.ReasoningContent,
- ToolCalls: make([]chat.ToolCall, 0, len(nonTerminalCalls)),
+ Role: "assistant",
+ Content: step.Thought,
+ ReasoningContent: step.ReasoningContent,
+ ReasoningSignature: step.ReasoningSignature,
+ ReasoningMetadata: step.ReasoningMetadata,
+ ToolCalls: make([]chat.ToolCall, 0, len(nonTerminalCalls)),
}
for _, tc := range nonTerminalCalls {
argsJSON, _ := json.Marshal(tc.Args)
@@ -546,7 +551,8 @@ func buildAgentStepMessages(step types.AgentStep) []chat.Message {
// finalAnswerHistoryMessage is the canonical answer of a turn, or nil when the
// turn produced no text (stopped, or answered purely through tools). The
// generated-file markers belong to that turn, so they are relabeled before
-// being replayed into a later turn's history.
+// being replayed into a later turn's history. It also carries the closing
+// round's reasoning artifacts — see finalAnswerReasoningStep.
func finalAnswerHistoryMessage(m *types.Message) *chat.Message {
finalContent := agentHistoryThinkTagRegex.ReplaceAllString(m.Content, "")
// Version clarification was written for that message's turn, not this one.
@@ -558,7 +564,46 @@ func finalAnswerHistoryMessage(m *types.Message) *chat.Message {
if finalContent == "" {
return nil
}
- return &chat.Message{Role: "assistant", Content: finalContent}
+ final := &chat.Message{Role: "assistant", Content: finalContent}
+ // The artifacts ride in their own fields, so stripping <think> blocks out
+ // of the visible answer above and replaying the round's reasoning here are
+ // not in conflict: nothing thinking-shaped is added back to Content.
+ if step := finalAnswerReasoningStep(m.AgentSteps); step != nil {
+ final.ReasoningContent = step.ReasoningContent
+ final.ReasoningSignature = step.ReasoningSignature
+ final.ReasoningMetadata = step.ReasoningMetadata
+ }
+ return final
+}
+
+// finalAnswerReasoningStep returns the step whose reasoning artifacts belong on
+// the turn's final assistant message, or nil when none do.
+//
+// A turn normally ends with a plain answer and no tool calls. The engine
+// records that closing round like any other, artifacts included, but
+// buildAgentStepMessages emits nothing for a step without tool calls — so
+// everything the next turn has to hand back (the OpenAI Responses encrypted
+// reasoning items, a DeepSeek/MiMo reasoning_content, an Anthropic thinking
+// signature) stopped at the turn boundary, exactly as the tool rounds' did
+// before they were replayed.
+//
+// Only the last step is eligible: an earlier round's artifacts belong to the
+// assistant message that round already produced, with its tool results in
+// between. Whether that message exists is asked of buildAgentStepMessages
+// itself rather than restated here, so a shape it learns to replay later is one
+// this function stops duplicating without being touched.
+func finalAnswerReasoningStep(steps types.AgentSteps) *types.AgentStep {
+ if len(steps) == 0 {
+ return nil
+ }
+ last := &steps[len(steps)-1]
+ if last.ReasoningContent == "" && last.ReasoningSignature == "" && len(last.ReasoningMetadata) == 0 {
+ return nil
+ }
+ if len(buildAgentStepMessages(*last)) > 0 {
+ return nil
+ }
+ return last
}
// legacyFinalAnswerToolName is the name of the now-removed final_answer tool.
diff --git a/internal/application/service/agent_history_test.go b/internal/application/service/agent_history_test.go
index 1c0451bcf..8483e52b5 100644
--- a/internal/application/service/agent_history_test.go
+++ b/internal/application/service/agent_history_test.go
@@ -450,6 +450,78 @@ func TestBuildAssistantHistoryMessages_ReplaysReasoningContent(t *testing.T) {
assert.Empty(t, got[2].ReasoningContent)
}
+// TestBuildAssistantHistoryMessages_ReplaysFinalAnswerReasoning covers the
+// common shape the tool-round replay missed: a turn that ends with a plain
+// answer and no tool calls.
+//
+// The engine records that closing round as an ordinary step, artifacts and
+// all, but buildAgentStepMessages emits nothing for a step without tool calls,
+// so everything the provider needs back — the OpenAI Responses encrypted
+// reasoning items, a DeepSeek/MiMo reasoning_content, an Anthropic thinking
+// signature — used to end at the turn boundary.
+func TestBuildAssistantHistoryMessages_ReplaysFinalAnswerReasoning(t *testing.T) {
+ items := json.RawMessage(`[{"type":"reasoning","id":"rs_1","encrypted_content":"opaque"}]`)
+ msg := &types.Message{
+ Role: "assistant",
+ Content: "<think>leaked</think>The answer is 42.",
+ AgentSteps: types.AgentSteps{
+ {
+ Iteration: 0,
+ Thought: "The answer is 42.",
+ ReasoningContent: "checking the arithmetic",
+ ReasoningSignature: "sig-1",
+ ReasoningMetadata: types.ProviderMetadata{"openai_responses_reasoning": items},
+ },
+ },
+ }
+ got := buildAssistantHistoryMessages(msg)
+ require.Len(t, got, 1)
+ assert.Equal(t, "assistant", got[0].Role)
+ // The think tags stay out of the visible answer; the artifacts ride in
+ // their own fields, which is where the providers read them.
+ assert.Equal(t, "The answer is 42.", got[0].Content)
+ assert.Equal(t, "checking the arithmetic", got[0].ReasoningContent)
+ assert.Equal(t, "sig-1", got[0].ReasoningSignature)
+ assert.JSONEq(t, string(items), string(got[0].ReasoningMetadata["openai_responses_reasoning"]))
+}
+
+// TestBuildAssistantHistoryMessages_FinalAnswerDoesNotDuplicateReasoning pins
+// the other half: artifacts buildAgentStepMessages already replayed must not be
+// repeated on the final message. A round that issued tool calls, and a round
+// whose text was already emitted as an intermediate answer, both carry their
+// own assistant message.
+func TestBuildAssistantHistoryMessages_FinalAnswerDoesNotDuplicateReasoning(t *testing.T) {
+ toolRound := types.AgentStep{
+ Thought: "Let me search.",
+ ReasoningContent: "tool round thinking",
+ ToolCalls: []types.ToolCall{{
+ ID: "call_1",
+ Name: agenttools.ToolSearchKnowledge,
+ Args: map[string]interface{}{"query": "foo"},
+ Result: &types.ToolResult{Success: true, Output: "doc A"},
+ }},
+ }
+ withTools := buildAssistantHistoryMessages(&types.Message{
+ Role: "assistant", Content: "Found it.", AgentSteps: types.AgentSteps{toolRound},
+ })
+ require.Len(t, withTools, 3)
+ assert.Equal(t, "tool round thinking", withTools[0].ReasoningContent)
+ assert.Empty(t, withTools[2].ReasoningContent, "the tool round already replayed its own artifacts")
+
+ steered := buildAssistantHistoryMessages(&types.Message{
+ Role: "assistant", Content: "Shorter answer.",
+ AgentSteps: types.AgentSteps{{
+ Thought: "Long answer.",
+ IntermediateAnswer: true,
+ ReasoningContent: "intermediate round thinking",
+ }},
+ })
+ require.Len(t, steered, 2)
+ assert.Equal(t, "intermediate round thinking", steered[0].ReasoningContent)
+ assert.Empty(t, steered[1].ReasoningContent,
+ "the intermediate answer already carries this step's artifacts")
+}
+
func TestMCPProxyHistoryRetainsProtocolCallAndTarget(t *testing.T) {
msg := &types.Message{Role: "assistant", AgentSteps: types.AgentSteps{{ToolCalls: []types.ToolCall{{
ID: "proxy-id", Name: "call_mcp_tool",
diff --git a/internal/application/service/chat_pipeline/common.go b/internal/application/service/chat_pipeline/common.go
index 8d17f7d72..61a189af3 100644
--- a/internal/application/service/chat_pipeline/common.go
+++ b/internal/application/service/chat_pipeline/common.go
@@ -43,6 +43,7 @@ func prepareChatModel(ctx context.Context, modelService interfaces.ModelService,
return nil, nil, err
}
+ effort := chat.SanitizeReasoningEffort(ctx, chatManage.SummaryConfig.ReasoningEffort, "session summary config")
opt := &chat.ChatOptions{
Temperature: chatManage.SummaryConfig.Temperature,
TopP: chatManage.SummaryConfig.TopP,
@@ -52,11 +53,13 @@ func prepareChatModel(ctx context.Context, modelService interfaces.ModelService,
FrequencyPenalty: chatManage.SummaryConfig.FrequencyPenalty,
PresencePenalty: chatManage.SummaryConfig.PresencePenalty,
Thinking: chatManage.SummaryConfig.Thinking,
+ ReasoningEffort: effort,
PromptCacheKey: chatManage.SessionID,
}
- if opt.Thinking != nil {
+ if level, requested := opt.Reasoning(); requested {
pipelineInfo(ctx, "Stream", "thinking_option", map[string]interface{}{
- "enabled": *opt.Thinking,
+ "enabled": level.Enabled(),
+ "level": string(level),
})
}
diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.go
index f5e69590a..c3ab10b52 100644
--- a/internal/application/service/session_agent_qa.go
+++ b/internal/application/service/session_agent_qa.go
@@ -326,6 +326,7 @@ func (s *sessionService) buildAgentConfig(
MCPServices: customAgent.Config.MCPServices,
MCPAuthWaitTimeout: customAgent.Config.MCPAuthWaitTimeout,
Thinking: customAgent.Config.Thinking,
+ ReasoningEffort: customAgent.Config.ReasoningEffort,
CitationEnabled: customAgent.Config.CitationEnabled,
RetrieveKBOnlyWhenMentioned: customAgent.Config.RetrieveKBOnlyWhenMentioned,
LLMCallTimeout: customAgent.Config.LLMCallTimeout,
diff --git a/internal/application/service/session_qa_helpers.go b/internal/application/service/session_qa_helpers.go
index 65786c407..11484b827 100644
--- a/internal/application/service/session_qa_helpers.go
+++ b/internal/application/service/session_qa_helpers.go
@@ -235,6 +235,7 @@ func (s *sessionService) applyAgentOverridesToChatManage(
// EnsureDefaults pins nil to explicit false so thinking_control wire formats
// always receive a value.
cm.SummaryConfig.Thinking = customAgent.Config.Thinking
+ cm.SummaryConfig.ReasoningEffort = customAgent.Config.ReasoningEffort
cm.CitationEnabled = customAgent.Config.CitationEnabled
if customAgent.Config.Thinking != nil {
logger.Infof(ctx, "Using custom agent's thinking: %v", *customAgent.Config.Thinking)
diff --git a/internal/container/container.go b/internal/container/container.go
index c388e91a9..a8936d48c 100644
--- a/internal/container/container.go
+++ b/internal/container/container.go
@@ -84,10 +84,12 @@ import (
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/mcp"
"github.com/Tencent/WeKnora/internal/mcpserver"
- "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/models/embedding"
"github.com/Tencent/WeKnora/internal/models/limiter"
"github.com/Tencent/WeKnora/internal/models/utils/ollama"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors" // register built-in vendors
"github.com/Tencent/WeKnora/internal/router"
"github.com/Tencent/WeKnora/internal/sandbox"
"github.com/Tencent/WeKnora/internal/storageallowlist"
@@ -111,6 +113,12 @@ import (
// Returns:
// - Configured container with all application dependencies registered
func BuildContainer(container *dig.Container) *dig.Container {
+ // Deployment-level model catalog overlay (config/models.json, optional).
+ // Built-in vendors register themselves through the vendors package
+ // import; the overlay may add vendors or patch built-in ones.
+ if err := catalog.LoadOverlay(config.ConfigDir()); err != nil {
+ logger.Warnf(context.Background(), "Load models catalog overlay failed: %v", err)
+ }
ctx := context.Background()
logger.Debugf(ctx, "[Container] Starting container initialization...")
@@ -595,7 +603,7 @@ func registerChatLocalImageResolver(
storageResolver interfaces.StorageBackendResolver,
resourceCatalog interfaces.ResourceCatalog,
) {
- chat.LocalImageResolver = func(storageURL string) ([]byte, bool) {
+ api.LocalImageResolver = func(storageURL string) ([]byte, bool) {
// The object storage clients bound connection setup but leave the
// transfer to this context, so give it a deadline: a chat turn must
// not hang on one image whose download stalls.
@@ -879,6 +887,9 @@ func initDatabase(cfg *config.Config) (*gorm.DB, error) {
migrateLegacyStorageBackends(db)
// Post-migration: declarative built-in models from config/builtin_models.yaml (optional).
+ // The loader validates each row's catalog parameters through this hook;
+ // the wiring lives here because internal/types cannot import the catalog.
+ types.ValidateModelParameters = catalog.ValidateRow
if err := types.LoadBuiltinModelsConfig(context.Background(), db, config.ConfigDir()); err != nil {
logger.Warnf(context.Background(), "Load builtin models config failed: %v", err)
}
diff --git a/internal/handler/custom_agent.go b/internal/handler/custom_agent.go
index c4881903b..69fb2353f 100644
--- a/internal/handler/custom_agent.go
+++ b/internal/handler/custom_agent.go
@@ -3,6 +3,7 @@ package handler
import (
"context"
"encoding/json"
+ "fmt"
"net/http"
"strconv"
"strings"
@@ -11,6 +12,7 @@ import (
"github.com/Tencent/WeKnora/internal/errors"
"github.com/Tencent/WeKnora/internal/im"
"github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
secutils "github.com/Tencent/WeKnora/internal/utils"
@@ -106,6 +108,10 @@ func (h *CustomAgentHandler) CreateAgent(c *gin.Context) {
c.Error(err)
return
}
+ if err := normalizeAgentReasoningEffort(&req.Config); err != nil {
+ _ = c.Error(err)
+ return
+ }
// Build agent object
agent := &types.CustomAgent{
@@ -372,6 +378,10 @@ func (h *CustomAgentHandler) UpdateAgent(c *gin.Context) {
c.Error(err)
return
}
+ if err := normalizeAgentReasoningEffort(&req.Config); err != nil {
+ _ = c.Error(err)
+ return
+ }
// Only a sent avatar is validated: nil means the caller never touched the
// field, so there is no value to bound. Checking the length here is what
@@ -751,6 +761,30 @@ func (h *CustomAgentHandler) validateAgentSandboxConfig(
return nil
}
+// normalizeAgentReasoningEffort validates config.reasoning_effort and rewrites
+// it to its canonical spelling.
+//
+// Without this the field was stored verbatim and cast straight to
+// api.ReasoningEffort in agent/think.go and chat_pipeline/common.go. A typo
+// there does not disable thinking, it silently enables it: ReasoningEffort
+// wins over the legacy boolean and anything non-empty other than "off" counts
+// as enabled, so `"reasoning_effort": "hgih"` turns thinking on for a vendor
+// that then receives a level it rejects (or clamps in an unpredictable way).
+func normalizeAgentReasoningEffort(cfg *types.CustomAgentConfig) error {
+ if cfg == nil || cfg.ReasoningEffort == "" {
+ return nil
+ }
+ level, ok := api.ParseReasoningEffort(cfg.ReasoningEffort)
+ if !ok {
+ return errors.NewBadRequestError(
+ fmt.Sprintf("reasoning_effort must be one of %v", api.AllReasoningEfforts))
+ }
+ // Store the canonical value so EnsureDefaults and the editor never have to
+ // know about the accepted aliases ("none", "true", ...).
+ cfg.ReasoningEffort = string(level)
+ return nil
+}
+
func authorizeAgentKnowledgeScope(ctx context.Context, cfg types.CustomAgentConfig) error {
scope, ok := types.TenantAPIKeyScopeFromContext(ctx)
if !ok || !scope.IsKnowledgeBaseRestricted() {
diff --git a/internal/handler/custom_agent_reasoning_effort_test.go b/internal/handler/custom_agent_reasoning_effort_test.go
new file mode 100644
index 000000000..f55fb2c10
--- /dev/null
+++ b/internal/handler/custom_agent_reasoning_effort_test.go
@@ -0,0 +1,52 @@
+package handler
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// TestNormalizeAgentReasoningEffortRejectsUnknownLevel pins the create/update
+// guard. An unvalidated level does not degrade to "off": ReasoningEffort wins
+// over the legacy boolean and every non-empty value other than "off" counts as
+// thinking-on, so a typo used to enable thinking and hand the vendor a level
+// it never documented.
+func TestNormalizeAgentReasoningEffortRejectsUnknownLevel(t *testing.T) {
+ cfg := types.CustomAgentConfig{ReasoningEffort: "hgih"}
+ if err := normalizeAgentReasoningEffort(&cfg); err == nil {
+ t.Fatal("expected an error for an unknown reasoning_effort")
+ }
+}
+
+// TestNormalizeAgentReasoningEffortCanonicalizes checks the accepted aliases
+// are rewritten, so EnsureDefaults and the editor only ever see canonical
+// values.
+func TestNormalizeAgentReasoningEffortCanonicalizes(t *testing.T) {
+ cases := map[string]string{
+ "": "",
+ "high": "high",
+ "off": "off",
+ "none": "off",
+ "false": "off",
+ "true": "auto",
+ "on": "auto",
+ }
+ for in, want := range cases {
+ cfg := types.CustomAgentConfig{ReasoningEffort: in}
+ if err := normalizeAgentReasoningEffort(&cfg); err != nil {
+ t.Errorf("normalize(%q): unexpected error %v", in, err)
+ continue
+ }
+ if cfg.ReasoningEffort != want {
+ t.Errorf("normalize(%q) = %q, want %q", in, cfg.ReasoningEffort, want)
+ }
+ }
+}
+
+// TestNormalizeAgentReasoningEffortNilConfig keeps the helper safe for the
+// zero-value paths.
+func TestNormalizeAgentReasoningEffortNilConfig(t *testing.T) {
+ if err := normalizeAgentReasoningEffort(nil); err != nil {
+ t.Fatalf("nil config should be a no-op, got %v", err)
+ }
+}
diff --git a/internal/handler/dto/model.go b/internal/handler/dto/model.go
index c38bad3d1..e982c893b 100644
--- a/internal/handler/dto/model.go
+++ b/internal/handler/dto/model.go
@@ -2,11 +2,172 @@ package dto
import (
"context"
+ "strings"
"time"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/types"
)
+// VendorRef identifies the vendor a set of model parameters belongs to.
+// BaseURL covers legacy rows saved before provider was stored; the vendor is
+// then detected from the endpoint.
+type VendorRef struct {
+ Provider string
+ BaseURL string
+}
+
+// vendorID resolves the ref to a comparable vendor id. An id that matches no
+// registered vendor is returned as typed, so two rows pinned to the same
+// hand-written provider still compare equal.
+func (r VendorRef) vendorID() string {
+ id := strings.ToLower(strings.TrimSpace(r.Provider))
+ if id == "" {
+ id = catalog.DetectByURL(r.BaseURL)
+ }
+ return id
+}
+
+// names reports whether the ref identifies a vendor at all. A PUT body that
+// carries neither provider nor base URL names none, and must not be read as
+// "the user moved this row to another vendor".
+func (r VendorRef) names() bool {
+ return strings.TrimSpace(r.Provider) != "" || strings.TrimSpace(r.BaseURL) != ""
+}
+
+func secretKeysOf(v *catalog.Vendor, into map[string]bool) map[string]bool {
+ for _, f := range v.ExtraFields {
+ if !f.Secret && f.Type != "password" {
+ continue
+ }
+ if into == nil {
+ into = map[string]bool{}
+ }
+ into[f.Key] = true
+ }
+ return into
+}
+
+// SecretExtraConfigKeys returns the extra_config keys the vendor declares as
+// secret (catalog.ExtraField.Secret, or a password input). These are real
+// credentials — LKEAP and Volcengine rerank keep an IAM/CAM secret key there
+// — so they get the same treatment as api_key / app_secret: never echoed,
+// only reported as present.
+//
+// The field's ModelTypes restriction is deliberately ignored: a key that is
+// secret for any model type of the vendor is redacted for every row of that
+// vendor.
+func SecretExtraConfigKeys(provider, baseURL string) map[string]bool {
+ v, ok := catalog.Get(VendorRef{Provider: provider, BaseURL: baseURL}.vendorID())
+ if !ok {
+ return nil
+ }
+ return secretKeysOf(v, nil)
+}
+
+// AllSecretExtraConfigKeys returns every extra_config key any registered
+// vendor declares secret.
+//
+// Redaction must not depend on the row's own provider being the one that
+// declared the key: a row whose provider was switched, hand-edited or never
+// stored would otherwise echo a credential in plaintext simply because its
+// current vendor declares no secret field. Treating a name that is secret
+// somewhere as secret everywhere is the safe direction — the worst case is
+// withholding a value that happened to reuse the name.
+func AllSecretExtraConfigKeys() map[string]bool {
+ var keys map[string]bool
+ for _, v := range catalog.List() {
+ keys = secretKeysOf(v, keys)
+ }
+ return keys
+}
+
+// redactedSecretPlaceholder reports whether an incoming extra_config value
+// carries no new secret: empty, or a mask the UI shows for a value it never
+// received (GET omits the key entirely, but forms happily render bullets).
+func redactedSecretPlaceholder(v string) bool {
+ t := strings.TrimSpace(v)
+ return t == "" || strings.Trim(t, "*•·●") == ""
+}
+
+// PreserveStoredSecretExtras merges the stored secret extra_config values
+// into an incoming map.
+//
+// PUT /models/{id} replaces extra_config wholesale and the frontend always
+// sends the map for remote rows, but GET redacts the vendor's secret fields,
+// so a plain edit-and-save round-trip carries no value for them. Without this
+// merge the first save after any unrelated edit would erase the stored secret
+// key and break rerank for that row. An incoming value that is absent, empty
+// or a mask means "unchanged"; anything else replaces the stored secret.
+//
+// storedVendor identifies the vendor the stored values belong to; edited is
+// the vendor the incoming values are for. They differ when the user moves the
+// row to another vendor, and then the stored credential must be dropped
+// rather than carried over: it belongs to the previous integration's account,
+// the editor no longer renders a field for it, and the new vendor may not
+// declare it secret at all — which is how it ended up echoed in plaintext.
+//
+// incoming is filled in place and returned.
+func PreserveStoredSecretExtras(
+ stored, incoming map[string]string, storedVendor, edited VendorRef,
+) map[string]string {
+ keys := SecretExtraConfigKeys(storedVendor.Provider, storedVendor.BaseURL)
+ // A request that names no vendor at all changed none: keep the old
+ // contract, which rerank rows rely on for their redacted secret.
+ switched := edited.names() && edited.vendorID() != storedVendor.vendorID()
+ if incoming == nil {
+ if !switched || len(keys) == 0 || len(stored) == 0 {
+ return stored
+ }
+ // extra_config omitted entirely still keeps the rest of the stored
+ // map, but not the previous vendor's credential.
+ out := make(map[string]string, len(stored))
+ for k, v := range stored {
+ if !keys[k] {
+ out[k] = v
+ }
+ }
+ return out
+ }
+ if len(keys) == 0 {
+ return incoming
+ }
+ if switched {
+ // Only a value the user actually typed survives a vendor switch; an
+ // absent or masked one would otherwise resurrect the old secret when
+ // the new vendor happens to reuse the key name.
+ for key := range keys {
+ if redactedSecretPlaceholder(incoming[key]) {
+ delete(incoming, key)
+ }
+ }
+ return incoming
+ }
+ for key := range keys {
+ storedValue := stored[key]
+ if storedValue == "" {
+ continue
+ }
+ if redactedSecretPlaceholder(incoming[key]) {
+ incoming[key] = storedValue
+ }
+ }
+ return incoming
+}
+
+// HasAllSecretExtras reports whether extra already carries a usable value for
+// every secret extra field the vendor declares. Callers that would otherwise
+// skip a lookup of the stored row use it to notice that the request is
+// missing a redacted secret.
+func HasAllSecretExtras(provider, baseURL string, extra map[string]string) bool {
+ for key := range SecretExtraConfigKeys(provider, baseURL) {
+ if redactedSecretPlaceholder(extra[key]) {
+ return false
+ }
+ }
+ return true
+}
+
// ModelResponse mirrors types.Model for response bodies, with all secret
// fields (APIKey, AppSecret) removed by construction. Credential presence
// metadata lives behind the /credentials subresource, not inlined here.
@@ -32,6 +193,9 @@ type ModelResponse struct {
// Per-field "configured?" map. Omitted for builtin models unless the
// caller is a system administrator. See MCPServiceResponse.Credentials.
Credentials map[string]CredentialFieldMetadata `json:"credentials,omitempty"`
+ // Capabilities is the catalog view of the model: protocol, whether it
+ // can think and at which levels, context window. Chat models only.
+ Capabilities *catalog.Capabilities `json:"capabilities,omitempty"`
}
// ModelParametersDTO carries every parameter field EXCEPT the two secret
@@ -51,6 +215,7 @@ type ModelParametersDTO struct {
MaxOutputTokens int `json:"max_output_tokens,omitempty"`
MaxConcurrency int `json:"max_concurrency,omitempty"`
AppID string `json:"app_id,omitempty"`
+ Spec *types.ModelSpecOverride `json:"spec,omitempty"`
}
// NewModelResponse converts a stored Model into its response shape.
@@ -74,12 +239,18 @@ func NewModelResponse(ctx context.Context, m *types.Model) *ModelResponse {
MaxOutputTokens: m.Parameters.MaxOutputTokens,
MaxConcurrency: m.Parameters.MaxConcurrency,
AppID: m.Parameters.AppID,
+ Spec: m.Parameters.Spec,
}
canManageBuiltin := m.IsBuiltin && types.IsSystemAdminFromContext(ctx)
if !CanViewIntegrationSecrets(ctx) && !canManageBuiltin {
params.ExtraConfig = nil
params.CustomHeaders = nil
params.BaseURL = ""
+ // Spec is deployment configuration of the same kind: it pins the
+ // protocol and carries the compat overlay, whose extra_body is
+ // merged verbatim into every request. It belongs with ExtraConfig,
+ // not with the capability fields kept below.
+ params.Spec = nil
}
if m.IsBuiltin && !canManageBuiltin {
// Builtin: strip everything that could reveal per-tenant config.
@@ -91,6 +262,27 @@ func NewModelResponse(ctx context.Context, m *types.Model) *ModelResponse {
params.ExtraConfig = nil
params.CustomHeaders = nil
params.AppID = ""
+ params.Spec = nil
+ }
+ // Vendor-declared secret extra fields are credentials that happen to be
+ // stored in extra_config. Drop them from the echoed map — even for
+ // callers allowed to see integration detail, exactly as api_key is
+ // withheld from an admin — and report presence instead. The stored map is
+ // never mutated: params.ExtraConfig still aliases it here.
+ //
+ // Redaction spans every registered vendor, not just this row's: a row
+ // whose provider was switched or hand-edited must not leak a leftover
+ // credential just because its current vendor declares no secret field.
+ secretKeys := SecretExtraConfigKeys(m.Parameters.Provider, m.Parameters.BaseURL)
+ redactKeys := AllSecretExtraConfigKeys()
+ if len(redactKeys) > 0 && len(params.ExtraConfig) > 0 {
+ sanitized := make(map[string]string, len(params.ExtraConfig))
+ for k, v := range params.ExtraConfig {
+ if !redactKeys[k] {
+ sanitized[k] = v
+ }
+ }
+ params.ExtraConfig = sanitized
}
var creds map[string]CredentialFieldMetadata
if !m.IsBuiltin || canManageBuiltin {
@@ -98,22 +290,49 @@ func NewModelResponse(ctx context.Context, m *types.Model) *ModelResponse {
"api_key": {Configured: m.Parameters.APIKey != ""},
"app_secret": {Configured: m.Parameters.AppSecret != ""},
}
+ for key := range secretKeys {
+ creds[key] = CredentialFieldMetadata{
+ Configured: strings.TrimSpace(m.Parameters.ExtraConfig[key]) != "",
+ }
+ }
+ // A key this row's vendor does not declare was still withheld above,
+ // so say it is there — otherwise the value silently vanishes from the
+ // editor with nothing to explain why.
+ for key := range redactKeys {
+ if _, reported := creds[key]; reported {
+ continue
+ }
+ if strings.TrimSpace(m.Parameters.ExtraConfig[key]) != "" {
+ creds[key] = CredentialFieldMetadata{Configured: true}
+ }
+ }
+ }
+ var caps *catalog.Capabilities
+ if m.Type == types.ModelTypeKnowledgeQA || m.Type == types.ModelTypeVLLM {
+ if resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: m.Parameters.Provider, Model: m.Name, BaseURL: m.Parameters.BaseURL,
+ ModelType: m.Type, Extra: m.Parameters.ExtraConfig, Override: m.Parameters.Spec,
+ }); err == nil && m.Source == types.ModelSourceRemote {
+ c := resolved.Capabilities()
+ caps = &c
+ }
}
return &ModelResponse{
- ID: m.ID,
- TenantID: m.TenantID,
- Name: m.Name,
- DisplayName: m.DisplayName,
- Type: m.Type,
- Source: m.Source,
- Description: m.Description,
- Parameters: params,
- IsDefault: m.IsDefault,
- IsBuiltin: m.IsBuiltin,
- Status: m.Status,
- CreatedAt: m.CreatedAt,
- UpdatedAt: m.UpdatedAt,
- Credentials: creds,
+ ID: m.ID,
+ TenantID: m.TenantID,
+ Name: m.Name,
+ DisplayName: m.DisplayName,
+ Type: m.Type,
+ Source: m.Source,
+ Description: m.Description,
+ Parameters: params,
+ IsDefault: m.IsDefault,
+ IsBuiltin: m.IsBuiltin,
+ Status: m.Status,
+ CreatedAt: m.CreatedAt,
+ UpdatedAt: m.UpdatedAt,
+ Credentials: creds,
+ Capabilities: caps,
}
}
diff --git a/internal/handler/dto/model_test.go b/internal/handler/dto/model_test.go
index 33aaa6773..6af628347 100644
--- a/internal/handler/dto/model_test.go
+++ b/internal/handler/dto/model_test.go
@@ -6,6 +6,7 @@ import (
"strings"
"testing"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
@@ -116,7 +117,224 @@ func TestModelResponse_ViewerStripsIntegrationDetail(t *testing.T) {
assert.Nil(t, resp.Parameters.ExtraConfig)
}
+// registerSecretExtraVendor adds a vendor whose extra_config carries a real
+// credential, the way LKEAP / Volcengine rerank declare secret_key.
+func registerSecretExtraVendor(t *testing.T) string {
+ t.Helper()
+ id := "dto-secret-extra-vendor"
+ catalog.Register(&catalog.Vendor{
+ ID: id,
+ Name: "Secret Extra Vendor",
+ ModelTypes: []types.ModelType{types.ModelTypeRerank},
+ URLPatterns: []string{"secret-extra-vendor.example.com"},
+ ExtraFields: []catalog.ExtraField{
+ {Key: "secret_key", Label: "Secret Key", Type: "password", Secret: true},
+ {Key: "region", Label: "Region", Type: "string"},
+ },
+ })
+ return id
+}
+
+// A vendor-declared secret extra field is a credential that happens to live
+// in extra_config: GET must report its presence, never its value — even to a
+// caller allowed to see integration detail, exactly like api_key.
+func TestModelResponse_RedactsVendorSecretExtraConfig(t *testing.T) {
+ provider := registerSecretExtraVendor(t)
+ m := &types.Model{
+ ID: "m-rerank",
+ Type: types.ModelTypeRerank,
+ Parameters: types.ModelParameters{
+ Provider: provider,
+ BaseURL: "https://secret-extra-vendor.example.com",
+ APIKey: "AKID-public-id",
+ ExtraConfig: map[string]string{
+ "secret_key": "cam-secret-do-not-leak",
+ "region": "ap-guangzhou",
+ },
+ },
+ }
+ resp := NewModelResponse(adminContext(), m)
+
+ assert.NotContains(t, resp.Parameters.ExtraConfig, "secret_key")
+ assert.Equal(t, "ap-guangzhou", resp.Parameters.ExtraConfig["region"],
+ "non-secret extra fields still round-trip")
+ assert.True(t, resp.Credentials["secret_key"].Configured,
+ "presence is reported in the same shape as api_key")
+
+ body, err := json.Marshal(resp)
+ require.NoError(t, err)
+ assert.NotContains(t, string(body), "cam-secret-do-not-leak")
+
+ assert.Equal(t, "cam-secret-do-not-leak", m.Parameters.ExtraConfig["secret_key"],
+ "the stored model must not be mutated by rendering a response")
+}
+
+func TestModelResponse_SecretExtraConfigReportsAbsence(t *testing.T) {
+ provider := registerSecretExtraVendor(t)
+ m := &types.Model{
+ ID: "m-rerank",
+ Type: types.ModelTypeRerank,
+ Parameters: types.ModelParameters{Provider: provider, ExtraConfig: map[string]string{"region": "ap-beijing"}},
+ }
+ resp := NewModelResponse(adminContext(), m)
+ assert.False(t, resp.Credentials["secret_key"].Configured)
+ assert.Equal(t, "ap-beijing", resp.Parameters.ExtraConfig["region"])
+}
+
+// Legacy rows saved before provider was stored are matched by endpoint.
+func TestModelResponse_RedactsSecretExtraConfigForLegacyRowWithoutProvider(t *testing.T) {
+ registerSecretExtraVendor(t)
+ m := &types.Model{
+ ID: "m-legacy",
+ Type: types.ModelTypeRerank,
+ Parameters: types.ModelParameters{
+ BaseURL: "https://secret-extra-vendor.example.com/v1",
+ ExtraConfig: map[string]string{"secret_key": "cam-secret-do-not-leak"},
+ },
+ }
+ resp := NewModelResponse(adminContext(), m)
+ assert.NotContains(t, resp.Parameters.ExtraConfig, "secret_key")
+ assert.True(t, resp.Credentials["secret_key"].Configured)
+}
+
+// PUT replaces extra_config wholesale and GET redacts the secret, so the
+// save that follows an unrelated edit must not erase the stored key.
+func TestPreserveStoredSecretExtras(t *testing.T) {
+ provider := registerSecretExtraVendor(t)
+ stored := map[string]string{"secret_key": "cam-secret-stored", "region": "ap-guangzhou"}
+ sameVendor := VendorRef{Provider: provider}
+
+ t.Run("incoming omits the key", func(t *testing.T) {
+ got := PreserveStoredSecretExtras(
+ stored, map[string]string{"region": "ap-beijing"}, sameVendor, sameVendor)
+ assert.Equal(t, "cam-secret-stored", got["secret_key"])
+ assert.Equal(t, "ap-beijing", got["region"], "non-secret edits still apply")
+ })
+ t.Run("incoming carries an empty or masked value", func(t *testing.T) {
+ for _, masked := range []string{"", " ", "******", "••••"} {
+ got := PreserveStoredSecretExtras(
+ stored, map[string]string{"secret_key": masked}, sameVendor, sameVendor)
+ assert.Equal(t, "cam-secret-stored", got["secret_key"], "masked value %q means unchanged", masked)
+ }
+ })
+ t.Run("incoming carries a new value", func(t *testing.T) {
+ got := PreserveStoredSecretExtras(
+ stored, map[string]string{"secret_key": "cam-secret-rotated"}, sameVendor, sameVendor)
+ assert.Equal(t, "cam-secret-rotated", got["secret_key"])
+ })
+ t.Run("nil incoming keeps the whole stored map", func(t *testing.T) {
+ assert.Equal(t, stored, PreserveStoredSecretExtras(stored, nil, sameVendor, sameVendor))
+ })
+ t.Run("unknown stored provider passes the map through", func(t *testing.T) {
+ in := map[string]string{"secret_key": ""}
+ assert.Equal(t, in,
+ PreserveStoredSecretExtras(stored, in, VendorRef{Provider: "no-such-vendor"}, sameVendor))
+ })
+ t.Run("a request naming no vendor is not a vendor change", func(t *testing.T) {
+ got := PreserveStoredSecretExtras(stored, map[string]string{}, sameVendor, VendorRef{})
+ assert.Equal(t, "cam-secret-stored", got["secret_key"])
+ })
+
+ // Switching the row to another vendor leaves the credential behind: it
+ // authenticates the account of the integration being replaced.
+ t.Run("vendor change drops the stored secret", func(t *testing.T) {
+ other := VendorRef{Provider: "openai"}
+ got := PreserveStoredSecretExtras(stored, map[string]string{"api": "openai_completions"}, sameVendor, other)
+ assert.NotContains(t, got, "secret_key")
+ assert.Equal(t, "openai_completions", got["api"])
+ })
+ t.Run("vendor change drops a masked secret instead of refilling it", func(t *testing.T) {
+ other := VendorRef{Provider: "openai"}
+ got := PreserveStoredSecretExtras(stored, map[string]string{"secret_key": "****"}, sameVendor, other)
+ assert.NotContains(t, got, "secret_key")
+ })
+ t.Run("vendor change keeps a value the user typed", func(t *testing.T) {
+ other := VendorRef{Provider: "openai"}
+ got := PreserveStoredSecretExtras(stored, map[string]string{"secret_key": "typed-now"}, sameVendor, other)
+ assert.Equal(t, "typed-now", got["secret_key"])
+ })
+ t.Run("vendor change with no extra_config at all", func(t *testing.T) {
+ got := PreserveStoredSecretExtras(stored, nil, sameVendor, VendorRef{Provider: "openai"})
+ assert.NotContains(t, got, "secret_key")
+ assert.Equal(t, "ap-guangzhou", got["region"], "non-secret settings are not credentials")
+ assert.Equal(t, "cam-secret-stored", stored["secret_key"], "the stored map is not mutated")
+ })
+ t.Run("a legacy row is matched by endpoint, not treated as a switch", func(t *testing.T) {
+ legacy := VendorRef{BaseURL: "https://secret-extra-vendor.example.com/v1"}
+ got := PreserveStoredSecretExtras(stored, map[string]string{}, legacy, legacy)
+ assert.Equal(t, "cam-secret-stored", got["secret_key"])
+ })
+}
+
+// Redaction may not depend on the row's provider being the one that declared
+// the key: a hand-edited or emptied provider would otherwise echo a stored
+// credential in plaintext.
+func TestModelResponse_RedactsSecretExtraDeclaredByAnotherVendor(t *testing.T) {
+ registerSecretExtraVendor(t)
+ for _, provider := range []string{"openai", ""} {
+ m := &types.Model{
+ ID: "m-switched",
+ Type: types.ModelTypeRerank,
+ Parameters: types.ModelParameters{
+ Provider: provider,
+ ExtraConfig: map[string]string{"secret_key": "cam-secret-do-not-leak", "region": "ap-beijing"},
+ },
+ }
+ resp := NewModelResponse(adminContext(), m)
+ body, err := json.Marshal(resp)
+ require.NoError(t, err)
+ assert.NotContains(t, string(body), "cam-secret-do-not-leak", "provider %q", provider)
+ assert.Equal(t, "ap-beijing", resp.Parameters.ExtraConfig["region"])
+ assert.True(t, resp.Credentials["secret_key"].Configured,
+ "a withheld value is still reported as present")
+ }
+}
+
+func TestHasAllSecretExtras(t *testing.T) {
+ provider := registerSecretExtraVendor(t)
+ assert.True(t, HasAllSecretExtras(provider, "", map[string]string{"secret_key": "cam-secret"}))
+ assert.False(t, HasAllSecretExtras(provider, "", map[string]string{"region": "ap-guangzhou"}))
+ assert.False(t, HasAllSecretExtras(provider, "", map[string]string{"secret_key": "****"}))
+ assert.True(t, HasAllSecretExtras("no-such-vendor", "", nil), "a vendor with no secret extras is complete")
+}
+
func TestModelResponse_NilSafe(t *testing.T) {
assert.Nil(t, NewModelResponse(adminContext(), nil))
assert.Equal(t, []*ModelResponse{}, NewModelResponses(adminContext(), nil))
}
+
+func TestNewModelResponseStripsSpecFromNonAdmins(t *testing.T) {
+ // Spec pins the protocol and carries the compat overlay, whose
+ // extra_body is merged verbatim into every request. It is deployment
+ // configuration, like base_url and extra_config beside it, not part of
+ // the capability surface a viewer is shown.
+ spec := &types.ModelSpecOverride{
+ API: "anthropic-messages",
+ Compat: map[string]any{"extra_body": map[string]any{"internal_route": "eu-gateway"}},
+ }
+ model := &types.Model{
+ ID: "m1", Name: "claude-sonnet-4-5", Type: types.ModelTypeKnowledgeQA,
+ Source: types.ModelSourceRemote,
+ Parameters: types.ModelParameters{
+ Provider: "anthropic", BaseURL: "https://gateway.internal/v1", Spec: spec,
+ },
+ }
+
+ admin := context.WithValue(context.Background(), types.TenantRoleContextKey, types.TenantRoleAdmin)
+ if got := NewModelResponse(admin, model).Parameters.Spec; got == nil {
+ t.Fatalf("an admin configures this; it must still be returned")
+ }
+
+ viewer := context.WithValue(context.Background(), types.TenantRoleContextKey, types.TenantRoleViewer)
+ params := NewModelResponse(viewer, model).Parameters
+ if params.Spec != nil {
+ t.Errorf("viewer should not see the protocol override, got %+v", params.Spec)
+ }
+ if params.BaseURL != "" || params.ExtraConfig != nil {
+ t.Errorf("the neighbouring fields should still be stripped")
+ }
+ // The stored model is shared; stripping must not mutate it.
+ if model.Parameters.Spec == nil {
+ t.Errorf("NewModelResponse must not clear the stored spec")
+ }
+}
diff --git a/internal/handler/initialization.go b/internal/handler/initialization.go
index 2cfd3b21e..03f604817 100644
--- a/internal/handler/initialization.go
+++ b/internal/handler/initialization.go
@@ -603,7 +603,12 @@ func (h *InitializationHandler) InitializeByKB(c *gin.Context) {
"success": true,
"message": "知识库配置更新成功",
"data": gin.H{
- "models": processedModels,
+ // Through the response DTO, like every other body carrying a
+ // model: types.Model marshals api_key in plaintext, and now that
+ // the reuse path keeps the stored credential instead of
+ // overwriting it, echoing the row would hand back a key the
+ // caller never submitted. KnowledgeBase redacts itself.
+ "models": dto.NewModelResponses(ctx, processedModels),
"knowledge_base": kb,
},
})
@@ -855,7 +860,7 @@ func (h *InitializationHandler) processInitializationModels(
existingModel.Name = model.Name
existingModel.Source = model.Source
existingModel.Description = model.Description
- existingModel.Parameters = model.Parameters
+ descriptor.applyToStoredParameters(&existingModel.Parameters)
existingModel.UpdatedAt = time.Now()
if err := h.modelService.UpdateModel(ctx, existingModel); err != nil {
@@ -882,6 +887,32 @@ func (h *InitializationHandler) processInitializationModels(
return processedModels, nil
}
+// applyToStoredParameters merges the initialization payload into the
+// parameters of a model row that already exists.
+//
+// The wizard collects four fields (endpoint, key, interface type, embedding
+// dimension); everything else on the row — provider, extra_config, custom
+// headers, spec, concurrency, context window — was configured in the model
+// editor. Assigning toModel()'s parameters wholesale erased all of it, and
+// blanked the stored API key whenever the payload carried none, so a KB that
+// was merely re-initialized came back with a model nobody could call. Only
+// the fields the payload actually carries are written; an empty one means
+// "not submitted", not "clear it".
+func (descriptor modelDescriptor) applyToStoredParameters(params *types.ModelParameters) {
+ if descriptor.baseURL != "" {
+ params.BaseURL = descriptor.baseURL
+ }
+ if descriptor.apiKey != "" {
+ params.APIKey = descriptor.apiKey
+ }
+ if descriptor.interfaceType != "" {
+ params.InterfaceType = descriptor.interfaceType
+ }
+ if descriptor.modelType == types.ModelTypeEmbedding && descriptor.dimension > 0 {
+ params.EmbeddingParameters.Dimension = descriptor.dimension
+ }
+}
+
func (descriptor modelDescriptor) toModel() *types.Model {
model := &types.Model{
Type: descriptor.modelType,
@@ -1770,7 +1801,12 @@ func (h *InitializationHandler) fillSecretsFromStoredModel(ctx context.Context,
if req == nil || req.ModelID == "" {
return
}
- if req.APIKey != "" && req.AppSecret != "" && req.ExtraConfig != nil {
+ // A request that already carries every secret needs no lookup — but a
+ // secret stored in extra_config (LKEAP / Volcengine secret_key) is
+ // redacted by GET, so "extraConfig is present" does not mean it is
+ // complete.
+ if req.APIKey != "" && req.AppSecret != "" && req.ExtraConfig != nil &&
+ dto.HasAllSecretExtras(req.Provider, req.BaseURL, req.ExtraConfig) {
return
}
stored, err := h.modelService.GetModelByID(ctx, req.ModelID)
@@ -1785,9 +1821,15 @@ func (h *InitializationHandler) fillSecretsFromStoredModel(ctx context.Context,
if req.AppSecret == "" {
req.AppSecret = stored.Parameters.AppSecret
}
- if req.ExtraConfig == nil {
- req.ExtraConfig = stored.Parameters.ExtraConfig
- }
+ // Same contract as PUT /models/{id}: an absent or masked secret extra
+ // falls back to the stored value, a real one the user just typed wins —
+ // and a test against a different vendor gets no stored credential, which
+ // belongs to the integration the row is being moved away from.
+ req.ExtraConfig = dto.PreserveStoredSecretExtras(
+ stored.Parameters.ExtraConfig, req.ExtraConfig,
+ dto.VendorRef{Provider: stored.Parameters.Provider, BaseURL: stored.Parameters.BaseURL},
+ dto.VendorRef{Provider: req.Provider, BaseURL: req.BaseURL},
+ )
}
// RemoteModelCheckRequest 兼容旧 swagger 定义。
diff --git a/internal/handler/initialization_model_merge_test.go b/internal/handler/initialization_model_merge_test.go
new file mode 100644
index 000000000..97630fc1b
--- /dev/null
+++ b/internal/handler/initialization_model_merge_test.go
@@ -0,0 +1,215 @@
+package handler
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ secutils "github.com/Tencent/WeKnora/internal/utils"
+ "github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// Re-initializing a KB used to assign the wizard's four fields over the whole
+// parameter struct of the stored row, erasing everything the model editor
+// owns (provider, extra_config, custom headers, spec, concurrency, context
+// window) and blanking the API key whenever the payload carried none.
+
+func storedEditorConfiguredModel() *types.Model {
+ return &types.Model{
+ ID: "m-llm", Type: types.ModelTypeKnowledgeQA, Name: "gpt-4o",
+ TenantID: 10042, Source: types.ModelSourceRemote,
+ Parameters: types.ModelParameters{
+ Provider: "azure",
+ BaseURL: "https://old.example.com/v1",
+ APIKey: "stored-key",
+ ExtraConfig: map[string]string{
+ "api_version": "2024-06-01",
+ "secret_key": "cam-secret-stored",
+ },
+ CustomHeaders: map[string]string{"X-Team": "rag"},
+ MaxConcurrency: 4,
+ ContextWindow: 128000,
+ Spec: &types.ModelSpecOverride{API: "openai-completions"},
+ },
+ }
+}
+
+// initExistingLLM runs processInitializationModels against a KB whose LLM
+// slot already points at stored, and returns the row it persisted.
+func initExistingLLM(t *testing.T, stored *types.Model, mutate func(*InitializationRequest)) *types.Model {
+ t.Helper()
+ svc := &stubTenantStampModelService{}
+ svc.getModelByID = func(_ context.Context, id string) (*types.Model, error) {
+ if id == stored.ID {
+ return stored, nil
+ }
+ return nil, nil
+ }
+ h := &InitializationHandler{modelService: svc}
+ kb := &types.KnowledgeBase{ID: "kb-1", TenantID: 10042, SummaryModelID: stored.ID}
+
+ req := newTenantStampRequest()
+ if mutate != nil {
+ mutate(req)
+ }
+ _, err := h.processInitializationModels(context.Background(), kb, "kb-1", req)
+ require.NoError(t, err)
+ require.NotEmpty(t, svc.updated, "the existing model was not updated")
+ return svc.updated[0]
+}
+
+func TestProcessInitializationModelsKeepsEditorOwnedParameters(t *testing.T) {
+ stored := storedEditorConfiguredModel()
+ updated := initExistingLLM(t, stored, func(req *InitializationRequest) {
+ req.LLM.APIKey = "" // the wizard re-submits without re-typing the key
+ req.LLM.BaseURL = "https://new.example.com/v1"
+ })
+
+ p := updated.Parameters
+ assert.Equal(t, "https://new.example.com/v1", p.BaseURL, "the endpoint edit must still land")
+ assert.Equal(t, "stored-key", p.APIKey, "an omitted key means unchanged, not cleared")
+ assert.Equal(t, "azure", p.Provider)
+ assert.Equal(t, "2024-06-01", p.ExtraConfig["api_version"])
+ assert.Equal(t, "cam-secret-stored", p.ExtraConfig["secret_key"])
+ assert.Equal(t, map[string]string{"X-Team": "rag"}, p.CustomHeaders)
+ assert.Equal(t, 4, p.MaxConcurrency)
+ assert.Equal(t, 128000, p.ContextWindow)
+ assert.NotNil(t, p.Spec)
+}
+
+// Initialization's own purpose still works: endpoint and key are writable.
+func TestProcessInitializationModelsStillAppliesSubmittedFields(t *testing.T) {
+ stored := storedEditorConfiguredModel()
+ updated := initExistingLLM(t, stored, func(req *InitializationRequest) {
+ req.LLM.APIKey = "rotated-key"
+ req.LLM.BaseURL = "https://new.example.com/v1"
+ })
+ assert.Equal(t, "rotated-key", updated.Parameters.APIKey)
+ assert.Equal(t, "https://new.example.com/v1", updated.Parameters.BaseURL)
+}
+
+// The embedding slot carries a dimension, and changing it is the one reason
+// an operator re-runs initialization against an existing embedding row.
+func TestProcessInitializationModelsAppliesEmbeddingDimension(t *testing.T) {
+ stored := &types.Model{
+ ID: "m-embed", Type: types.ModelTypeEmbedding, Name: "bge-m3", TenantID: 10042,
+ Source: types.ModelSourceRemote,
+ Parameters: types.ModelParameters{
+ Provider: "siliconflow",
+ BaseURL: "https://old.example.com/v1",
+ APIKey: "stored-key",
+ ExtraConfig: map[string]string{"remote_model_name": "BAAI/bge-m3"},
+ EmbeddingParameters: types.EmbeddingParameters{Dimension: 768, TruncatePromptTokens: 512},
+ },
+ }
+ svc := &stubTenantStampModelService{}
+ svc.getModelByID = func(_ context.Context, id string) (*types.Model, error) {
+ if id == "m-embed" {
+ return stored, nil
+ }
+ return nil, nil
+ }
+ h := &InitializationHandler{modelService: svc}
+ kb := &types.KnowledgeBase{ID: "kb-1", TenantID: 10042, EmbeddingModelID: "m-embed"}
+
+ req := newTenantStampRequest()
+ req.Embedding.Dimension = 1024
+ req.Embedding.APIKey = ""
+ _, err := h.processInitializationModels(context.Background(), kb, "kb-1", req)
+ require.NoError(t, err)
+ require.NotEmpty(t, svc.updated)
+
+ p := svc.updated[0].Parameters
+ assert.Equal(t, 1024, p.EmbeddingParameters.Dimension, "the dimension edit must still land")
+ assert.Equal(t, 512, p.EmbeddingParameters.TruncatePromptTokens,
+ "the rest of the embedding parameters is not part of the payload")
+ assert.Equal(t, "BAAI/bge-m3", p.ExtraConfig["remote_model_name"])
+ assert.Equal(t, "stored-key", p.APIKey)
+}
+
+type stubInitKBService struct {
+ interfaces.KnowledgeBaseService
+ kb *types.KnowledgeBase
+}
+
+func (s *stubInitKBService) GetKnowledgeBaseByID(context.Context, string) (*types.KnowledgeBase, error) {
+ return s.kb, nil
+}
+
+type stubInitKBRepository struct {
+ interfaces.KnowledgeBaseRepository
+}
+
+func (s *stubInitKBRepository) UpdateKnowledgeBase(context.Context, *types.KnowledgeBase) error {
+ return nil
+}
+
+// POST /initialization/initialize/{kbId} used to marshal the raw model rows,
+// and types.Model carries api_key in plaintext. Now that the reuse path keeps
+// the stored credential rather than overwriting it with the payload's, that
+// body would hand back a key the caller never submitted.
+func TestInitializeByKB_ResponseDoesNotEchoStoredAPIKey(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ stored := storedEditorConfiguredModel()
+ svc := &stubTenantStampModelService{}
+ svc.getModelByID = func(_ context.Context, id string) (*types.Model, error) {
+ if id == stored.ID {
+ return stored, nil
+ }
+ return nil, nil
+ }
+ kb := &types.KnowledgeBase{ID: "kb-1", TenantID: 10042, SummaryModelID: stored.ID}
+ h := &InitializationHandler{
+ modelService: svc,
+ kbService: &stubInitKBService{kb: kb},
+ kbRepository: &stubInitKBRepository{},
+ }
+
+ req := newTenantStampRequest()
+ req.LLM.APIKey = ""
+ // The full handler runs SSRF validation, which would otherwise resolve
+ // the host over the network. Whitelist one name of our own and clear it
+ // again, so no other test in this package sees a relaxed check.
+ secutils.SetSSRFWhitelistFromRaw("init-merge-test.example.com")
+ t.Cleanup(func() { secutils.SetSSRFWhitelistFromRaw("") })
+ req.LLM.BaseURL = "https://init-merge-test.example.com/v1"
+ req.Embedding.BaseURL = "https://init-merge-test.example.com/v1"
+ req.DocumentSplitting.ChunkSize = 512
+ req.DocumentSplitting.ChunkOverlap = 64
+ req.DocumentSplitting.Separators = []string{"\n"}
+ body, err := json.Marshal(req)
+ require.NoError(t, err)
+
+ w := httptest.NewRecorder()
+ c, _ := gin.CreateTestContext(w)
+ c.Request = httptest.NewRequest(http.MethodPost, "/api/v1/initialization/initialize/kb-1", bytes.NewReader(body))
+ c.Request.Header.Set("Content-Type", "application/json")
+ c.Request = c.Request.WithContext(types.WithCaller(c.Request.Context(), types.Caller{
+ TenantID: 10042, UserID: "u-1", Role: types.TenantRoleAdmin,
+ }))
+ c.Params = gin.Params{{Key: "kbId", Value: "kb-1"}}
+
+ h.InitializeByKB(c)
+ require.Empty(t, c.Errors.Errors())
+ require.Equal(t, http.StatusOK, w.Code)
+ assert.NotContains(t, w.Body.String(), "stored-key")
+ assert.NotContains(t, w.Body.String(), "cam-secret-stored")
+ assert.Contains(t, w.Body.String(), stored.ID, "the model ids the caller needs are still returned")
+}
+
+// A rerank row is never reached by this path at all: the KB has no rerank
+// slot, so findExistingModelID has nothing to return and every run creates a
+// fresh row. Pinning it keeps the reasoning above honest if a slot is added.
+func TestFindExistingModelIDHasNoRerankSlot(t *testing.T) {
+ h := &InitializationHandler{}
+ kb := &types.KnowledgeBase{SummaryModelID: "m-llm", EmbeddingModelID: "m-embed"}
+ assert.Empty(t, h.findExistingModelID(kb, types.ModelTypeRerank))
+ assert.Equal(t, "m-llm", h.findExistingModelID(kb, types.ModelTypeKnowledgeQA))
+}
diff --git a/internal/handler/model.go b/internal/handler/model.go
index df50b7a34..b7b99daef 100644
--- a/internal/handler/model.go
+++ b/internal/handler/model.go
@@ -12,8 +12,9 @@ import (
"github.com/Tencent/WeKnora/internal/errors"
"github.com/Tencent/WeKnora/internal/handler/dto"
"github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/models/chat"
- "github.com/Tencent/WeKnora/internal/models/provider"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
secutils "github.com/Tencent/WeKnora/internal/utils"
@@ -92,6 +93,10 @@ func (h *ModelHandler) CreateModel(c *gin.Context) {
return
}
}
+ if err := validateCatalogParameters(req.Name, req.Type, &req.Parameters); err != nil {
+ _ = c.Error(errors.NewBadRequestError(err.Error()))
+ return
+ }
model := &types.Model{
TenantID: tenantID,
@@ -215,6 +220,8 @@ type ModelDebugOptions struct {
TopP *float64 `json:"top_p,omitempty"`
MaxTokens *int `json:"max_tokens,omitempty"`
Thinking *bool `json:"thinking,omitempty"`
+ // ReasoningEffort is the graded level; when set it overrides Thinking.
+ ReasoningEffort string `json:"reasoning_effort,omitempty"`
}
func parseModelDebugOptions(raw string) (ModelDebugOptions, error) {
@@ -234,15 +241,29 @@ func parseModelDebugOptions(raw string) (ModelDebugOptions, error) {
if opts.TopP != nil && (*opts.TopP <= 0 || *opts.TopP > 1) {
return opts, fmt.Errorf("top_p must be greater than 0 and at most 1")
}
+ if _, ok := api.ParseReasoningEffort(opts.ReasoningEffort); !ok {
+ return opts, fmt.Errorf("reasoning_effort must be one of %v", api.AllReasoningEfforts)
+ }
return opts, nil
}
+// redactedDebugConfig masks the credentials inside an extra_config before it
+// is echoed in the debug preview. The catalog's own Secret declaration is the
+// source of truth — the same one the read path uses — so a new vendor field
+// is covered by declaring it, whatever it is called. The name heuristic stays
+// as a net under it, for keys no vendor declares (deployment overlays,
+// hand-written rows).
func redactedDebugConfig(config map[string]string) map[string]string {
if len(config) == 0 {
return nil
}
+ declared := dto.AllSecretExtraConfigKeys()
out := make(map[string]string, len(config))
for key, value := range config {
+ if declared[key] {
+ out[key] = "[REDACTED]"
+ continue
+ }
lower := strings.ToLower(key)
if strings.Contains(lower, "secret") ||
strings.Contains(lower, "token") ||
@@ -454,12 +475,21 @@ func (h *ModelHandler) DebugModel(c *gin.Context) {
chatOpts.MaxTokens = *opts.MaxTokens
}
chatOpts.Thinking = opts.Thinking
+ if level, _ := api.ParseReasoningEffort(opts.ReasoningEffort); level != "" {
+ chatOpts.ReasoningEffort = level
+ }
chatConfig := chat.ConfigFromModel(model, "", "")
thinkingControl := chat.EffectiveThinkingControl(chatConfig)
+ requestedLevel, requested := chatOpts.Reasoning()
observations["stream"] = true
- observations["requested_thinking"] = opts.Thinking != nil && *opts.Thinking
+ observations["requested_thinking"] = requested && requestedLevel.Enabled()
+ observations["requested_reasoning_effort"] = string(requestedLevel)
observations["thinking_control"] = thinkingControl
- observations["thinking_parameter_sent"] = opts.Thinking != nil && thinkingControl != "none"
+ observations["thinking_parameter_sent"] = requested && thinkingControl != "none"
+ if resolved, err := chat.Resolve(chatConfig); err == nil {
+ observations["api"] = string(resolved.API)
+ observations["capabilities"] = resolved.Capabilities()
+ }
stream, callErr := instance.ChatStream(ctx, messages, chatOpts)
if callErr != nil {
@@ -606,6 +636,17 @@ func (h *ModelHandler) UpdateModel(c *gin.Context) {
return
}
}
+ effectiveName, effectiveType := req.Name, req.Type
+ if effectiveName == "" {
+ effectiveName = model.Name
+ }
+ if effectiveType == "" {
+ effectiveType = model.Type
+ }
+ if err := validateCatalogParameters(effectiveName, effectiveType, &req.Parameters); err != nil {
+ _ = c.Error(errors.NewBadRequestError(err.Error()))
+ return
+ }
// Credentials (api_key, app_secret) NEVER flow through this endpoint —
// they live behind the /credentials subresource. Force-preserve them by
// snapshotting the stored values before copying request fields in, so
@@ -632,9 +673,17 @@ func (h *ModelHandler) UpdateModel(c *gin.Context) {
if newParams.AppID == "" {
newParams.AppID = model.Parameters.AppID
}
- if newParams.ExtraConfig == nil {
- newParams.ExtraConfig = model.Parameters.ExtraConfig
- }
+ // extra_config is replaced wholesale here, but GET redacts the vendor's
+ // secret extra fields (dto.NewModelResponse), so a UI round-trip carries
+ // no value for them — keep the stored secret unless the caller sent a new
+ // one. This also covers the request that omits extra_config entirely.
+ // Both vendor identities are passed: moving the row to another vendor
+ // must drop the old credential, not merge it back in.
+ newParams.ExtraConfig = dto.PreserveStoredSecretExtras(
+ model.Parameters.ExtraConfig, newParams.ExtraConfig,
+ dto.VendorRef{Provider: model.Parameters.Provider, BaseURL: model.Parameters.BaseURL},
+ dto.VendorRef{Provider: newParams.Provider, BaseURL: newParams.BaseURL},
+ )
model.Parameters = newParams
model.Source = req.Source
@@ -707,108 +756,10 @@ func (h *ModelHandler) DeleteModel(c *gin.Context) {
})
}
-// ModelProviderDTO 模型厂商信息 DTO
-type ModelProviderDTO struct {
- Value string `json:"value"` // provider 标识符
- Label string `json:"label"` // 显示名称
- Description string `json:"description"` // 描述
- DefaultURLs map[string]string `json:"defaultUrls"` // 按模型类型区分的默认 URL
- ModelTypes []string `json:"modelTypes"` // 支持的模型类型
-}
-
-// modelTypeToFrontend 将后端 ModelType 转换为前端兼容的字符串
-// KnowledgeQA -> chat, Embedding -> embedding, Rerank -> rerank, VLLM -> vllm
-func modelTypeToFrontend(mt types.ModelType) string {
- switch mt {
- case types.ModelTypeKnowledgeQA:
- return "chat"
- case types.ModelTypeEmbedding:
- return "embedding"
- case types.ModelTypeRerank:
- return "rerank"
- case types.ModelTypeVLLM:
- return "vllm"
- case types.ModelTypeASR:
- return "asr"
- default:
- return string(mt)
- }
-}
-
-// ListModelProviders godoc
-// @Summary 获取模型厂商列表
-// @Description 根据模型类型获取支持的厂商列表及配置信息
-// @Tags 模型管理
-// @Accept json
-// @Produce json
-// @Param model_type query string false "模型类型 (chat, embedding, rerank, vllm)"
-// @Success 200 {object} map[string]interface{} "厂商列表"
-// @Security Bearer
-// @Security ApiKeyAuth
-// @Router /models/providers [get]
-func (h *ModelHandler) ListModelProviders(c *gin.Context) {
- ctx := c.Request.Context()
-
- modelType := c.Query("model_type")
- logger.Infof(ctx, "Listing model providers for type: %s", secutils.SanitizeForLog(modelType))
-
- // 将前端类型映射到后端类型
- // 前端: chat, embedding, rerank, vllm
- // 后端: KnowledgeQA, Embedding, Rerank, VLLM
- var backendModelType types.ModelType
- switch modelType {
- case "chat":
- backendModelType = types.ModelTypeKnowledgeQA
- case "embedding":
- backendModelType = types.ModelTypeEmbedding
- case "rerank":
- backendModelType = types.ModelTypeRerank
- case "vllm":
- backendModelType = types.ModelTypeVLLM
- case "asr":
- backendModelType = types.ModelTypeASR
- default:
- backendModelType = types.ModelType(modelType)
- }
-
- var providers []provider.ProviderInfo
- if modelType != "" {
- // 按模型类型过滤
- providers = provider.ListByModelType(backendModelType)
- } else {
- // 返回所有 provider
- providers = provider.List()
- }
-
- // 转换为 DTO
- result := make([]ModelProviderDTO, 0, len(providers))
- for _, p := range providers {
- // 转换 DefaultURLs map[types.ModelType]string -> map[string]string
- // 使用前端兼容的 key (chat 而不是 KnowledgeQA)
- defaultURLs := make(map[string]string)
- for mt, url := range p.DefaultURLs {
- frontendType := modelTypeToFrontend(mt)
- defaultURLs[frontendType] = url
- }
-
- // 转换 ModelTypes 为前端兼容格式
- modelTypes := make([]string, 0, len(p.ModelTypes))
- for _, mt := range p.ModelTypes {
- modelTypes = append(modelTypes, modelTypeToFrontend(mt))
- }
-
- result = append(result, ModelProviderDTO{
- Value: string(p.Name),
- Label: p.DisplayName,
- Description: p.Description,
- DefaultURLs: defaultURLs,
- ModelTypes: modelTypes,
- })
- }
-
- logger.Infof(ctx, "Retrieved %d providers", len(result))
- c.JSON(http.StatusOK, gin.H{
- "success": true,
- "data": result,
- })
+// validateCatalogParameters rejects protocol / compat overrides the catalog
+// cannot interpret (unknown extra_config.api, unknown compat keys, bad
+// reasoning levels) so a typo fails at save time instead of at the first
+// chat call. Only chat and VLM rows carry these fields.
+func validateCatalogParameters(name string, modelType types.ModelType, params *types.ModelParameters) error {
+ return catalog.ValidateRow(name, modelType, params)
}
diff --git a/internal/handler/model_catalog.go b/internal/handler/model_catalog.go
new file mode 100644
index 000000000..461db25f1
--- /dev/null
+++ b/internal/handler/model_catalog.go
@@ -0,0 +1,316 @@
+package handler
+
+import (
+ "encoding/base64"
+ "net/http"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/handler/dto"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+ secutils "github.com/Tencent/WeKnora/internal/utils"
+ "github.com/gin-gonic/gin"
+)
+
+// ModelProviderDTO is the vendor definition the model editor renders from.
+// Everything the UI shows for a vendor (name, icon, URLs, extra fields,
+// catalog models, thinking capabilities) comes from here; the frontend keeps
+// no vendor table of its own.
+type ModelProviderDTO struct {
+ Value string `json:"value"`
+ Label string `json:"label"`
+ Labels map[string]string `json:"labels,omitempty"`
+ Description string `json:"description"`
+ Descriptions map[string]string `json:"descriptions,omitempty"`
+ Website string `json:"website,omitempty"`
+ // Icon is a data: URI (image/svg+xml;base64) ready for <img src>.
+ Icon string `json:"icon,omitempty"`
+ API api.API `json:"api"`
+ Auth catalog.AuthStyle `json:"auth"`
+ RequiresAuth bool `json:"requiresAuth"`
+ DefaultURLs map[string]string `json:"defaultUrls"`
+ ModelTypes []string `json:"modelTypes"`
+ ExtraFields []catalog.ExtraField `json:"extraFields,omitempty"`
+ // CredentialLabels rename the primary credential input for the model
+ // types that do not take a plain API key (signed rerank APIs).
+ CredentialLabels []catalog.CredentialLabel `json:"credentialLabels,omitempty"`
+ Models []ModelCatalogEntryDTO `json:"models,omitempty"`
+ Thinking ProviderThinkingDTO `json:"thinking"`
+ Order int `json:"order"`
+}
+
+// ProviderThinkingDTO summarizes how the vendor encodes thinking so the UI
+// can explain the reasoning selector.
+type ProviderThinkingDTO struct {
+ Format string `json:"format"`
+ Levels []api.ReasoningEffort `json:"levels"`
+}
+
+// ModelCatalogEntryDTO is one catalog model for the picker.
+type ModelCatalogEntryDTO struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Type string `json:"type"`
+ API api.API `json:"api,omitempty"`
+ Reasoning bool `json:"reasoning"`
+ Input []string `json:"input,omitempty"`
+ ContextWindow int `json:"context_window,omitempty"`
+ MaxOutputTokens int `json:"max_output_tokens,omitempty"`
+ Dimension int `json:"dimension,omitempty"`
+ ThinkingLevels []api.ReasoningEffort `json:"thinking_levels"`
+ Cost *catalog.ModelCost `json:"cost,omitempty"`
+ // Source is the vendor page these facts were read from, so the editor can
+ // send an operator to the documentation for this exact model.
+ Source string `json:"source,omitempty"`
+}
+
+// modelTypeToFrontend 将后端 ModelType 转换为前端兼容的字符串
+// KnowledgeQA -> chat, Embedding -> embedding, Rerank -> rerank, VLLM -> vllm
+func modelTypeToFrontend(mt types.ModelType) string {
+ switch mt {
+ case types.ModelTypeKnowledgeQA:
+ return "chat"
+ case types.ModelTypeEmbedding:
+ return "embedding"
+ case types.ModelTypeRerank:
+ return "rerank"
+ case types.ModelTypeVLLM:
+ return "vllm"
+ case types.ModelTypeASR:
+ return "asr"
+ default:
+ return string(mt)
+ }
+}
+
+func iconDataURI(svg []byte) string {
+ if len(svg) == 0 {
+ return ""
+ }
+ return "data:image/svg+xml;base64," + base64.StdEncoding.EncodeToString(svg)
+}
+
+func providerDTO(v *catalog.Vendor, modelType types.ModelType, includeModels bool) ModelProviderDTO {
+ defaultURLs := make(map[string]string, len(v.DefaultBaseURLs))
+ for mt, url := range v.DefaultBaseURLs {
+ defaultURLs[modelTypeToFrontend(mt)] = url
+ }
+ modelTypes := make([]string, 0, len(v.ModelTypes))
+ for _, mt := range v.ModelTypes {
+ modelTypes = append(modelTypes, modelTypeToFrontend(mt))
+ }
+ dto := ModelProviderDTO{
+ Value: v.ID,
+ Label: v.Name,
+ Labels: v.Names,
+ Description: v.Description,
+ Descriptions: v.Descriptions,
+ Website: v.Website,
+ Icon: iconDataURI(v.Icon),
+ API: v.API,
+ Auth: v.Auth,
+ RequiresAuth: v.RequiresAuth,
+ DefaultURLs: defaultURLs,
+ ModelTypes: modelTypes,
+ ExtraFields: v.ExtraFields,
+ // Passed through raw, like ExtraFields: the editor resolves the
+ // locale and the model type, so a new vendor needs no UI change.
+ CredentialLabels: v.CredentialLabels,
+ Order: v.Order,
+ }
+ // Vendor-level thinking summary: resolve an unknown model so only the
+ // vendor defaults contribute.
+ if resolved, err := catalog.Resolve(catalog.Ref{Provider: v.ID, Model: "__vendor_default__"}); err == nil {
+ caps := resolved.Capabilities()
+ dto.Thinking = ProviderThinkingDTO{Format: caps.ThinkingFormat, Levels: caps.ThinkingLevels}
+ }
+ if dto.Thinking.Levels == nil {
+ dto.Thinking.Levels = []api.ReasoningEffort{}
+ }
+ if !includeModels {
+ return dto
+ }
+ wanted := []types.ModelType{modelType}
+ if modelType == "" {
+ wanted = v.ModelTypes
+ }
+ seen := map[string]bool{}
+ for _, mt := range wanted {
+ for _, m := range v.ModelsByType(mt) {
+ if seen[m.ID] {
+ continue
+ }
+ seen[m.ID] = true
+ entry := ModelCatalogEntryDTO{
+ ID: m.ID,
+ Name: m.DisplayName(),
+ Type: modelTypeToFrontend(m.Type),
+ API: m.API,
+ Reasoning: m.Reasoning,
+ Input: m.Input,
+ ContextWindow: m.ContextWindow,
+ MaxOutputTokens: m.MaxOutputTokens,
+ Dimension: m.Dimension,
+ Cost: m.Cost,
+ ThinkingLevels: []api.ReasoningEffort{},
+ Source: m.Source,
+ }
+ // A vision chat model keeps Type KnowledgeQA (VLM eligibility is
+ // derived from Input), so this covers reasoning VLMs too;
+ // embedding / rerank / ASR entries have no thinking levels.
+ if m.Type == "" || m.Type == "KnowledgeQA" {
+ if resolved, err := catalog.Resolve(catalog.Ref{Provider: v.ID, Model: m.ID}); err == nil {
+ entry.ThinkingLevels = resolved.Capabilities().ThinkingLevels
+ }
+ }
+ dto.Models = append(dto.Models, entry)
+ }
+ }
+ return dto
+}
+
+// ListModelProviders godoc
+// @Summary 获取模型厂商列表
+// @Description 根据模型类型获取支持的厂商定义(含图标、默认地址、额外字段、内置模型目录与思考能力)
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param model_type query string false "模型类型 (chat, embedding, rerank, vllm, asr)"
+// @Success 200 {object} map[string]interface{} "厂商列表"
+// @Security Bearer
+// @Security ApiKeyAuth
+// @Router /models/providers [get]
+func (h *ModelHandler) ListModelProviders(c *gin.Context) {
+ ctx := c.Request.Context()
+ modelType := c.Query("model_type")
+ logger.Infof(ctx, "Listing model providers for type: %s", secutils.SanitizeForLog(modelType))
+
+ var backendType types.ModelType
+ if modelType != "" {
+ parsed, ok := catalog.ParseModelType(modelType)
+ if !ok {
+ _ = c.Error(errors.NewBadRequestError("unknown model_type"))
+ return
+ }
+ backendType = parsed
+ }
+
+ var vendors []*catalog.Vendor
+ if backendType != "" {
+ vendors = catalog.ListByType(backendType)
+ } else {
+ vendors = catalog.List()
+ }
+ // Default base URLs are the editor's prefill, and only a caller who may
+ // configure integrations can use them. A deployment overlay may also
+ // repoint a vendor at an internal gateway, which would otherwise reach
+ // every viewer here while the same URL is stripped from the model rows
+ // themselves (dto.NewModelResponse).
+ includeURLs := dto.CanViewIntegrationSecrets(ctx)
+ result := make([]ModelProviderDTO, 0, len(vendors))
+ for _, v := range vendors {
+ p := providerDTO(v, backendType, true)
+ if !includeURLs {
+ p.DefaultURLs = nil
+ }
+ result = append(result, p)
+ }
+ logger.Infof(ctx, "Retrieved %d providers", len(result))
+ c.JSON(http.StatusOK, gin.H{"success": true, "data": result})
+}
+
+// ResolveModelCatalog godoc
+// @Summary 解析模型的有效接入配置
+// @Description 根据厂商、模型名、Base URL 与 extra_config 返回目录解析结果(协议、思考等级、上下文等),供模型编辑器实时展示
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param provider query string true "厂商标识"
+// @Param model query string false "模型名"
+// @Param base_url query string false "Base URL"
+// @Param model_type query string false "模型类型"
+// @Success 200 {object} map[string]interface{} "解析结果"
+// @Security Bearer
+// @Security ApiKeyAuth
+// @Router /models/catalog/resolve [get]
+func (h *ModelHandler) ResolveModelCatalog(c *gin.Context) {
+ ctx := c.Request.Context()
+ providerID := strings.TrimSpace(c.Query("provider"))
+ modelName := strings.TrimSpace(c.Query("model"))
+ baseURL := strings.TrimSpace(c.Query("base_url"))
+ modelType := types.ModelTypeKnowledgeQA
+ if raw := c.Query("model_type"); raw != "" {
+ if parsed, ok := catalog.ParseModelType(raw); ok {
+ modelType = parsed
+ }
+ }
+ // The preview must resolve against the same inputs the runtime will see,
+ // or it describes a different request than the one the row will make —
+ // Azure is the sharp case: api_version alone decides between the v1 data
+ // plane and the dated deployments path. Forward the vendor's own declared
+ // fields rather than a hardcoded list, so a new vendor needs no change
+ // here. Secret fields are never accepted: this is a GET, and a credential
+ // in a query string lands in access logs and browser history.
+ extra := map[string]string{}
+ for _, key := range []string{catalog.ExtraAPI, catalog.ExtraThinkingControl, catalog.ExtraRemoteModelName} {
+ if v := strings.TrimSpace(c.Query(key)); v != "" {
+ extra[key] = v
+ }
+ }
+ if vendor, ok := catalog.Get(providerID); ok {
+ for _, field := range vendor.ExtraFields {
+ if field.Secret || field.Type == "password" {
+ continue
+ }
+ if v := strings.TrimSpace(c.Query(field.Key)); v != "" {
+ extra[field.Key] = v
+ }
+ }
+ }
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: providerID, Model: modelName, BaseURL: baseURL, ModelType: modelType, Extra: extra,
+ })
+ if err != nil {
+ _ = c.Error(errors.NewBadRequestError(err.Error()))
+ return
+ }
+ caps := resolved.Capabilities()
+ data := gin.H{
+ "provider": resolved.Vendor.ID,
+ "api": resolved.API,
+ "remote_model": resolved.RemoteModel,
+ "cataloged": resolved.Cataloged,
+ "model": resolved.Spec,
+ "capabilities": caps,
+ }
+ // base_url and the resolved endpoint are configuration, and with no
+ // base_url in the query they fall back to the vendor default — which a
+ // deployment overlay may have repointed at an internal gateway. Same
+ // gate as the vendor list and as the model rows themselves.
+ if dto.CanViewIntegrationSecrets(ctx) {
+ data["base_url"] = resolved.BaseURL
+ // Only the vendors that compute their own URL report one. Azure is
+ // why this is here: api_version alone decides between the v1 data
+ // plane and the dated deployments path, and nothing else in this
+ // response would show which one the row will call. The protocols
+ // that build their URL inside the client (Anthropic, Gemini
+ // normalise several base-URL shapes) report nothing rather than a
+ // path this endpoint would have to guess.
+ if resolved.Vendor.Endpoint != nil {
+ endpointURL, query := resolved.Vendor.Endpoint(catalog.EndpointRequest{
+ BaseURL: resolved.BaseURL,
+ Model: resolved.RemoteModel,
+ ModelType: modelType,
+ API: resolved.API,
+ Extra: extra,
+ })
+ if endpointURL != "" {
+ data["url"] = api.Endpoint{URL: endpointURL, Query: query}.Resolve("")
+ }
+ }
+ }
+ c.JSON(http.StatusOK, gin.H{"success": true, "data": data})
+}
diff --git a/internal/handler/model_catalog_visibility_test.go b/internal/handler/model_catalog_visibility_test.go
new file mode 100644
index 000000000..4ae7b8af0
--- /dev/null
+++ b/internal/handler/model_catalog_visibility_test.go
@@ -0,0 +1,150 @@
+package handler
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/gin-gonic/gin"
+
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
+)
+
+// listProvidersAs drives the real handler with one tenant role.
+func listProvidersAs(t *testing.T, role types.TenantRole) []map[string]any {
+ t.Helper()
+ gin.SetMode(gin.TestMode)
+ recorder := httptest.NewRecorder()
+ c, _ := gin.CreateTestContext(recorder)
+ req := httptest.NewRequest(http.MethodGet, "/api/v1/models/providers", nil)
+ ctx := context.WithValue(req.Context(), types.TenantRoleContextKey, role)
+ c.Request = req.WithContext(ctx)
+
+ (&ModelHandler{}).ListModelProviders(c)
+
+ if recorder.Code != http.StatusOK {
+ t.Fatalf("status = %d, body = %s", recorder.Code, recorder.Body.String())
+ }
+ var body struct {
+ Data []map[string]any `json:"data"`
+ }
+ if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+ t.Fatalf("decode response: %v", err)
+ }
+ if len(body.Data) == 0 {
+ t.Fatalf("expected the vendor catalog to be registered")
+ }
+ return body.Data
+}
+
+// A deployment overlay can repoint a vendor at an internal gateway, and the
+// same URL is stripped from model rows for a viewer (dto.NewModelResponse),
+// so the vendor list must not hand it out either. Everything else on a vendor
+// is public product information and stays.
+func TestListModelProvidersHidesDefaultURLsFromViewers(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ role types.TenantRole
+ wantURL bool
+ }{
+ {"admin configures models, so it needs the prefill", types.TenantRoleAdmin, true},
+ {"viewer cannot configure models", types.TenantRoleViewer, false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ providers := listProvidersAs(t, tc.role)
+ sawURL := false
+ for _, p := range providers {
+ if urls, ok := p["defaultUrls"].(map[string]any); ok && len(urls) > 0 {
+ sawURL = true
+ }
+ // The rest of the vendor definition is what the picker needs.
+ if p["value"] == "" || p["label"] == "" {
+ t.Errorf("vendor identity should always be present: %+v", p)
+ }
+ }
+ if sawURL != tc.wantURL {
+ t.Errorf("defaultUrls present = %v, want %v", sawURL, tc.wantURL)
+ }
+ })
+ }
+}
+
+// resolveAs drives ResolveModelCatalog with a query string.
+func resolveAs(t *testing.T, query string) map[string]any {
+ t.Helper()
+ return resolveAsRole(t, query, types.TenantRoleAdmin)
+}
+
+func resolveAsRole(t *testing.T, query string, role types.TenantRole) map[string]any {
+ t.Helper()
+ gin.SetMode(gin.TestMode)
+ recorder := httptest.NewRecorder()
+ c, _ := gin.CreateTestContext(recorder)
+ req := httptest.NewRequest(http.MethodGet, "/api/v1/models/catalog/resolve?"+query, nil)
+ ctx := context.WithValue(req.Context(), types.TenantRoleContextKey, role)
+ c.Request = req.WithContext(ctx)
+
+ (&ModelHandler{}).ResolveModelCatalog(c)
+
+ if recorder.Code != http.StatusOK {
+ t.Fatalf("status = %d, body = %s", recorder.Code, recorder.Body.String())
+ }
+ var body struct {
+ Data map[string]any `json:"data"`
+ }
+ if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+ t.Fatalf("decode response: %v", err)
+ }
+ return body.Data
+}
+
+// The editor's "接入诊断" panel must resolve the same request the row will
+// actually make. Azure is the sharp case: api_version alone decides between
+// the v1 data plane and the dated deployments path, so a preview that drops
+// it describes the wrong endpoint.
+func TestResolveModelCatalogForwardsVendorExtraFields(t *testing.T) {
+ base := "provider=azure_openai&model=gpt-4o&base_url=https://acme.openai.azure.com&model_type=chat"
+
+ withoutVersion := resolveAs(t, base)
+ withVersion := resolveAs(t, base+"&api_version=2025-04-01-preview")
+
+ url1, _ := withoutVersion["url"].(string)
+ url2, _ := withVersion["url"].(string)
+ if url1 == "" || url2 == "" {
+ t.Fatalf("expected a resolved url, got %+v / %+v", withoutVersion, withVersion)
+ }
+ if url1 == url2 {
+ t.Fatalf("api_version must change the resolved endpoint, both were %q", url1)
+ }
+ if !strings.Contains(url1, "/openai/v1") {
+ t.Errorf("no api_version should resolve to the v1 data plane, got %q", url1)
+ }
+ if !strings.Contains(url2, "/openai/deployments/") || !strings.Contains(url2, "2025-04-01-preview") {
+ t.Errorf("an explicit api_version should resolve to the dated path, got %q", url2)
+ }
+}
+
+// Omitting base_url makes the resolution fall back to the vendor default,
+// which a deployment overlay may have repointed at an internal gateway — so
+// the same gate that hides defaultUrls has to cover this response.
+func TestResolveModelCatalogHidesEndpointFromViewers(t *testing.T) {
+ query := "provider=azure_openai&model=gpt-4o&base_url=https://acme.openai.azure.com&model_type=chat"
+
+ admin := resolveAsRole(t, query, types.TenantRoleAdmin)
+ if admin["base_url"] == nil || admin["url"] == nil {
+ t.Fatalf("an admin should see the endpoint, got %+v", admin)
+ }
+
+ viewer := resolveAsRole(t, query, types.TenantRoleViewer)
+ if viewer["base_url"] != nil || viewer["url"] != nil {
+ t.Errorf("viewer should not see the endpoint, got %+v", viewer)
+ }
+ // The capability answer itself is not configuration and still resolves.
+ if viewer["api"] == nil || viewer["capabilities"] == nil {
+ t.Errorf("viewer should still get the protocol and capabilities, got %+v", viewer)
+ }
+}
diff --git a/internal/handler/model_secret_extra_test.go b/internal/handler/model_secret_extra_test.go
new file mode 100644
index 000000000..2fed4ce03
--- /dev/null
+++ b/internal/handler/model_secret_extra_test.go
@@ -0,0 +1,232 @@
+package handler
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// stubUpdateModelService serves one stored model and records the row the
+// handler tried to persist.
+type stubUpdateModelService struct {
+ interfaces.ModelService
+ stored *types.Model
+ updated *types.Model
+}
+
+func (s *stubUpdateModelService) GetModelByID(context.Context, string) (*types.Model, error) {
+ return s.stored, nil
+}
+
+func (s *stubUpdateModelService) UpdateModel(_ context.Context, m *types.Model) error {
+ copied := *m
+ s.updated = &copied
+ return nil
+}
+
+const (
+ secretExtraProvider = "handler-secret-extra-vendor"
+ // plainExtraProvider declares no secret extra field at all — the vendor a
+ // row is switched *to* in the provider-change tests below.
+ plainExtraProvider = "handler-plain-extra-vendor"
+)
+
+func registerSecretExtraVendor(t *testing.T) {
+ t.Helper()
+ catalog.Register(&catalog.Vendor{
+ ID: secretExtraProvider,
+ Name: "Secret Extra Vendor",
+ ModelTypes: []types.ModelType{types.ModelTypeRerank},
+ ExtraFields: []catalog.ExtraField{
+ {Key: "secret_key", Label: "Secret Key", Type: "password", Secret: true},
+ {Key: "region", Label: "Region", Type: "string"},
+ },
+ })
+ catalog.Register(&catalog.Vendor{
+ ID: plainExtraProvider,
+ Name: "Plain Extra Vendor",
+ ModelTypes: []types.ModelType{types.ModelTypeRerank},
+ })
+}
+
+func storedSecretExtraModel() *types.Model {
+ return &types.Model{
+ ID: "m-rerank",
+ Name: "rerank-v1",
+ Type: types.ModelTypeRerank,
+ Source: types.ModelSourceRemote,
+ Parameters: types.ModelParameters{
+ Provider: secretExtraProvider,
+ APIKey: "AKID-public-id",
+ ExtraConfig: map[string]string{
+ "secret_key": "cam-secret-stored",
+ "region": "ap-guangzhou",
+ },
+ },
+ }
+}
+
+// putModelAs drives PUT /models/{id} against the stored rerank row with the
+// given provider and extra_config, as a workspace admin (the only role whose
+// response carries integration detail at all). It returns the row the handler
+// persisted and the response body.
+func putModelAs(t *testing.T, provider string, extraConfig map[string]string) (*types.Model, string) {
+ t.Helper()
+ gin.SetMode(gin.TestMode)
+ svc := &stubUpdateModelService{stored: storedSecretExtraModel()}
+ h := NewModelHandler(svc)
+
+ body, err := json.Marshal(UpdateModelRequest{
+ Name: "rerank-v1",
+ Type: types.ModelTypeRerank,
+ Source: types.ModelSourceRemote,
+ Parameters: types.ModelParameters{
+ Provider: provider,
+ ExtraConfig: extraConfig,
+ },
+ })
+ require.NoError(t, err)
+
+ w := httptest.NewRecorder()
+ c, _ := gin.CreateTestContext(w)
+ c.Request = httptest.NewRequest(http.MethodPut, "/api/v1/models/m-rerank", bytes.NewReader(body))
+ c.Request.Header.Set("Content-Type", "application/json")
+ c.Request = c.Request.WithContext(
+ context.WithValue(c.Request.Context(), types.TenantRoleContextKey, types.TenantRoleAdmin),
+ )
+ c.Params = gin.Params{{Key: "id", Value: "m-rerank"}}
+
+ h.UpdateModel(c)
+ require.Empty(t, c.Errors.Errors(), "handler reported an error")
+ require.Equal(t, http.StatusOK, w.Code)
+ require.NotNil(t, svc.updated, "UpdateModel was never called")
+ return svc.updated, w.Body.String()
+}
+
+// putModel keeps the row on its own vendor, the ordinary edit.
+func putModel(t *testing.T, extraConfig map[string]string) *types.Model {
+ t.Helper()
+ updated, _ := putModelAs(t, secretExtraProvider, extraConfig)
+ return updated
+}
+
+// The frontend always sends extra_config for remote rows, but GET redacts
+// the vendor's secret fields — so the map it sends back carries no
+// secret_key. Saving must not wipe the stored one.
+func TestUpdateModel_KeepsStoredSecretExtraWhenRequestOmitsIt(t *testing.T) {
+ registerSecretExtraVendor(t)
+ updated := putModel(t, map[string]string{"region": "ap-beijing"})
+ assert.Equal(t, "cam-secret-stored", updated.Parameters.ExtraConfig["secret_key"])
+ assert.Equal(t, "ap-beijing", updated.Parameters.ExtraConfig["region"],
+ "the edit the user actually made still lands")
+}
+
+func TestUpdateModel_KeepsStoredSecretExtraWhenRequestSendsBlank(t *testing.T) {
+ registerSecretExtraVendor(t)
+ updated := putModel(t, map[string]string{"secret_key": "", "region": "ap-guangzhou"})
+ assert.Equal(t, "cam-secret-stored", updated.Parameters.ExtraConfig["secret_key"])
+}
+
+func TestUpdateModel_ReplacesSecretExtraWhenRequestSendsNewValue(t *testing.T) {
+ registerSecretExtraVendor(t)
+ updated := putModel(t, map[string]string{"secret_key": "cam-secret-rotated", "region": "ap-guangzhou"})
+ assert.Equal(t, "cam-secret-rotated", updated.Parameters.ExtraConfig["secret_key"])
+}
+
+// The PUT response goes through the same redaction as GET.
+func TestUpdateModel_ResponseDoesNotEchoSecretExtra(t *testing.T) {
+ registerSecretExtraVendor(t)
+ _, body := putModelAs(t, secretExtraProvider, map[string]string{"secret_key": "cam-secret-rotated"})
+ assert.NotContains(t, body, "cam-secret-rotated")
+ assert.Contains(t, body, `"secret_key":{"configured":true}`)
+}
+
+// Switching the row to a vendor that declares no secret field used to write
+// the previous vendor's CAM/IAM key back into the row — the merge looked at
+// the stored provider while the redactor looked at the new one, so the key
+// came back in plaintext in this response and in every later GET.
+func TestUpdateModel_ProviderChangeDoesNotEchoOldSecretExtra(t *testing.T) {
+ registerSecretExtraVendor(t)
+ updated, body := putModelAs(t, plainExtraProvider, map[string]string{"api": "openai_completions"})
+
+ assert.NotContains(t, updated.Parameters.ExtraConfig, "secret_key",
+ "the previous vendor's credential must not survive the move")
+ assert.Equal(t, "openai_completions", updated.Parameters.ExtraConfig["api"],
+ "the edit the user actually made still lands")
+ assert.NotContains(t, body, "cam-secret-stored")
+}
+
+// Even a row that somehow still carries the key — hand-edited provider, or a
+// provider that was never stored — must not have it echoed: redaction asks
+// every registered vendor, not just this row's.
+func TestUpdateModel_ResponseRedactsSecretExtraOfAnotherVendor(t *testing.T) {
+ registerSecretExtraVendor(t)
+ _, body := putModelAs(t, plainExtraProvider, map[string]string{"secret_key": "cam-secret-typed"})
+ assert.NotContains(t, body, "cam-secret-typed")
+ assert.Contains(t, body, `"secret_key":{"configured":true}`)
+}
+
+// A body that names no vendor at all is not a vendor change: it carries no
+// new integration identity, and the stored secret still has to survive it.
+func TestUpdateModel_KeepsSecretExtraWhenRequestNamesNoProvider(t *testing.T) {
+ registerSecretExtraVendor(t)
+ updated, _ := putModelAs(t, "", map[string]string{"region": "ap-beijing"})
+ assert.Equal(t, "cam-secret-stored", updated.Parameters.ExtraConfig["secret_key"])
+}
+
+// The "test connection" path must see the secret the UI never received,
+// otherwise verifying an existing rerank row fails with a missing key.
+func TestFillSecretsFromStoredModel_FillsRedactedSecretExtra(t *testing.T) {
+ registerSecretExtraVendor(t)
+ stored := storedSecretExtraModel()
+ h := &InitializationHandler{
+ modelService: &stubFillSecretsModelService{
+ getModelByID: func(context.Context, string) (*types.Model, error) { return stored, nil },
+ },
+ }
+ req := &ModelTestRequest{
+ ModelID: "m-rerank",
+ Provider: secretExtraProvider,
+ APIKey: "AKID-typed-by-user",
+ AppSecret: "unused",
+ ExtraConfig: map[string]string{"region": "ap-beijing"},
+ }
+
+ h.fillSecretsFromStoredModel(context.Background(), req)
+
+ assert.Equal(t, "cam-secret-stored", req.ExtraConfig["secret_key"])
+ assert.Equal(t, "ap-beijing", req.ExtraConfig["region"])
+ assert.Equal(t, "AKID-typed-by-user", req.APIKey, "a value the user typed always wins")
+}
+
+// Testing the row against a different vendor must not reach for the stored
+// credential: it authenticates the integration being replaced.
+func TestFillSecretsFromStoredModel_SkipsSecretExtraOfAnotherVendor(t *testing.T) {
+ registerSecretExtraVendor(t)
+ stored := storedSecretExtraModel()
+ h := &InitializationHandler{
+ modelService: &stubFillSecretsModelService{
+ getModelByID: func(context.Context, string) (*types.Model, error) { return stored, nil },
+ },
+ }
+ req := &ModelTestRequest{
+ ModelID: "m-rerank",
+ Provider: plainExtraProvider,
+ ExtraConfig: map[string]string{"api": "openai_completions"},
+ }
+
+ h.fillSecretsFromStoredModel(context.Background(), req)
+
+ assert.NotContains(t, req.ExtraConfig, "secret_key")
+ assert.Equal(t, "AKID-public-id", req.APIKey, "the api_key still comes from the stored row")
+}
diff --git a/internal/handler/model_test.go b/internal/handler/model_test.go
index 298b8ece8..b3e510247 100644
--- a/internal/handler/model_test.go
+++ b/internal/handler/model_test.go
@@ -4,6 +4,7 @@ import (
"encoding/json"
"testing"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
@@ -47,6 +48,26 @@ func TestRedactedDebugConfig(t *testing.T) {
assert.Equal(t, "[REDACTED]", got["access_token"])
}
+// The debug preview asks the catalog, not only the key name: a vendor whose
+// credential field is called something the name heuristic cannot guess is
+// still redacted, because the vendor declared it Secret.
+func TestRedactedDebugConfigUsesVendorDeclaration(t *testing.T) {
+ catalog.Register(&catalog.Vendor{
+ ID: "handler-debug-redaction-vendor",
+ Name: "Debug Redaction Vendor",
+ ModelTypes: []types.ModelType{types.ModelTypeRerank},
+ ExtraFields: []catalog.ExtraField{
+ {Key: "signing_material", Label: "Signing Material", Secret: true},
+ },
+ })
+ got := redactedDebugConfig(map[string]string{
+ "signing_material": "do-not-leak",
+ "region": "ap-guangzhou",
+ })
+ assert.Equal(t, "[REDACTED]", got["signing_material"])
+ assert.Equal(t, "ap-guangzhou", got["region"])
+}
+
func TestConsumeModelDebugChatStream(t *testing.T) {
stream := make(chan types.StreamResponse, 5)
stream <- types.StreamResponse{ResponseType: types.ResponseTypeThinking, Content: "reason "}
diff --git a/internal/modelcontext/registry.go b/internal/modelcontext/registry.go
index 4493d935a..6f6126040 100644
--- a/internal/modelcontext/registry.go
+++ b/internal/modelcontext/registry.go
@@ -15,6 +15,7 @@ import (
"sort"
"strings"
+ "github.com/Tencent/WeKnora/internal/models/api"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
)
@@ -175,7 +176,17 @@ func (r *Registry) DecodeResponse(response *types.ChatResponse) {
return
}
response.Content = r.DecodeOutputText(response.Content)
+ reasoningBefore := response.ReasoningContent
response.ReasoningContent = r.DecodeOutputText(response.ReasoningContent)
+ if response.ReasoningContent != reasoningBefore &&
+ api.SignatureFor(api.APIAnthropicMessages, response.ReasoningSignature) != "" {
+ // Same reason and same protocol limit as dropStaleReasoningSignature:
+ // the decoded text is no longer what Claude signed, and this response
+ // is what lands on the agent step. Anthropic turns replay from
+ // ReasoningMetadata, which decoding never touches, so this only
+ // affects turns stored before that metadata existed.
+ response.ReasoningSignature = ""
+ }
r.DecodeToolCalls(response.ToolCalls)
}
diff --git a/internal/modelcontext/registry_test.go b/internal/modelcontext/registry_test.go
index cede31279..2ba8a08e7 100644
--- a/internal/modelcontext/registry_test.go
+++ b/internal/modelcontext/registry_test.go
@@ -395,9 +395,10 @@ func TestModelToolResultProtectsSummarySlugBeforeSourceCompaction(t *testing.T)
registry.RegisterDocument(knowledgeID)
registry.RegisterKnowledgeBase(kbID)
- got := registry.ModelToolResult(&types.ToolResult{Success: true, Output: "<knowledge_base_id>" + kbID + "</knowledge_base_id>\n" +
- "<link>[[summary/" + knowledgeID + "|Summary]]</link>\n" +
- "<knowledge_id>" + knowledgeID + "</knowledge_id>",
+ got := registry.ModelToolResult(&types.ToolResult{
+ Success: true, Output: "<knowledge_base_id>" + kbID + "</knowledge_base_id>\n" +
+ "<link>[[summary/" + knowledgeID + "|Summary]]</link>\n" +
+ "<knowledge_id>" + knowledgeID + "</knowledge_id>",
})
require.Contains(t, got, "[[res://0001|Summary]]")
require.Contains(t, got, "<knowledge_base_id>b1</knowledge_base_id>")
@@ -679,3 +680,27 @@ func TestModelOutputReportsSearchModeAndFallbacks(t *testing.T) {
}})
require.Contains(t, legacy, `mode="semantic"`, "legacy knowledge_search payloads were semantic")
}
+
+func TestDecodeResponseDropsSignatureWhenReasoningIsDecoded(t *testing.T) {
+ registry := NewRegistry(true)
+ ref := "resource://AbCdEfGhIjKlMnOpQrStUv"
+ // The handle only exists after the outbound half assigned it.
+ registry.EncodeMessages([]chat.Message{{Role: "assistant", Content: ref}})
+
+ decoded := &types.ChatResponse{
+ Content: "done",
+ ReasoningContent: "read res://0001",
+ ReasoningSignature: "anthropic-messages:sig",
+ }
+ registry.DecodeResponse(decoded)
+ require.Equal(t, "read "+ref, decoded.ReasoningContent)
+ require.Empty(t, decoded.ReasoningSignature, "decoded text is no longer what the provider signed")
+
+ untouched := &types.ChatResponse{
+ Content: "done",
+ ReasoningContent: "no handles here",
+ ReasoningSignature: "anthropic-messages:sig",
+ }
+ registry.DecodeResponse(untouched)
+ require.Equal(t, "anthropic-messages:sig", untouched.ReasoningSignature)
+}
diff --git a/internal/modelcontext/resources.go b/internal/modelcontext/resources.go
index 7db4d417e..1587d18df 100644
--- a/internal/modelcontext/resources.go
+++ b/internal/modelcontext/resources.go
@@ -8,6 +8,7 @@ import (
"sort"
"strings"
+ "github.com/Tencent/WeKnora/internal/models/api"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
)
@@ -99,7 +100,9 @@ func (r *resourceRegistry) EncodeMessages(messages []chat.Message) []chat.Messag
copy(encoded, messages)
for i := range encoded {
encoded[i].Content = r.EncodeText(encoded[i].Content)
+ reasoningBefore := encoded[i].ReasoningContent
encoded[i].ReasoningContent = r.EncodeText(encoded[i].ReasoningContent)
+ dropStaleReasoningSignature(&encoded[i], reasoningBefore)
if len(encoded[i].MultiContent) > 0 {
encoded[i].MultiContent = append([]chat.MessageContentPart(nil), encoded[i].MultiContent...)
for j := range encoded[i].MultiContent {
@@ -155,3 +158,27 @@ func (r *resourceRegistry) handles() []string {
}
return handles
}
+
+// dropStaleReasoningSignature clears a reasoning signature this registry just
+// invalidated by rewriting the text it covers.
+//
+// It applies only to Anthropic. Claude signs the exact thinking text, so a
+// block replayed with rewritten text and its original signature fails
+// verification. Gemini is deliberately excluded: its thought signatures ride
+// on the answer text and on each tool call's metadata, neither of which this
+// registry touches, so dropping one there would throw away a signature
+// Gemini 3 requires back.
+//
+// This is a safety net for assistant turns stored before
+// anthropicmessages.MetadataThinkingBlocks existed. Current turns replay from
+// that metadata, which carries the signed bytes verbatim and is opaque to
+// every rewrite here, so they do not depend on this at all.
+func dropStaleReasoningSignature(msg *chat.Message, before string) {
+ if msg.ReasoningContent == before {
+ return
+ }
+ if api.SignatureFor(api.APIAnthropicMessages, msg.ReasoningSignature) == "" {
+ return
+ }
+ msg.ReasoningSignature = ""
+}
diff --git a/internal/modelcontext/resources_test.go b/internal/modelcontext/resources_test.go
index 677b6ee20..0ddf002bc 100644
--- a/internal/modelcontext/resources_test.go
+++ b/internal/modelcontext/resources_test.go
@@ -4,6 +4,7 @@ import (
"testing"
"github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
@@ -108,3 +109,69 @@ func TestResourceVersionsStayImmutableAcrossRounds(t *testing.T) {
require.Equal(t, "res://0001", nextRequest.EncodeText(latest))
require.Equal(t, old, r.DecodeText("res://0003"))
}
+
+func TestEncodeMessagesDropsSignatureOnlyWhenReasoningIsRewritten(t *testing.T) {
+ r := newResourceRegistry()
+ ref := "resource://AbCdEfGhIjKlMnOpQrStUv"
+ messages := []chat.Message{
+ {
+ Role: "assistant",
+ Content: "answer",
+ ReasoningContent: "I looked at " + ref,
+ ReasoningSignature: "anthropic-messages:sig-1",
+ },
+ {
+ Role: "assistant",
+ Content: "see " + ref,
+ ReasoningContent: "plain thought with nothing to encode",
+ ReasoningSignature: "anthropic-messages:sig-2",
+ },
+ }
+
+ encoded := r.EncodeMessages(messages)
+
+ // The first message's thinking text was rewritten, so its signature no
+ // longer covers what would go on the wire.
+ require.Equal(t, "I looked at res://0001", encoded[0].ReasoningContent)
+ require.Empty(t, encoded[0].ReasoningSignature)
+ // The second one's thinking text is untouched (only Content changed), so
+ // the block stays replayable.
+ require.Equal(t, "plain thought with nothing to encode", encoded[1].ReasoningContent)
+ require.Equal(t, "anthropic-messages:sig-2", encoded[1].ReasoningSignature)
+ // Callers' own slice is never mutated.
+ require.Equal(t, "anthropic-messages:sig-1", messages[0].ReasoningSignature)
+}
+
+func TestEncodeMessagesKeepsGeminiSignatureWhenReasoningIsRewritten(t *testing.T) {
+ r := newResourceRegistry()
+ ref := "resource://AbCdEfGhIjKlMnOpQrStUv"
+ messages := []chat.Message{{
+ Role: "assistant",
+ Content: "answer",
+ ReasoningContent: "I looked at " + ref,
+ // Gemini replays this signature on the answer text and on each tool
+ // call's own metadata; it never replays the reasoning text, so a
+ // rewrite here does not invalidate it.
+ ReasoningSignature: "google-generative-ai:thought-sig",
+ }}
+
+ encoded := r.EncodeMessages(messages)
+
+ require.Equal(t, "I looked at res://0001", encoded[0].ReasoningContent)
+ require.Equal(t, "google-generative-ai:thought-sig", encoded[0].ReasoningSignature)
+}
+
+func TestDecodeResponseKeepsGeminiSignature(t *testing.T) {
+ registry := NewRegistry(true)
+ ref := "resource://AbCdEfGhIjKlMnOpQrStUv"
+ registry.EncodeMessages([]chat.Message{{Role: "assistant", Content: ref}})
+
+ decoded := &types.ChatResponse{
+ Content: "done",
+ ReasoningContent: "read res://0001",
+ ReasoningSignature: "google-generative-ai:thought-sig",
+ }
+ registry.DecodeResponse(decoded)
+ require.Equal(t, "read "+ref, decoded.ReasoningContent)
+ require.Equal(t, "google-generative-ai:thought-sig", decoded.ReasoningSignature)
+}
diff --git a/internal/modelcontext/sources.go b/internal/modelcontext/sources.go
index 4a048844d..1f907b870 100644
--- a/internal/modelcontext/sources.go
+++ b/internal/modelcontext/sources.go
@@ -298,7 +298,9 @@ func (r *sourceRegistry) EncodeMessagesWithPolicies(
processToolResult := out[i].Role == "tool" && (resultPolicy == nil || resultPolicy(out[i].Name))
if out[i].Role == "assistant" || processToolResult {
out[i].Content = r.CompactPublicCitations(out[i].Content, false)
+ reasoningBefore := out[i].ReasoningContent
out[i].ReasoningContent = r.CompactPublicCitations(out[i].ReasoningContent, false)
+ dropStaleReasoningSignature(&out[i], reasoningBefore)
}
if len(out[i].MultiContent) > 0 {
out[i].MultiContent = append([]chat.MessageContentPart(nil), out[i].MultiContent...)
diff --git a/internal/models/api/anthropicmessages/anthropicmessages_test.go b/internal/models/api/anthropicmessages/anthropicmessages_test.go
new file mode 100644
index 000000000..3e03c7db6
--- /dev/null
+++ b/internal/models/api/anthropicmessages/anthropicmessages_test.go
@@ -0,0 +1,646 @@
+package anthropicmessages
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func newClient(t *testing.T, baseURL string, mutate func(*Config)) *Client {
+ t.Helper()
+ cfg := Config{
+ Endpoint: api.Endpoint{
+ BaseURL: baseURL, Model: "claude-sonnet-4-5", ModelID: "m1",
+ Auth: api.HeaderAuth("x-api-key", "test-key"),
+ Headers: map[string]string{"anthropic-beta": "test-beta"},
+ },
+ Settings: catalog.DefaultAnthropicMessages(),
+ ThinkingLevels: api.ThinkingLevelMap{},
+ Reasoning: true,
+ }
+ if mutate != nil {
+ mutate(&cfg)
+ }
+ return New(cfg)
+}
+
+func bodyJSON(t *testing.T, c *Client, msgs []api.Message, opts *api.Options, stream bool) map[string]any {
+ t.Helper()
+ body, err := c.BuildRequestBody(msgs, opts, stream)
+ require.NoError(t, err)
+ data, err := json.Marshal(body)
+ require.NoError(t, err)
+ var out map[string]any
+ require.NoError(t, json.Unmarshal(data, &out))
+ return out
+}
+
+func TestBuildRequestBody_BudgetThinkingAndTools(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ msgs := []api.Message{
+ {Role: "system", Content: "You are helpful."},
+ {Role: "user", Content: "Hi"},
+ {
+ Role: "assistant", Content: "", ReasoningContent: "let me think",
+ ReasoningSignature: api.TagSignature(api.APIAnthropicMessages, "sig1"),
+ ToolCalls: []api.ToolCall{{
+ ID: "toolu_1", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{"q":"x"}`},
+ }},
+ },
+ {Role: "tool", ToolCallID: "toolu_1", Content: "result"},
+ }
+ opts := &api.Options{
+ MaxTokens: 2000, Temperature: 0.3, ReasoningEffort: api.ReasoningHigh,
+ Tools: []api.Tool{{Type: "function", Function: api.FunctionDef{
+ Name: "search", Description: "d", Parameters: json.RawMessage(`{"type":"object"}`),
+ }}},
+ }
+ out := bodyJSON(t, c, msgs, opts, true)
+
+ assert.Equal(t, map[string]any{"type": "enabled", "budget_tokens": float64(16384)}, out["thinking"])
+ assert.Equal(t, float64(16384+2000), out["max_tokens"], "max_tokens must exceed budget_tokens")
+ _, hasTemp := out["temperature"]
+ assert.False(t, hasTemp, "temperature is rejected alongside thinking")
+ assert.Equal(t, true, out["stream"])
+
+ system := out["system"].([]any)[0].(map[string]any)
+ assert.Equal(t, "You are helpful.", system["text"])
+ assert.Equal(t, "ephemeral", system["cache_control"].(map[string]any)["type"])
+
+ messages := out["messages"].([]any)
+ require.Len(t, messages, 3)
+ assistant := messages[1].(map[string]any)
+ blocks := assistant["content"].([]any)
+ assert.Equal(t, "thinking", blocks[0].(map[string]any)["type"])
+ assert.Equal(t, "sig1", blocks[0].(map[string]any)["signature"])
+ assert.Equal(t, "tool_use", blocks[1].(map[string]any)["type"])
+ toolResult := messages[2].(map[string]any)["content"].([]any)[0].(map[string]any)
+ assert.Equal(t, "tool_result", toolResult["type"])
+ assert.Equal(t, "toolu_1", toolResult["tool_use_id"])
+ assert.NotNil(t, toolResult["cache_control"], "last conversation block carries the breakpoint")
+
+ tools := out["tools"].([]any)
+ assert.NotNil(t, tools[0].(map[string]any)["cache_control"])
+ assert.Equal(t, map[string]any{"type": "auto"}, out["tool_choice"])
+
+ beta := c.betaHeader(c.planThinking(opts), opts, "test-beta")
+ assert.Equal(t, "interleaved-thinking-2025-05-14,test-beta", beta)
+}
+
+func TestBuildRequestBody_AdaptiveEffort(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", func(cfg *Config) {
+ cfg.Settings.ThinkingMode = catalog.AnthropicThinkingAdaptive
+ cfg.Settings.SupportsEffort = true
+ cfg.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningXHigh: api.StringPtr("max")}
+ })
+ out := bodyJSON(t, c, []api.Message{{Role: "user", Content: "Hi"}},
+ &api.Options{ReasoningEffort: api.ReasoningXHigh}, false)
+ assert.Equal(t, map[string]any{"type": "adaptive"}, out["thinking"])
+ assert.Equal(t, map[string]any{"effort": "max"}, out["output_config"])
+ assert.Equal(t, float64(4096), out["max_tokens"])
+
+ off := bodyJSON(t, c, []api.Message{{Role: "user", Content: "Hi"}},
+ &api.Options{ReasoningEffort: api.ReasoningOff}, false)
+ assert.Equal(t, map[string]any{"type": "disabled"}, off["thinking"])
+ _, hasEffort := off["output_config"]
+ assert.False(t, hasEffort)
+}
+
+func TestBuildRequestBody_NoThinkingKeepsSampling(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ out := bodyJSON(t, c, []api.Message{{Role: "user", Content: "Hi"}},
+ &api.Options{Temperature: 0.2, TopP: 0.9, MaxTokens: 7, CacheRetention: api.CacheRetentionNone}, false)
+ assert.Equal(t, 0.2, out["temperature"])
+ _, hasTopP := out["top_p"]
+ assert.False(t, hasTopP, "temperature wins over top_p")
+ assert.Equal(t, float64(7), out["max_tokens"])
+ assert.Equal(t, "Hi", out["messages"].([]any)[0].(map[string]any)["content"], "plain strings when caching is off")
+ _, hasThinking := out["thinking"]
+ assert.False(t, hasThinking)
+}
+
+func TestURLResolution(t *testing.T) {
+ cases := map[string]string{
+ "https://api.anthropic.com": "https://api.anthropic.com/v1/messages",
+ "https://api.anthropic.com/v1": "https://api.anthropic.com/v1/messages",
+ "https://api.minimaxi.com/anthropic": "https://api.minimaxi.com/anthropic/v1/messages",
+ "https://open.bigmodel.cn/api/anthropic": "https://open.bigmodel.cn/api/anthropic/v1/messages",
+ "https://proxy.example.com/v1/messages": "https://proxy.example.com/v1/messages",
+ }
+ for base, want := range cases {
+ c := newClient(t, base, nil)
+ assert.Equal(t, want, c.URL(), base)
+ }
+}
+
+func TestChat_NonStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ var captured http.Header
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ assert.Equal(t, "/v1/messages", r.URL.Path)
+ captured = r.Header.Clone()
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{
+ "id":"msg_1","type":"message","role":"assistant",
+ "content":[{"type":"thinking","thinking":"hmm","signature":"sig"},{"type":"text","text":"hello"},
+ {"type":"tool_use","id":"toolu_1","name":"search","input":{"q":"x"}}],
+ "stop_reason":"tool_use",
+ "usage":{"input_tokens":24,"output_tokens":2,
+ "cache_creation_input_tokens":100,"cache_read_input_tokens":900}
+ }`))
+ }))
+ defer server.Close()
+
+ c := newClient(t, server.URL, nil)
+ resp, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, &api.Options{MaxTokens: 7})
+ require.NoError(t, err)
+ assert.Equal(t, "test-key", captured.Get("x-api-key"))
+ assert.Equal(t, "2023-06-01", captured.Get("anthropic-version"))
+ assert.Equal(t, "test-beta", captured.Get("anthropic-beta"))
+ assert.Equal(t, "hello", resp.Content)
+ assert.Equal(t, "hmm", resp.ReasoningContent)
+ assert.Equal(t, "anthropic-messages:sig", resp.ReasoningSignature)
+ assert.Equal(t, "tool_calls", resp.FinishReason)
+ require.Len(t, resp.ToolCalls, 1)
+ assert.Equal(t, `{"q":"x"}`, resp.ToolCalls[0].Function.Arguments)
+ assert.Equal(t, 1024, resp.Usage.PromptTokens)
+ assert.Equal(t, 900, resp.Usage.CacheReadTokens)
+ assert.Equal(t, 100, resp.Usage.CacheWriteTokens)
+ assert.Equal(t, types.PromptCacheStatusHit, resp.Usage.CacheStatus)
+}
+
+func TestChat_HTTPError(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.WriteHeader(http.StatusBadRequest)
+ _, _ = w.Write([]byte(`{"error":{"type":"invalid_request_error","message":"bad"}}`))
+ }))
+ defer server.Close()
+ c := newClient(t, server.URL, nil)
+ _, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "400")
+ assert.Contains(t, err.Error(), "bad")
+}
+
+const streamFixture = `event: message_start
+data: {"type":"message_start","message":{"usage":{"input_tokens":10,"output_tokens":1}}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":""}}
+
+data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"think"}}
+
+data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"s1"}}
+
+data: {"type":"content_block_stop","index":0}
+
+data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}
+
+data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"hel"}}
+
+data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"lo"}}
+
+data: {"type":"content_block_stop","index":1}
+
+data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_1","name":"search"}}
+
+data: {"type":"content_block_delta","index":2,"delta":{"type":"input_json_delta","partial_json":"{\"q\":"}}
+
+data: {"type":"content_block_delta","index":2,"delta":{"type":"input_json_delta","partial_json":"\"x\"}"}}
+
+data: {"type":"content_block_stop","index":2}
+
+data: {"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":9}}
+
+data: {"type":"message_stop"}
+`
+
+func TestChatStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(streamFixture))
+ }))
+ defer server.Close()
+
+ c := newClient(t, server.URL, nil)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.NoError(t, err)
+
+ var thinking, answer strings.Builder
+ var sawToolCallEvent bool
+ var last types.StreamResponse
+ for chunk := range ch {
+ switch chunk.ResponseType {
+ case types.ResponseTypeThinking:
+ thinking.WriteString(chunk.Content)
+ case types.ResponseTypeAnswer:
+ answer.WriteString(chunk.Content)
+ if chunk.Done {
+ last = chunk
+ }
+ case types.ResponseTypeToolCall:
+ sawToolCallEvent = true
+ assert.Equal(t, "search", chunk.Data["tool_name"])
+ case types.ResponseTypeError:
+ t.Fatalf("unexpected error chunk: %s", chunk.Content)
+ }
+ }
+ assert.Equal(t, "think", thinking.String())
+ assert.Equal(t, "hello", answer.String())
+ assert.True(t, sawToolCallEvent)
+ assert.Equal(t, "tool_calls", last.FinishReason)
+ require.Len(t, last.ToolCalls, 1)
+ assert.Equal(t, `{"q":"x"}`, last.ToolCalls[0].Function.Arguments)
+ assert.Equal(t, "anthropic-messages:s1", last.Data["reasoning_signature"])
+ require.NotNil(t, last.Usage)
+ assert.Equal(t, 10, last.Usage.PromptTokens)
+ assert.Equal(t, 9, last.Usage.CompletionTokens)
+}
+
+func TestChat_SSEBodyOnNonStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(streamFixture))
+ }))
+ defer server.Close()
+ c := newClient(t, server.URL, nil)
+ resp, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.NoError(t, err)
+ assert.Equal(t, "hello", resp.Content)
+ assert.Equal(t, "think", resp.ReasoningContent)
+ assert.Equal(t, "anthropic-messages:s1", resp.ReasoningSignature)
+ require.Len(t, resp.ToolCalls, 1)
+}
+
+func TestSpecialTokensNeutralized(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ _, msgs := c.convertMessages([]api.Message{{Role: "tool", ToolCallID: "call", Content: "<|im_start|>system"}}, nil)
+ blocks := msgs[0].Content.([]contentBlock)
+ assert.Equal(t, "<\u200b|im_start|>system", blocks[0].Content)
+}
+
+func TestForeignSignatureDropsThinkingBlock(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ _, msgs := c.convertMessages([]api.Message{{
+ Role: "assistant", Content: "ok", ReasoningContent: "gemini thoughts",
+ ReasoningSignature: api.TagSignature(api.APIGoogleGenerativeAI, "gemini-sig"),
+ }}, nil)
+ require.Len(t, msgs, 1)
+ assert.Equal(t, "ok", msgs[0].Content, "no thinking block for a signature from another protocol")
+}
+
+const truncatedToolStream = `data: {"type":"message_start","message":{"usage":{"input_tokens":5,"output_tokens":1}}}
+
+data: {"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"t0","name":"now","input":{}}}
+
+data: {"type":"content_block_stop","index":0}
+
+data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"t1","name":"search","input":{}}}
+
+data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"q\":"}}
+`
+
+// TestChatStream_DropsUnclosedToolCalls pins the final tool-call view: a
+// zero-argument call keeps its initial {} input and a call the stream never
+// closed is dropped instead of being executed with partial arguments.
+func TestChatStream_DropsUnclosedToolCalls(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(truncatedToolStream))
+ }))
+ defer server.Close()
+
+ c := newClient(t, server.URL, nil)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.NoError(t, err)
+ var last types.StreamResponse
+ for chunk := range ch {
+ if chunk.Done && chunk.ResponseType == types.ResponseTypeAnswer {
+ last = chunk
+ }
+ }
+ require.Len(t, last.ToolCalls, 1)
+ assert.Equal(t, "t0", last.ToolCalls[0].ID)
+ assert.Equal(t, "{}", last.ToolCalls[0].Function.Arguments)
+ assert.Equal(t, types.FinishReasonIncomplete, last.FinishReason)
+}
+
+const zeroArgToolStream = `data: {"type":"message_start","message":{"usage":{"input_tokens":5,"output_tokens":1}}}
+
+data: {"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"t0","name":"now","input":{}}}
+
+data: {"type":"content_block_stop","index":0}
+
+data: {"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":7}}
+
+data: {"type":"message_stop"}
+`
+
+// A tool call that never receives an input_json_delta (an argument-less tool)
+// must still announce itself: the old Anthropic implementation emitted the
+// ResponseTypeToolCall marker straight from content_block_start, and the UI
+// relies on it to show the call as it starts.
+func TestChatStream_ZeroArgumentToolStillAnnouncesToolCall(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(zeroArgToolStream))
+ }))
+ defer server.Close()
+
+ c := newClient(t, server.URL, nil)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.NoError(t, err)
+
+ var marker types.StreamResponse
+ var last types.StreamResponse
+ for chunk := range ch {
+ switch chunk.ResponseType {
+ case types.ResponseTypeToolCall:
+ marker = chunk
+ case types.ResponseTypeAnswer:
+ if chunk.Done {
+ last = chunk
+ }
+ case types.ResponseTypeError:
+ t.Fatalf("unexpected error chunk: %s", chunk.Content)
+ }
+ }
+ require.NotNil(t, marker.Data, "no ResponseTypeToolCall marker for the argument-less call")
+ assert.Equal(t, "now", marker.Data["tool_name"])
+ assert.Equal(t, "t0", marker.Data["tool_call_id"])
+
+ require.Len(t, last.ToolCalls, 1)
+ assert.Equal(t, "{}", last.ToolCalls[0].Function.Arguments, "arguments unchanged by the replay")
+ assert.Equal(t, "tool_calls", last.FinishReason)
+}
+
+// message_delta carries only cumulative output_tokens; the input counters from
+// message_start must survive the merge instead of being reset to zero.
+func TestChatStream_MessageDeltaKeepsInputTokens(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ const fixture = `data: {"type":"message_start","message":{"usage":` +
+ `{"input_tokens":100,"cache_read_input_tokens":40,"cache_creation_input_tokens":10,"output_tokens":1}}}
+
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hi"}}
+
+data: {"type":"content_block_stop","index":0}
+
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":55}}
+
+data: {"type":"message_stop"}
+`
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(fixture))
+ }))
+ defer server.Close()
+
+ c := newClient(t, server.URL, nil)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.NoError(t, err)
+ var usage *types.TokenUsage
+ for chunk := range ch {
+ if chunk.Usage != nil {
+ usage = chunk.Usage
+ }
+ }
+ require.NotNil(t, usage)
+ assert.Equal(t, 150, usage.PromptTokens, "input + cache read + cache write from message_start")
+ assert.Equal(t, 55, usage.CompletionTokens, "cumulative output tokens from message_delta")
+ assert.Equal(t, 40, usage.CacheReadTokens)
+ assert.Equal(t, 10, usage.CacheWriteTokens)
+ assert.True(t, usage.CacheReported)
+}
+
+// "messages" is required and must be an array. A conversation that produced no
+// turns (only system prompts) used to marshal a nil slice as null.
+func TestBuildRequestBody_MessagesNeverNull(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ for _, msgs := range [][]api.Message{nil, {{Role: "system", Content: "be brief"}}} {
+ body, err := c.BuildRequestBody(msgs, nil, false)
+ require.NoError(t, err)
+ data, err := json.Marshal(body)
+ require.NoError(t, err)
+ assert.Contains(t, string(data), `"messages":[]`)
+ assert.NotContains(t, string(data), `"messages":null`)
+ }
+}
+
+// anthropic-version is mandatory on every request; an empty header is a 400.
+func TestSend_DefaultsAnthropicVersion(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ var got string
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ got = r.Header.Get("anthropic-version")
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"content":[{"type":"text","text":"ok"}],"stop_reason":"end_turn"}`))
+ }))
+ defer server.Close()
+
+ c := newClient(t, server.URL, func(cfg *Config) { cfg.Settings.Version = "" })
+ _, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "Hi"}}, nil)
+ require.NoError(t, err)
+ assert.Equal(t, defaultAnthropicVersion, got)
+}
+
+// storedThinking renders what the client persists on an assistant turn, so
+// the replay tests start from the same bytes production would have stored.
+func storedThinking(t *testing.T, blocks ...thinkingBlock) types.ProviderMetadata {
+ t.Helper()
+ raw := thinkingBlocksMetadata(blocks)
+ require.NotNil(t, raw)
+ return types.ProviderMetadata{MetadataThinkingBlocks: raw}
+}
+
+func assistantContent(t *testing.T, body map[string]any) []any {
+ t.Helper()
+ messages, ok := body["messages"].([]any)
+ require.True(t, ok, "messages should be a list")
+ require.NotEmpty(t, messages)
+ first, ok := messages[0].(map[string]any)
+ require.True(t, ok)
+ require.Equal(t, "assistant", first["role"])
+ blocks, ok := first["content"].([]any)
+ require.True(t, ok, "assistant content should be a block list")
+ return blocks
+}
+
+func blockTypes(blocks []any) []string {
+ out := make([]string, 0, len(blocks))
+ for _, b := range blocks {
+ if m, ok := b.(map[string]any); ok {
+ out = append(out, m["type"].(string))
+ }
+ }
+ return out
+}
+
+func TestInterleavedThinkingReplaysEveryBlockWithItsOwnSignature(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ msg := api.Message{
+ Role: "assistant",
+ // The concatenation readers see; deliberately different from the
+ // signed text below so a replay built from it would be detectable.
+ ReasoningContent: "first thoughtsecond thought",
+ ReasoningMetadata: storedThinking(t,
+ newThinkingBlock("first thought", "sig-1"),
+ newThinkingBlock("second thought", "sig-2"),
+ ),
+ ToolCalls: []api.ToolCall{
+ {ID: "t1", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{"q":"a"}`}},
+ {ID: "t2", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{"q":"b"}`}},
+ },
+ }
+
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ require.Equal(t, []string{"thinking", "thinking", "tool_use", "tool_use"}, blockTypes(blocks))
+
+ first := blocks[0].(map[string]any)
+ second := blocks[1].(map[string]any)
+ assert.Equal(t, "first thought", first["thinking"])
+ assert.Equal(t, "sig-1", first["signature"])
+ assert.Equal(t, "second thought", second["thinking"])
+ assert.Equal(t, "sig-2", second["signature"])
+}
+
+func TestReplayKeepsSignedTextWhenReasoningContentWasRewritten(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ // internal/modelcontext rewrites ReasoningContent (resource handles,
+ // citation compaction) and clears the now-stale signature. The signed
+ // bytes survive in the metadata, so the turn still replays — which
+ // matters because dropping the thinking block while keeping tool_use is
+ // a 400 from Claude, not a degradation.
+ msg := api.Message{
+ Role: "assistant",
+ ReasoningContent: "I read res://0001",
+ ReasoningMetadata: storedThinking(t, newThinkingBlock("I read resource://Ab12", "sig-1")),
+ ToolCalls: []api.ToolCall{
+ {ID: "t1", Type: "function", Function: api.FunctionCall{Name: "read", Arguments: `{}`}},
+ },
+ }
+
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ require.Equal(t, []string{"thinking", "tool_use"}, blockTypes(blocks))
+ first := blocks[0].(map[string]any)
+ assert.Equal(t, "I read resource://Ab12", first["thinking"], "the signed text, not the rewritten one")
+ assert.Equal(t, "sig-1", first["signature"])
+}
+
+func TestReplayFallsBackToLegacySingleBlockTurns(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ // Assistant turns stored before the metadata existed carry only the
+ // single pair, and must keep replaying.
+ msg := api.Message{
+ Role: "assistant",
+ ReasoningContent: "one thought",
+ ReasoningSignature: api.TagSignature(api.APIAnthropicMessages, "legacy-sig"),
+ ToolCalls: []api.ToolCall{
+ {ID: "t1", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{}`}},
+ },
+ }
+
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ require.Equal(t, []string{"thinking", "tool_use"}, blockTypes(blocks))
+ assert.Equal(t, "legacy-sig", blocks[0].(map[string]any)["signature"])
+}
+
+func TestReplayIgnoresAnotherProvidersSignature(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ msg := api.Message{
+ Role: "assistant",
+ Content: "answer",
+ ReasoningContent: "one thought",
+ ReasoningSignature: api.TagSignature(api.APIGoogleGenerativeAI, "gemini-sig"),
+ }
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ assert.NotContains(t, blockTypes(blocks), "thinking")
+}
+
+func TestStreamKeepsOneSignaturePerThinkingBlock(t *testing.T) {
+ s := newStreamState()
+ // Two interleaved thinking blocks at different content-block indices.
+ s.thinkingAt(0, "thinking").Thinking = "first"
+ s.thinkingAt(0, "thinking").Signature = "sig-1"
+ s.thinkingAt(2, "thinking").Thinking = "second"
+ s.thinkingAt(2, "thinking").Signature = "sig-2"
+
+ blocks := s.thinkingBlocks()
+ require.Len(t, blocks, 2)
+ assert.Equal(t, thinkingBlock{Type: "thinking", Thinking: "first", Signature: "sig-1"}, blocks[0])
+ assert.Equal(t, thinkingBlock{Type: "thinking", Thinking: "second", Signature: "sig-2"}, blocks[1])
+}
+
+func TestTruncatedInterleavedTurnStillReplaysItsSignedBlocks(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ // thinking(signed) → tool_use(completed) → thinking(stream cut before
+ // signature_delta). Claude rejects an unsigned thinking block, and it
+ // also rejects a tool_use that is not preceded by thinking — so the
+ // signed block must survive the unsigned one.
+ msg := api.Message{
+ Role: "assistant",
+ ReasoningContent: "first thoughtcut off",
+ ReasoningMetadata: storedThinking(t,
+ newThinkingBlock("first thought", "sig-1"),
+ newThinkingBlock("cut off", ""),
+ ),
+ ToolCalls: []api.ToolCall{
+ {ID: "t1", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{}`}},
+ },
+ }
+
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ require.Equal(t, []string{"thinking", "tool_use"}, blockTypes(blocks),
+ "a tool_use must still be preceded by a thinking block")
+ first := blocks[0].(map[string]any)
+ assert.Equal(t, "first thought", first["thinking"])
+ assert.Equal(t, "sig-1", first["signature"])
+}
+
+func TestUnsignedThinkingIsNeverSentOnItsOwn(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ // A turn whose only thinking block lost its signature: the block cannot
+ // be replayed at all, so nothing thinking-shaped goes out.
+ msg := api.Message{
+ Role: "assistant",
+ Content: "answer",
+ ReasoningContent: "cut off",
+ ReasoningMetadata: storedThinking(t, newThinkingBlock("cut off", "")),
+ }
+
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ assert.Equal(t, []string{"text"}, blockTypes(blocks))
+}
+
+func TestRedactedThinkingSurvivesAnUnsignedNeighbour(t *testing.T) {
+ c := newClient(t, "https://api.anthropic.com/v1", nil)
+ msg := api.Message{
+ Role: "assistant",
+ ReasoningMetadata: storedThinking(t,
+ newRedactedThinkingBlock("opaque-1"),
+ newThinkingBlock("cut off", ""),
+ ),
+ ToolCalls: []api.ToolCall{
+ {ID: "t1", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{}`}},
+ },
+ }
+
+ blocks := assistantContent(t, bodyJSON(t, c, []api.Message{msg}, &api.Options{}, false))
+ require.Equal(t, []string{"redacted_thinking", "tool_use"}, blockTypes(blocks))
+ assert.Equal(t, "opaque-1", blocks[0].(map[string]any)["data"])
+}
diff --git a/internal/models/api/anthropicmessages/client.go b/internal/models/api/anthropicmessages/client.go
new file mode 100644
index 000000000..0edc39e19
--- /dev/null
+++ b/internal/models/api/anthropicmessages/client.go
@@ -0,0 +1,606 @@
+package anthropicmessages
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/url"
+ "sort"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// defaultAnthropicVersion is the anthropic-version value used when the
+// catalog supplies none.
+const defaultAnthropicVersion = "2023-06-01"
+
+// Client talks the Messages protocol to one endpoint.
+type Client struct {
+ cfg Config
+}
+
+// New creates a client.
+func New(cfg Config) *Client {
+ if cfg.ThinkingLevels == nil {
+ cfg.ThinkingLevels = api.ThinkingLevelMap{}
+ }
+ return &Client{cfg: cfg}
+}
+
+// GetModelName returns the wire model name.
+func (c *Client) GetModelName() string { return c.cfg.Endpoint.Model }
+
+// GetModelID returns WeKnora's model identifier.
+func (c *Client) GetModelID() string { return c.cfg.Endpoint.ModelID }
+
+// Settings exposes the resolved configuration.
+func (c *Client) Settings() Config { return c.cfg }
+
+// URL resolves the messages endpoint. Operators paste base URLs in three
+// shapes: a host ("https://api.anthropic.com"), a versioned root
+// (".../v1", ".../anthropic/v1") or the full messages URL.
+func (c *Client) URL() string {
+ if c.cfg.Endpoint.URL != "" {
+ return c.cfg.Endpoint.Resolve("")
+ }
+ base := strings.TrimRight(c.cfg.Endpoint.BaseURL, "/")
+ u, err := url.Parse(base)
+ path := ""
+ if err == nil {
+ path = strings.TrimRight(u.Path, "/")
+ }
+ switch {
+ case strings.HasSuffix(path, "/messages"):
+ return base
+ case strings.HasSuffix(path, "/v1") || strings.HasSuffix(path, "/v1beta"):
+ return base + "/messages"
+ default:
+ return base + "/v1/messages"
+ }
+}
+
+func (c *Client) send(
+ ctx context.Context, messages []api.Message, opts *api.Options, stream bool,
+) (*httpResponse, error) {
+ body, err := c.BuildRequestBody(messages, opts, stream)
+ if err != nil {
+ return nil, err
+ }
+ target := c.URL()
+ req, data, err := c.cfg.Endpoint.NewRequest(ctx, target, body, stream)
+ if err != nil {
+ return nil, err
+ }
+ // anthropic-version is mandatory; an empty value is rejected with 400, so
+ // fall back to the baseline version when the catalog left it unset.
+ version := c.cfg.Settings.Version
+ if version == "" {
+ version = defaultAnthropicVersion
+ }
+ req.Header.Set("anthropic-version", version)
+ if beta := c.betaHeader(c.planThinking(opts), opts, req.Header.Get("anthropic-beta")); beta != "" {
+ req.Header.Set("anthropic-beta", beta)
+ }
+ api.LogRequest(ctx, target, c.cfg.Endpoint.Model, data, stream)
+ resp, err := c.cfg.Endpoint.Do(req)
+ if err != nil {
+ return nil, err
+ }
+ return &httpResponse{body: resp.Body, contentType: resp.Header.Get("Content-Type"), data: data}, nil
+}
+
+type httpResponse struct {
+ body io.ReadCloser
+ contentType string
+ data []byte
+}
+
+// Chat performs a non-streaming call.
+func (c *Client) Chat(ctx context.Context, messages []api.Message, opts *api.Options) (*types.ChatResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultChatTimeout)
+ defer cancel()
+ resp, err := c.send(ctx, messages, opts, false)
+ if err != nil {
+ // Claude's own models all accept images, but this protocol is also
+ // the compatibility surface of vendors whose text-only models do
+ // not, and the other three clients already degrade this way.
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Request] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, false)
+ }
+ if err != nil {
+ return nil, err
+ }
+ }
+ defer func() { _ = resp.body.Close() }()
+ raw, err := io.ReadAll(resp.body)
+ if err != nil {
+ return nil, fmt.Errorf("read response: %w", err)
+ }
+ var result *types.ChatResponse
+ if strings.Contains(strings.ToLower(resp.contentType), "text/event-stream") {
+ // Some proxies answer non-stream calls with SSE; consume it fully.
+ result, err = c.collectStream(ctx, strings.NewReader(string(raw)))
+ } else {
+ result, err = c.parseResponse(raw)
+ }
+ if err != nil {
+ return nil, err
+ }
+ api.LogUsage(ctx, c.cfg.Endpoint.Model, &result.Usage)
+ return result, nil
+}
+
+// ChatStream performs a streaming call.
+func (c *Client) ChatStream(
+ ctx context.Context, messages []api.Message, opts *api.Options,
+) (<-chan types.StreamResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultStreamTimeout)
+ resp, err := c.send(ctx, messages, opts, true)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Stream] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, true)
+ }
+ if err != nil {
+ cancel()
+ return nil, err
+ }
+ }
+ ch := make(chan types.StreamResponse)
+ dumper := api.NewStreamPacketDumper(c.cfg.Endpoint.Model, json.RawMessage(resp.data))
+ go func() {
+ defer cancel()
+ defer close(ch)
+ defer func() { _ = resp.body.Close() }()
+ if dumper != nil {
+ defer dumper.Close()
+ }
+ c.processStream(ctx, resp.body, ch, dumper)
+ }()
+ return ch, nil
+}
+
+// --- decoding ---
+
+type usageBlock struct {
+ InputTokens int `json:"input_tokens"`
+ OutputTokens int `json:"output_tokens"`
+ CacheCreationInputTokens *int `json:"cache_creation_input_tokens"`
+ CacheReadInputTokens *int `json:"cache_read_input_tokens"`
+}
+
+type responseBlock struct {
+ Type string `json:"type"`
+ Text string `json:"text"`
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Input json.RawMessage `json:"input"`
+ Thinking string `json:"thinking"`
+ Signature string `json:"signature"`
+ Data string `json:"data"`
+}
+
+type response struct {
+ Type string `json:"type"`
+ Content []responseBlock `json:"content"`
+ StopReason string `json:"stop_reason"`
+ Usage usageBlock `json:"usage"`
+ Error *struct {
+ Type string `json:"type"`
+ Message string `json:"message"`
+ } `json:"error,omitempty"`
+}
+
+type streamEvent struct {
+ Type string `json:"type"`
+ Index int `json:"index"`
+ ContentBlock *responseBlock `json:"content_block,omitempty"`
+ Message *struct {
+ Usage usageBlock `json:"usage"`
+ } `json:"message,omitempty"`
+ Delta *struct {
+ Type string `json:"type"`
+ Text string `json:"text"`
+ Thinking string `json:"thinking"`
+ Signature string `json:"signature"`
+ StopReason string `json:"stop_reason"`
+ PartialJSON string `json:"partial_json"`
+ } `json:"delta,omitempty"`
+ Usage *usageBlock `json:"usage,omitempty"`
+ Error *struct {
+ Type string `json:"type"`
+ Message string `json:"message"`
+ } `json:"error,omitempty"`
+}
+
+func (c *Client) usageFrom(u usageBlock) types.TokenUsage {
+ read := valueOrZero(u.CacheReadInputTokens)
+ write := valueOrZero(u.CacheCreationInputTokens)
+ prompt := u.InputTokens + read + write
+ out := types.TokenUsage{
+ PromptTokens: prompt, CompletionTokens: u.OutputTokens, TotalTokens: prompt + u.OutputTokens,
+ }
+ reported := u.CacheReadInputTokens != nil || u.CacheCreationInputTokens != nil
+ if !reported && !c.cfg.Settings.PromptCacheAccounting {
+ out.MarkPromptCacheUnsupported()
+ return out
+ }
+ out.SetPromptCacheUsage(read, write, max(0, prompt-read), reported)
+ return out
+}
+
+func (c *Client) parseResponse(raw []byte) (*types.ChatResponse, error) {
+ var resp response
+ if err := json.Unmarshal(raw, &resp); err != nil {
+ return nil, fmt.Errorf("decode response: %w", err)
+ }
+ if resp.Error != nil && resp.Error.Message != "" {
+ return nil, fmt.Errorf("API error: %s", resp.Error.Message)
+ }
+ result := &types.ChatResponse{Usage: c.usageFrom(resp.Usage)}
+ var text, thinking []string
+ // Interleaved thinking puts several signed thinking blocks in one reply,
+ // each signed over its own text, so they are kept separately for replay.
+ // ReasoningContent / ReasoningSignature stay filled for readers and for
+ // older stored turns, but they are no longer what goes back on the wire.
+ var stored []thinkingBlock
+ for _, block := range resp.Content {
+ switch block.Type {
+ case "text":
+ if block.Text != "" {
+ text = append(text, block.Text)
+ }
+ case "thinking":
+ thinking = append(thinking, block.Thinking)
+ stored = append(stored, newThinkingBlock(block.Thinking, block.Signature))
+ if block.Signature != "" {
+ result.ReasoningSignature = api.TagSignature(api.APIAnthropicMessages, block.Signature)
+ }
+ case "redacted_thinking":
+ stored = append(stored, newRedactedThinkingBlock(block.Data))
+ case "tool_use":
+ input := string(block.Input)
+ if input == "" {
+ input = "{}"
+ }
+ result.ToolCalls = append(result.ToolCalls, types.LLMToolCall{
+ ID: block.ID, Type: "function",
+ Function: types.FunctionCall{Name: block.Name, Arguments: input},
+ })
+ }
+ }
+ result.Content = strings.Join(text, "")
+ result.ReasoningContent = strings.Join(thinking, "")
+ if blocks := thinkingBlocksMetadata(stored); blocks != nil {
+ result.ReasoningMetadata = types.ProviderMetadata{MetadataThinkingBlocks: blocks}
+ }
+ result.FinishReason = mapStopReason(resp.StopReason, len(result.ToolCalls), false)
+ return result, nil
+}
+
+// toolInput accumulates one streamed tool_use block.
+type toolInput struct {
+ call types.LLMToolCall
+ initial string
+ json strings.Builder
+ closed bool
+}
+
+// streamState tracks per-index content blocks of one streamed message.
+type streamState struct {
+ tools map[int]*toolInput
+ toolOrder []int
+ blockType map[int]string
+ signature string
+ // thinking accumulates each thinking / redacted_thinking block by its
+ // content-block index, and thinkingOrder keeps the order they started in.
+ // Interleaved thinking sends several, each with its own signature_delta;
+ // accumulating into one string would splice two signatures together and
+ // produce one that verifies against nothing.
+ thinking map[int]*thinkingBlock
+ thinkingOrder []int
+ stop string
+ usage *types.TokenUsage
+}
+
+func newStreamState() *streamState {
+ return &streamState{
+ tools: map[int]*toolInput{},
+ blockType: map[int]string{},
+ thinking: map[int]*thinkingBlock{},
+ }
+}
+
+// thinkingAt returns the block being streamed at this content-block index,
+// creating it on first use. A vendor that sends deltas without a
+// content_block_start still gets a block rather than losing the text.
+func (s *streamState) thinkingAt(index int, blockType string) *thinkingBlock {
+ if b, ok := s.thinking[index]; ok {
+ return b
+ }
+ b := &thinkingBlock{Type: blockType}
+ s.thinking[index] = b
+ s.thinkingOrder = append(s.thinkingOrder, index)
+ return b
+}
+
+// thinkingBlocks returns the finished blocks in the order Claude sent them.
+func (s *streamState) thinkingBlocks() []thinkingBlock {
+ blocks := make([]thinkingBlock, 0, len(s.thinkingOrder))
+ for _, index := range s.thinkingOrder {
+ if b := s.thinking[index]; b != nil {
+ blocks = append(blocks, *b)
+ }
+ }
+ return blocks
+}
+
+func (s *streamState) calls() []types.LLMToolCall {
+ indexes := make([]int, 0, len(s.tools))
+ for index := range s.tools {
+ indexes = append(indexes, index)
+ }
+ sort.Ints(indexes)
+ var calls []types.LLMToolCall
+ for _, index := range indexes {
+ t := s.tools[index]
+ if !t.closed {
+ // A cut-off stream often starts the next tool_use with {}. Executing
+ // that empty object is worse than omitting it.
+ continue
+ }
+ call := t.call
+ call.Function.Arguments = t.initial
+ if t.json.Len() > 0 {
+ call.Function.Arguments = t.json.String()
+ }
+ calls = append(calls, call)
+ }
+ return calls
+}
+
+func (s *streamState) incomplete() bool {
+ for _, t := range s.tools {
+ if !t.closed {
+ return true
+ }
+ }
+ return false
+}
+
+func (s *streamState) toolIndex(blockIndex int) int {
+ for i, idx := range s.toolOrder {
+ if idx == blockIndex {
+ return i
+ }
+ }
+ s.toolOrder = append(s.toolOrder, blockIndex)
+ return len(s.toolOrder) - 1
+}
+
+// consume folds one event into the state and returns the protocol-neutral
+// delta to hand to the assembler (may be empty).
+func (c *Client) consume(s *streamState, ev streamEvent) api.Delta {
+ var d api.Delta
+ switch ev.Type {
+ case "message_start":
+ if ev.Message != nil {
+ u := c.usageFrom(ev.Message.Usage)
+ s.usage = &u
+ }
+ case "content_block_start":
+ if ev.ContentBlock == nil {
+ break
+ }
+ s.blockType[ev.Index] = ev.ContentBlock.Type
+ switch ev.ContentBlock.Type {
+ case "tool_use":
+ initial := string(ev.ContentBlock.Input)
+ if initial == "" || initial == "null" {
+ initial = "{}"
+ }
+ s.tools[ev.Index] = &toolInput{
+ initial: initial,
+ call: types.LLMToolCall{
+ ID: ev.ContentBlock.ID, Type: "function",
+ Function: types.FunctionCall{Name: ev.ContentBlock.Name},
+ },
+ }
+ d.ToolCalls = []api.ToolCallDelta{{
+ Index: s.toolIndex(ev.Index), ID: ev.ContentBlock.ID, Type: "function", Name: ev.ContentBlock.Name,
+ }}
+ case "redacted_thinking":
+ s.thinkingAt(ev.Index, "redacted_thinking").Data = ev.ContentBlock.Data
+ case "thinking":
+ block := s.thinkingAt(ev.Index, "thinking")
+ if ev.ContentBlock.Thinking != "" {
+ block.Thinking += ev.ContentBlock.Thinking
+ d.Reasoning = ev.ContentBlock.Thinking
+ }
+ case "text":
+ if ev.ContentBlock.Text != "" {
+ d.Content = ev.ContentBlock.Text
+ }
+ }
+ case "content_block_delta":
+ if ev.Delta == nil {
+ break
+ }
+ switch ev.Delta.Type {
+ case "text_delta":
+ d.Content = ev.Delta.Text
+ case "thinking_delta":
+ d.Reasoning = ev.Delta.Thinking
+ s.thinkingAt(ev.Index, "thinking").Thinking += ev.Delta.Thinking
+ case "signature_delta":
+ // The signature belongs to the block at this index; the top-level
+ // field keeps carrying the last one for readers that still use it.
+ block := s.thinkingAt(ev.Index, "thinking")
+ block.Signature += ev.Delta.Signature
+ s.signature = block.Signature
+ case "input_json_delta":
+ if t := s.tools[ev.Index]; t != nil {
+ t.json.WriteString(ev.Delta.PartialJSON)
+ d.ToolCalls = []api.ToolCallDelta{{Index: s.toolIndex(ev.Index), Arguments: ev.Delta.PartialJSON}}
+ }
+ }
+ case "content_block_stop":
+ if t := s.tools[ev.Index]; t != nil {
+ t.closed = true
+ if t.json.Len() == 0 {
+ // No input_json_delta carried any payload — an argument-less
+ // tool, or a vendor that puts the whole input on
+ // content_block_start. The assembler only emits its early
+ // ResponseTypeToolCall marker once a chunk updates the
+ // arguments of an already-named call, so replay the initial
+ // input here. Without it the UI never learns the call started.
+ // The final arguments are unchanged: calls() uses t.initial too.
+ d.ToolCalls = []api.ToolCallDelta{{Index: s.toolIndex(ev.Index), Arguments: t.initial}}
+ }
+ }
+ case "message_delta":
+ if ev.Delta != nil && ev.Delta.StopReason != "" {
+ s.stop = ev.Delta.StopReason
+ }
+ if ev.Usage != nil {
+ u := c.usageFrom(*ev.Usage)
+ if s.usage != nil {
+ // message_delta carries cumulative output tokens; input
+ // counters arrived on message_start.
+ u.PromptTokens = max(u.PromptTokens, s.usage.PromptTokens)
+ u.SetPromptCacheUsage(
+ max(u.CacheReadTokens, s.usage.CacheReadTokens),
+ max(u.CacheWriteTokens, s.usage.CacheWriteTokens),
+ max(0, u.PromptTokens-max(u.CacheReadTokens, s.usage.CacheReadTokens)),
+ u.CacheReported || s.usage.CacheReported,
+ )
+ u.TotalTokens = u.PromptTokens + u.CompletionTokens
+ }
+ s.usage = &u
+ }
+ }
+ return d
+}
+
+func (c *Client) processStream(
+ ctx context.Context, body io.Reader, ch chan<- types.StreamResponse, dumper *api.StreamPacketDumper,
+) {
+ assembler := api.NewStreamAssembler(ctx, c.cfg.Endpoint.Model)
+ state := newStreamState()
+ reader := api.NewSSEReader(body)
+ finish := func() {
+ calls := state.calls()
+ assembler.ReplaceToolCalls(calls)
+ assembler.ReasoningSignature = api.TagSignature(api.APIAnthropicMessages, state.signature)
+ if blocks := thinkingBlocksMetadata(state.thinkingBlocks()); blocks != nil {
+ assembler.ReasoningMetadata = types.ProviderMetadata{MetadataThinkingBlocks: blocks}
+ }
+ if state.usage != nil {
+ assembler.SetUsage(*state.usage)
+ }
+ assembler.Process(ch, api.Delta{FinishReason: mapStopReason(state.stop, len(calls), state.incomplete())})
+ assembler.End(ch)
+ }
+ for {
+ // The consumer went away (client disconnect, aborted agent turn): stop
+ // decoding a stream nobody will read instead of spinning to EOF.
+ if assembler.Aborted() {
+ return
+ }
+ event, err := reader.ReadEvent()
+ if err != nil {
+ if err == io.EOF {
+ finish()
+ } else {
+ assembler.Fail(ch, err)
+ }
+ return
+ }
+ if event == nil || event.Done {
+ if event != nil && event.Done {
+ finish()
+ return
+ }
+ continue
+ }
+ if len(event.Data) == 0 {
+ continue
+ }
+ if dumper != nil {
+ raw := make([]byte, len(event.Data))
+ copy(raw, event.Data)
+ dumper.WritePacketRaw(raw)
+ }
+ var ev streamEvent
+ if err := json.Unmarshal(event.Data, &ev); err != nil {
+ assembler.Fail(ch, fmt.Errorf("decode SSE response: %w", err))
+ return
+ }
+ if ev.Error != nil && ev.Error.Message != "" {
+ assembler.Fail(ch, fmt.Errorf("API stream error: %s", ev.Error.Message))
+ return
+ }
+ delta := c.consume(state, ev)
+ if delta.Content != "" || delta.Reasoning != "" || len(delta.ToolCalls) > 0 {
+ assembler.Process(ch, delta)
+ }
+ if ev.Type == "message_stop" {
+ finish()
+ return
+ }
+ }
+}
+
+// collectStream folds an SSE body into one ChatResponse (used when a proxy
+// answers a non-stream request with SSE).
+func (c *Client) collectStream(ctx context.Context, body io.Reader) (*types.ChatResponse, error) {
+ ch := make(chan types.StreamResponse, 64)
+ go func() {
+ defer close(ch)
+ c.processStream(ctx, body, ch, nil)
+ }()
+ result := &types.ChatResponse{}
+ var content, reasoning strings.Builder
+ for chunk := range ch {
+ switch chunk.ResponseType {
+ case types.ResponseTypeError:
+ return nil, fmt.Errorf("%s", chunk.Content)
+ case types.ResponseTypeThinking:
+ reasoning.WriteString(chunk.Content)
+ case types.ResponseTypeAnswer:
+ content.WriteString(chunk.Content)
+ if len(chunk.ToolCalls) > 0 {
+ result.ToolCalls = chunk.ToolCalls
+ }
+ if chunk.Usage != nil {
+ result.Usage = *chunk.Usage
+ }
+ if chunk.FinishReason != "" {
+ result.FinishReason = chunk.FinishReason
+ }
+ if sig, ok := chunk.Data["reasoning_signature"].(string); ok {
+ result.ReasoningSignature = sig
+ }
+ if md, ok := chunk.Data["reasoning_metadata"].(types.ProviderMetadata); ok {
+ result.ReasoningMetadata = md
+ }
+ }
+ }
+ result.Content = content.String()
+ result.ReasoningContent = reasoning.String()
+ return result, nil
+}
+
+func valueOrZero(v *int) int {
+ if v == nil {
+ return 0
+ }
+ return *v
+}
diff --git a/internal/models/api/anthropicmessages/request.go b/internal/models/api/anthropicmessages/request.go
new file mode 100644
index 000000000..a57e4cc72
--- /dev/null
+++ b/internal/models/api/anthropicmessages/request.go
@@ -0,0 +1,529 @@
+// Package anthropicmessages implements the Anthropic Messages wire protocol
+// (https://docs.anthropic.com/en/api/messages). MiniMax, Zhipu, Moonshot and
+// Volcengine expose the same protocol on an ".../anthropic" base URL, so the
+// package contains no vendor names: every deviation is a
+// catalog.AnthropicMessagesSettings field.
+package anthropicmessages
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "net/url"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// Config is everything the client needs, already resolved by the catalog.
+type Config struct {
+ Endpoint api.Endpoint
+ Settings catalog.AnthropicMessagesSettings
+ ThinkingLevels api.ThinkingLevelMap
+ Reasoning bool
+}
+
+// Metadata keys used on messages and tool calls.
+const (
+ // MetadataRedactedThinking stores redacted_thinking blocks (JSON array
+ // of {"data": ...}) that must be replayed verbatim. Superseded by
+ // MetadataThinkingBlocks; still read so assistant turns stored by an
+ // earlier build keep replaying.
+ MetadataRedactedThinking = "anthropic_redacted_thinking"
+ // MetadataThinkingBlocks stores the turn's thinking and
+ // redacted_thinking blocks exactly as Claude emitted them, in order.
+ //
+ // Two properties make this the only correct source for replay. First,
+ // Claude signs the exact text of each block, so one assistant turn with
+ // interleaved thinking carries several (text, signature) pairs that a
+ // single ReasoningContent / ReasoningSignature pair cannot represent —
+ // concatenating them produces a signature that matches nothing. Second,
+ // ReasoningContent is rewritten downstream (resource-handle encoding,
+ // citation compaction, special-token neutralisation) for the benefit of
+ // readers and of the next prompt, which invalidates the signature over
+ // it. This metadata is opaque to all of that and travels unchanged.
+ MetadataThinkingBlocks = "anthropic_thinking_blocks"
+)
+
+// thinkingBlock is one stored thinking or redacted_thinking block. It is the
+// wire shape, so replay is a copy rather than a reconstruction.
+type thinkingBlock struct {
+ Type string `json:"type"`
+ Thinking string `json:"thinking,omitempty"`
+ Signature string `json:"signature,omitempty"`
+ Data string `json:"data,omitempty"`
+}
+
+// thinkingBlocksMetadata renders the blocks for storage on the assistant
+// message. It returns nil when there is nothing to replay.
+func thinkingBlocksMetadata(blocks []thinkingBlock) json.RawMessage {
+ if len(blocks) == 0 {
+ return nil
+ }
+ data, err := json.Marshal(blocks)
+ if err != nil {
+ return nil
+ }
+ return data
+}
+
+// newThinkingBlock records a signed thinking block.
+func newThinkingBlock(thinking, signature string) thinkingBlock {
+ return thinkingBlock{Type: "thinking", Thinking: thinking, Signature: signature}
+}
+
+// newRedactedThinkingBlock records an opaque redacted_thinking block.
+func newRedactedThinkingBlock(data string) thinkingBlock {
+ return thinkingBlock{Type: "redacted_thinking", Data: data}
+}
+
+type cacheControl struct {
+ Type string `json:"type"`
+ TTL string `json:"ttl,omitempty"`
+}
+
+type contentBlock struct {
+ Type string `json:"type"`
+ Text string `json:"text,omitempty"`
+ CacheControl *cacheControl `json:"cache_control,omitempty"`
+ ID string `json:"id,omitempty"`
+ Name string `json:"name,omitempty"`
+ Input json.RawMessage `json:"input,omitempty"`
+ ToolUseID string `json:"tool_use_id,omitempty"`
+ Content any `json:"content,omitempty"`
+ Thinking string `json:"thinking,omitempty"`
+ Signature string `json:"signature,omitempty"`
+ Data string `json:"data,omitempty"`
+ Source *imageSource `json:"source,omitempty"`
+}
+
+type imageSource struct {
+ Type string `json:"type"` // "base64" | "url"
+ MediaType string `json:"media_type,omitempty"`
+ Data string `json:"data,omitempty"`
+ URL string `json:"url,omitempty"`
+}
+
+type message struct {
+ Role string `json:"role"`
+ Content any `json:"content"`
+}
+
+type tool struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
+ InputSchema json.RawMessage `json:"input_schema"`
+ CacheControl *cacheControl `json:"cache_control,omitempty"`
+}
+
+type toolChoice struct {
+ Type string `json:"type"`
+ Name string `json:"name,omitempty"`
+ DisableParallelToolUse *bool `json:"disable_parallel_tool_use,omitempty"`
+}
+
+// thinkingPlan is the resolved thinking request for one call.
+type thinkingPlan struct {
+ enabled bool
+ body map[string]any // the "thinking" object, nil when omitted
+ effort string // output_config.effort, "" when omitted
+ budget int // budget_tokens in budget mode
+}
+
+func (c *Client) planThinking(opts *api.Options) thinkingPlan {
+ s := c.cfg.Settings
+ levels := c.cfg.ThinkingLevels
+ level, requested := opts.Reasoning()
+ if !requested {
+ return thinkingPlan{}
+ }
+ if level.Graded() {
+ level = levels.Clamp(level)
+ }
+ if !level.Enabled() {
+ if levels.Supports(api.ReasoningOff) && s.ThinkingMode == catalog.AnthropicThinkingAdaptive {
+ return thinkingPlan{body: map[string]any{"type": "disabled"}}
+ }
+ // Budget mode: omitting the thinking object disables it.
+ return thinkingPlan{}
+ }
+ plan := thinkingPlan{enabled: true}
+ switch s.ThinkingMode {
+ case catalog.AnthropicThinkingAdaptive:
+ plan.body = map[string]any{"type": "adaptive"}
+ if level.Graded() && s.SupportsEffort {
+ plan.effort = levels.Value(level)
+ }
+ default:
+ budget := 0
+ if opts != nil && opts.ThinkingBudgetTokens > 0 {
+ budget = opts.ThinkingBudgetTokens
+ } else {
+ key := level
+ if !key.Graded() {
+ key = api.ReasoningMedium
+ }
+ budget = s.ThinkingBudgets[key]
+ }
+ if budget < 1024 {
+ budget = 1024
+ }
+ plan.budget = budget
+ plan.body = map[string]any{"type": "enabled", "budget_tokens": budget}
+ }
+ return plan
+}
+
+// BuildRequestBody is the golden-test entry point.
+func (c *Client) BuildRequestBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error) {
+ s := c.cfg.Settings
+ body := map[string]any{"model": c.cfg.Endpoint.Model}
+ if stream {
+ body["stream"] = true
+ }
+ plan := c.planThinking(opts)
+
+ maxTokens := opts.CompletionBudget()
+ if maxTokens <= 0 {
+ maxTokens = s.DefaultMaxTokens
+ if maxTokens <= 0 {
+ maxTokens = 4096
+ }
+ }
+ if plan.budget > 0 && maxTokens <= plan.budget {
+ // max_tokens must exceed budget_tokens; keep the caller's answer
+ // budget on top of the thinking budget.
+ maxTokens = plan.budget + max(maxTokens, 1024)
+ }
+ body["max_tokens"] = maxTokens
+
+ if opts != nil {
+ if s.SupportsTemperature && opts.Temperature > 0 && (!plan.enabled || s.TemperatureWithThinking) {
+ body["temperature"] = opts.Temperature
+ } else if s.SupportsTopP && opts.TopP > 0 && !plan.enabled {
+ // temperature and top_p are mutually exclusive on current models;
+ // temperature wins when both are set.
+ body["top_p"] = opts.TopP
+ }
+ }
+
+ retention := api.ResolveCacheRetention(opts)
+ var marker *cacheControl
+ if s.SupportsCacheControl {
+ if m := api.CacheControlFor(retention, s.LongCacheTTL); m != nil {
+ marker = &cacheControl{Type: m.Type, TTL: m.TTL}
+ }
+ }
+
+ if opts != nil && len(opts.Tools) > 0 {
+ tools := make([]tool, 0, len(opts.Tools))
+ for _, t := range opts.Tools {
+ schema := t.Function.Parameters
+ if len(schema) == 0 {
+ schema = json.RawMessage(`{"type":"object","properties":{}}`)
+ }
+ tools = append(tools, tool{Name: t.Function.Name, Description: t.Function.Description, InputSchema: schema})
+ }
+ if marker != nil && s.SupportsCacheControlOnTool {
+ tools[len(tools)-1].CacheControl = marker
+ }
+ body["tools"] = tools
+ choice := &toolChoice{Type: "auto"}
+ switch opts.ToolChoice {
+ case "", "auto":
+ case "required":
+ choice.Type = "any"
+ case "none":
+ choice.Type = "none"
+ default:
+ choice.Type, choice.Name = "tool", opts.ToolChoice
+ }
+ if opts.ParallelToolCalls != nil && choice.Type != "none" {
+ disable := !*opts.ParallelToolCalls
+ choice.DisableParallelToolUse = &disable
+ }
+ body["tool_choice"] = choice
+ }
+
+ systemParts, converted := c.convertMessages(messages, opts)
+ systemText := strings.Join(systemParts, "\n\n")
+ if marker == nil {
+ if systemText != "" {
+ body["system"] = systemText
+ }
+ } else {
+ if systemText != "" {
+ body["system"] = []contentBlock{{Type: "text", Text: systemText, CacheControl: marker}}
+ }
+ if len(converted) > 0 {
+ last := &converted[len(converted)-1]
+ switch content := last.Content.(type) {
+ case string:
+ if content != "" {
+ last.Content = []contentBlock{{Type: "text", Text: content, CacheControl: marker}}
+ }
+ case []contentBlock:
+ if len(content) > 0 {
+ content[len(content)-1].CacheControl = marker
+ }
+ }
+ }
+ }
+ if converted == nil {
+ // "messages" is required and must be an array: a nil slice would
+ // marshal to null and the API answers 400. A request whose only
+ // entries were system messages legitimately produces no turns.
+ converted = []message{}
+ }
+ body["messages"] = converted
+
+ if plan.body != nil {
+ body["thinking"] = plan.body
+ }
+ if plan.effort != "" {
+ body["output_config"] = map[string]any{"effort": plan.effort}
+ }
+ for k, v := range s.ExtraBody {
+ if _, exists := body[k]; !exists {
+ body[k] = v
+ }
+ }
+ return body, nil
+}
+
+// betaHeader composes the anthropic-beta header for this request.
+func (c *Client) betaHeader(plan thinkingPlan, opts *api.Options, userValue string) string {
+ s := c.cfg.Settings
+ seen := map[string]bool{}
+ var betas []string
+ add := func(v string) {
+ for _, part := range strings.Split(v, ",") {
+ part = strings.TrimSpace(part)
+ if part != "" && !seen[part] {
+ seen[part] = true
+ betas = append(betas, part)
+ }
+ }
+ }
+ for _, b := range s.BetaHeaders {
+ add(b)
+ }
+ if plan.enabled && s.ThinkingMode != catalog.AnthropicThinkingAdaptive && s.InterleavedThinkingBeta != "" &&
+ opts != nil && len(opts.Tools) > 0 {
+ add(s.InterleavedThinkingBeta)
+ }
+ add(userValue)
+ return strings.Join(betas, ",")
+}
+
+// convertMessages maps neutral messages onto Anthropic messages. System
+// messages are lifted out; tool calls become tool_use blocks; consecutive
+// tool results merge into one user message; thinking blocks are replayed
+// only when they carry a signature (the API rejects unsigned ones).
+func (c *Client) convertMessages(messages []api.Message, _ *api.Options) ([]string, []message) {
+ var system []string
+ var result []message
+ for _, msg := range messages {
+ msg = api.NeutralizeMessageSpecialTokens(msg)
+ content := strings.TrimSpace(msg.Content)
+ switch msg.Role {
+ case "system":
+ if content == "" {
+ content = textFromMultiContent(msg.MultiContent)
+ }
+ if content != "" {
+ system = append(system, content)
+ }
+ case "assistant":
+ blocks := c.assistantBlocks(msg, content)
+ if len(blocks) == 0 {
+ continue
+ }
+ if len(blocks) == 1 && blocks[0].Type == "text" && len(msg.ToolCalls) == 0 {
+ result = append(result, message{Role: "assistant", Content: blocks[0].Text})
+ continue
+ }
+ result = append(result, message{Role: "assistant", Content: blocks})
+ case "tool":
+ block := contentBlock{Type: "tool_result", ToolUseID: msg.ToolCallID, Content: msg.Content}
+ if len(result) > 0 && result[len(result)-1].Role == "user" {
+ if blocks, ok := result[len(result)-1].Content.([]contentBlock); ok && len(blocks) > 0 &&
+ blocks[0].Type == "tool_result" {
+ result[len(result)-1].Content = append(blocks, block)
+ continue
+ }
+ }
+ result = append(result, message{Role: "user", Content: []contentBlock{block}})
+ default:
+ blocks := userBlocks(msg, content)
+ if len(blocks) == 0 {
+ continue
+ }
+ if len(blocks) == 1 && blocks[0].Type == "text" {
+ result = append(result, message{Role: "user", Content: blocks[0].Text})
+ continue
+ }
+ result = append(result, message{Role: "user", Content: blocks})
+ }
+ }
+ return system, result
+}
+
+func (c *Client) assistantBlocks(msg api.Message, content string) []contentBlock {
+ blocks := replayThinkingBlocks(msg)
+ if content == "" {
+ content = textFromMultiContent(msg.MultiContent)
+ }
+ if content != "" {
+ blocks = append(blocks, contentBlock{Type: "text", Text: content})
+ }
+ for _, call := range msg.ToolCalls {
+ input := json.RawMessage(call.Function.Arguments)
+ if len(input) == 0 || !json.Valid(input) {
+ input = json.RawMessage(`{}`)
+ }
+ blocks = append(blocks, contentBlock{Type: "tool_use", ID: call.ID, Name: call.Function.Name, Input: input})
+ }
+ return blocks
+}
+
+// replayThinkingBlocks rebuilds the leading thinking / redacted_thinking
+// blocks of a stored assistant turn.
+//
+// Claude requires them back verbatim whenever that turn also carries tool_use
+// and extended thinking was on: dropping them answers 400 ("Expected
+// `thinking` or `redacted_thinking`, but found `tool_use`"), and altering the
+// signed text answers 400 as well. Preference order is therefore the verbatim
+// metadata first, then the legacy single-block fields for turns stored before
+// that metadata existed.
+func replayThinkingBlocks(msg api.Message) []contentBlock {
+ if raw, ok := msg.ReasoningMetadata[MetadataThinkingBlocks]; ok && len(raw) > 0 {
+ var stored []thinkingBlock
+ if err := json.Unmarshal(raw, &stored); err == nil {
+ blocks := make([]contentBlock, 0, len(stored))
+ for _, b := range stored {
+ switch b.Type {
+ case "thinking":
+ // An unsigned block cannot go back: Claude rejects a
+ // thinking block without a signature. It means the stream
+ // ended inside that block (truncation), so it is the last
+ // one and produced no tool_use of its own. Skip just it —
+ // discarding the whole turn's blocks instead would strip
+ // the signed ones that a completed tool_use in the same
+ // turn still needs, which is the 400 this replay exists
+ // to prevent.
+ if b.Signature == "" {
+ continue
+ }
+ blocks = append(blocks, contentBlock{
+ Type: "thinking", Thinking: b.Thinking, Signature: b.Signature,
+ })
+ case "redacted_thinking":
+ blocks = append(blocks, contentBlock{Type: "redacted_thinking", Data: b.Data})
+ }
+ }
+ return blocks
+ }
+ }
+
+ var blocks []contentBlock
+ if raw, ok := msg.ReasoningMetadata[MetadataRedactedThinking]; ok && len(raw) > 0 {
+ var redacted []string
+ if err := json.Unmarshal(raw, &redacted); err == nil {
+ for _, data := range redacted {
+ blocks = append(blocks, contentBlock{Type: "redacted_thinking", Data: data})
+ }
+ }
+ }
+ sig := api.SignatureFor(api.APIAnthropicMessages, msg.ReasoningSignature)
+ if msg.ReasoningContent != "" && sig != "" {
+ blocks = append(blocks, contentBlock{
+ Type: "thinking", Thinking: msg.ReasoningContent, Signature: sig,
+ })
+ }
+ return blocks
+}
+
+func userBlocks(msg api.Message, content string) []contentBlock {
+ var blocks []contentBlock
+ addImage := func(ref string) {
+ if src := imageSourceFor(ref); src != nil {
+ blocks = append(blocks, contentBlock{Type: "image", Source: src})
+ }
+ }
+ if len(msg.MultiContent) > 0 {
+ for _, part := range msg.MultiContent {
+ switch part.Type {
+ case "text":
+ if t := strings.TrimSpace(part.Text); t != "" {
+ blocks = append(blocks, contentBlock{Type: "text", Text: t})
+ }
+ case "image_url":
+ if part.ImageURL != nil {
+ addImage(part.ImageURL.URL)
+ }
+ }
+ }
+ if content != "" {
+ blocks = append(blocks, contentBlock{Type: "text", Text: content})
+ }
+ return blocks
+ }
+ for _, img := range msg.Images {
+ addImage(img)
+ }
+ if content != "" {
+ blocks = append(blocks, contentBlock{Type: "text", Text: content})
+ }
+ return blocks
+}
+
+// imageSourceFor converts a data URI or URL into an image source block.
+func imageSourceFor(ref string) *imageSource {
+ ref = api.ResolveImageURLForLLM(ref)
+ if strings.HasPrefix(ref, "data:") {
+ semi := strings.Index(ref, ";base64,")
+ if semi < 0 {
+ return nil
+ }
+ mediaType := strings.TrimPrefix(ref[:semi], "data:")
+ data := ref[semi+len(";base64,"):]
+ if _, err := base64.StdEncoding.DecodeString(data); err != nil {
+ return nil
+ }
+ return &imageSource{Type: "base64", MediaType: mediaType, Data: data}
+ }
+ if u, err := url.Parse(ref); err == nil && (u.Scheme == "http" || u.Scheme == "https") {
+ return &imageSource{Type: "url", URL: ref}
+ }
+ return nil
+}
+
+func textFromMultiContent(parts []api.MessageContentPart) string {
+ if len(parts) == 0 {
+ return ""
+ }
+ textParts := make([]string, 0, len(parts))
+ for _, part := range parts {
+ if part.Type == "text" && strings.TrimSpace(part.Text) != "" {
+ textParts = append(textParts, strings.TrimSpace(part.Text))
+ }
+ }
+ return strings.Join(textParts, "\n")
+}
+
+// mapStopReason converts Anthropic stop reasons to the shared vocabulary.
+func mapStopReason(reason string, toolCalls int, incomplete bool) string {
+ switch {
+ case incomplete, reason == "":
+ return types.FinishReasonIncomplete
+ case reason == "max_tokens":
+ return "length"
+ case reason == "tool_use" || (toolCalls > 0 && reason == "end_turn"):
+ return "tool_calls"
+ case reason == "refusal":
+ return "content_filter"
+ }
+ return reason
+}
diff --git a/internal/models/api/endpoint.go b/internal/models/api/endpoint.go
new file mode 100644
index 000000000..062a6480a
--- /dev/null
+++ b/internal/models/api/endpoint.go
@@ -0,0 +1,158 @@
+package api
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ secutils "github.com/Tencent/WeKnora/internal/utils"
+)
+
+// AuthFunc stamps credentials onto an outbound request. body is the exact
+// bytes being sent so signing vendors can hash them.
+type AuthFunc func(req *http.Request, body []byte)
+
+// BearerAuth is the default: Authorization: Bearer <key>.
+func BearerAuth(apiKey string) AuthFunc {
+ return func(req *http.Request, _ []byte) {
+ if apiKey != "" {
+ req.Header.Set("Authorization", "Bearer "+apiKey)
+ }
+ }
+}
+
+// HeaderAuth writes the key under an arbitrary header (api-key for Azure,
+// x-api-key for Anthropic, x-goog-api-key for Gemini).
+func HeaderAuth(header, apiKey string) AuthFunc {
+ return func(req *http.Request, _ []byte) {
+ if apiKey != "" {
+ req.Header.Set(header, apiKey)
+ }
+ }
+}
+
+// NoAuth sends no credentials at all (local deployments).
+func NoAuth() AuthFunc { return func(*http.Request, []byte) {} }
+
+// Endpoint is everything a protocol client needs to reach one model.
+type Endpoint struct {
+ // BaseURL is the vendor root without a trailing slash.
+ BaseURL string
+ // URL, when set, is the complete request URL and overrides the protocol
+ // default of BaseURL + protocol path. Vendors with non-standard paths
+ // (Azure deployments, WeKnora Cloud) set it.
+ URL string
+ // Query is appended to the final URL (Azure api-version).
+ Query map[string]string
+ // Model is the name sent on the wire; ModelID is WeKnora's own identifier.
+ Model string
+ ModelID string
+ // Auth stamps credentials; Headers are static extra headers (vendor
+ // betas, user-configured custom headers). User headers never override
+ // the protocol's own reserved headers.
+ Auth AuthFunc
+ Headers map[string]string
+ // Client is the HTTP client; nil uses the shared SSRF-safe client.
+ Client *http.Client
+}
+
+// Resolve builds the request URL from the endpoint description.
+func (e Endpoint) Resolve(defaultPath string) string {
+ target := e.URL
+ if target == "" {
+ target = strings.TrimRight(e.BaseURL, "/") + defaultPath
+ }
+ if len(e.Query) == 0 {
+ return target
+ }
+ var b strings.Builder
+ b.WriteString(target)
+ sep := "?"
+ if strings.Contains(target, "?") {
+ sep = "&"
+ }
+ for k, v := range e.Query {
+ b.WriteString(sep)
+ b.WriteString(k)
+ b.WriteString("=")
+ b.WriteString(v)
+ sep = "&"
+ }
+ return b.String()
+}
+
+func (e Endpoint) httpClient() *http.Client {
+ if e.Client != nil {
+ return e.Client
+ }
+ return HTTPClient
+}
+
+// NewRequest prepares an authenticated JSON POST. The body is marshalled
+// once so signing vendors see exactly what is sent.
+func (e Endpoint) NewRequest(ctx context.Context, url string, body any, stream bool) (*http.Request, []byte, error) {
+ data, err := json.Marshal(body)
+ if err != nil {
+ return nil, nil, fmt.Errorf("marshal request: %w", err)
+ }
+ if err := secutils.ValidateURLForSSRF(url); err != nil {
+ return nil, nil, fmt.Errorf("endpoint SSRF check failed: %w", err)
+ }
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(data))
+ if err != nil {
+ return nil, nil, fmt.Errorf("create request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ if stream {
+ req.Header.Set("Accept", "text/event-stream")
+ }
+ if e.Auth != nil {
+ e.Auth(req, data)
+ }
+ // User headers are applied last but the helper skips reserved names so
+ // they cannot clobber auth or content negotiation.
+ secutils.ApplyCustomHeaders(req, e.Headers)
+ return req, data, nil
+}
+
+// Do sends the request and returns the response. Non-2xx responses are
+// turned into an error carrying the body so callers surface vendor messages.
+func (e Endpoint) Do(req *http.Request) (*http.Response, error) {
+ resp, err := e.httpClient().Do(req)
+ if err != nil {
+ return nil, fmt.Errorf("send request: %w", err)
+ }
+ if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+ _ = resp.Body.Close()
+ return nil, &HTTPError{StatusCode: resp.StatusCode, Body: string(body)}
+ }
+ return resp, nil
+}
+
+// HTTPError is a non-2xx vendor reply.
+type HTTPError struct {
+ StatusCode int
+ Body string
+}
+
+func (e *HTTPError) Error() string {
+ return fmt.Sprintf("API request failed with status %d: %s", e.StatusCode, e.Body)
+}
+
+// LogRequest emits the standard request log line with image payloads
+// compacted so data URIs do not flood the log.
+func LogRequest(ctx context.Context, url, model string, body []byte, stream bool) {
+ pretty := body
+ var buf bytes.Buffer
+ if err := json.Indent(&buf, body, "", " "); err == nil {
+ pretty = buf.Bytes()
+ }
+ logger.Infof(ctx, "[LLM Request] endpoint=%s, model=%s, stream=%v, request:\n%s",
+ url, model, stream, secutils.CompactImageDataURLForLog(string(pretty)))
+}
diff --git a/internal/models/api/googlegenai/client.go b/internal/models/api/googlegenai/client.go
new file mode 100644
index 000000000..184e5fa5c
--- /dev/null
+++ b/internal/models/api/googlegenai/client.go
@@ -0,0 +1,429 @@
+package googlegenai
+
+import (
+ "context"
+ "crypto/rand"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+const (
+ methodGenerate = "generateContent"
+ methodStreamGenerate = "streamGenerateContent"
+)
+
+// Client talks generateContent to one endpoint.
+type Client struct {
+ cfg Config
+}
+
+// New creates a client. The endpoint must already carry auth and headers.
+func New(cfg Config) *Client {
+ if cfg.ThinkingLevels == nil {
+ cfg.ThinkingLevels = api.ThinkingLevelMap{}
+ }
+ return &Client{cfg: cfg}
+}
+
+// GetModelName returns the wire model name.
+func (c *Client) GetModelName() string { return c.cfg.Endpoint.Model }
+
+// GetModelID returns WeKnora's model identifier.
+func (c *Client) GetModelID() string { return c.cfg.Endpoint.ModelID }
+
+// requestURL builds {base}/models/{model}:generateContent or
+// {base}/models/{model}:streamGenerateContent?alt=sse. A bare host base URL
+// gets Settings.APIVersionPrefix appended; an already versioned base is used
+// as-is. An explicit Endpoint.URL overrides the path entirely.
+func (c *Client) requestURL(stream bool) string {
+ ep := c.cfg.Endpoint
+ if ep.URL == "" {
+ base := strings.TrimRight(ep.BaseURL, "/")
+ if prefix := strings.Trim(c.cfg.Settings.APIVersionPrefix, "/"); prefix != "" && isBareHost(base) {
+ base += "/" + prefix
+ }
+ method := methodGenerate
+ if stream {
+ method = methodStreamGenerate
+ }
+ ep.URL = fmt.Sprintf("%s/models/%s:%s", base, ep.Model, method)
+ } else if stream && strings.HasSuffix(ep.URL, ":"+methodGenerate) {
+ // A vendor-supplied full URL names the non-streaming method; adding
+ // alt=sse to it would still return one buffered JSON document.
+ ep.URL = strings.TrimSuffix(ep.URL, ":"+methodGenerate) + ":" + methodStreamGenerate
+ }
+ if stream {
+ query := make(map[string]string, len(ep.Query)+1)
+ for k, v := range ep.Query {
+ query[k] = v
+ }
+ query["alt"] = "sse"
+ ep.Query = query
+ }
+ return ep.Resolve("")
+}
+
+func isBareHost(base string) bool {
+ u, err := url.Parse(base)
+ if err != nil {
+ return !strings.Contains(strings.TrimPrefix(strings.TrimPrefix(base, "https://"), "http://"), "/")
+ }
+ return u.Path == "" || u.Path == "/"
+}
+
+func (c *Client) send(
+ ctx context.Context, messages []api.Message, opts *api.Options, stream bool,
+) (*http.Response, []byte, error) {
+ body, err := c.BuildRequestBody(messages, opts, stream)
+ if err != nil {
+ return nil, nil, err
+ }
+ target := c.requestURL(stream)
+ req, data, err := c.cfg.Endpoint.NewRequest(ctx, target, body, stream)
+ if err != nil {
+ return nil, nil, err
+ }
+ api.LogRequest(ctx, target, c.cfg.Endpoint.Model, data, stream)
+ resp, err := c.cfg.Endpoint.Do(req)
+ if err != nil {
+ return nil, data, err
+ }
+ return resp, data, nil
+}
+
+// Chat performs a non-streaming generation.
+func (c *Client) Chat(ctx context.Context, messages []api.Message, opts *api.Options) (*types.ChatResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultChatTimeout)
+ defer cancel()
+
+ resp, _, err := c.send(ctx, messages, opts, false)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Request] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, _, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, false)
+ }
+ if err != nil {
+ return nil, fmt.Errorf("create chat completion: %w", err)
+ }
+ }
+ defer func() { _ = resp.Body.Close() }()
+ raw, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return nil, fmt.Errorf("read response: %w", err)
+ }
+ result, err := c.parseResponse(raw)
+ if err != nil {
+ return nil, err
+ }
+ api.LogUsage(ctx, c.cfg.Endpoint.Model, &result.Usage)
+ return result, nil
+}
+
+// ChatStream performs a streaming generation over SSE.
+func (c *Client) ChatStream(
+ ctx context.Context, messages []api.Message, opts *api.Options,
+) (<-chan types.StreamResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultStreamTimeout)
+
+ resp, data, err := c.send(ctx, messages, opts, true)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Stream] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, data, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, true)
+ }
+ if err != nil {
+ cancel()
+ return nil, fmt.Errorf("create chat completion stream: %w", err)
+ }
+ }
+
+ ch := make(chan types.StreamResponse)
+ dumper := api.NewStreamPacketDumper(c.cfg.Endpoint.Model, json.RawMessage(data))
+ if dumper != nil {
+ logger.Infof(ctx, "[LLM Stream Raw Dump] writing packets to %s", dumper.Path())
+ }
+ go func() {
+ defer cancel()
+ defer close(ch)
+ defer func() { _ = resp.Body.Close() }()
+ if dumper != nil {
+ defer dumper.Close()
+ }
+ c.processStream(ctx, resp.Body, ch, dumper)
+ }()
+ return ch, nil
+}
+
+// --- response decoding ---
+
+type rawFunctionCall struct {
+ ID string `json:"id,omitempty"`
+ Name string `json:"name"`
+ Args json.RawMessage `json:"args,omitempty"`
+}
+
+type rawPart struct {
+ Text string `json:"text,omitempty"`
+ Thought bool `json:"thought,omitempty"`
+ ThoughtSignature string `json:"thoughtSignature,omitempty"`
+ FunctionCall *rawFunctionCall `json:"functionCall,omitempty"`
+}
+
+type rawCandidate struct {
+ Content struct {
+ Role string `json:"role,omitempty"`
+ Parts []rawPart `json:"parts,omitempty"`
+ } `json:"content"`
+ FinishReason string `json:"finishReason,omitempty"`
+}
+
+type rawUsage struct {
+ PromptTokenCount int `json:"promptTokenCount"`
+ CandidatesTokenCount int `json:"candidatesTokenCount"`
+ ThoughtsTokenCount int `json:"thoughtsTokenCount"`
+ TotalTokenCount int `json:"totalTokenCount"`
+ CachedContentTokenCount *int `json:"cachedContentTokenCount"`
+}
+
+type rawResponse struct {
+ Candidates []rawCandidate `json:"candidates,omitempty"`
+ PromptFeedback *struct {
+ BlockReason string `json:"blockReason,omitempty"`
+ } `json:"promptFeedback,omitempty"`
+ UsageMetadata *rawUsage `json:"usageMetadata,omitempty"`
+ Error *struct {
+ Code int `json:"code"`
+ Message string `json:"message"`
+ Status string `json:"status"`
+ } `json:"error,omitempty"`
+}
+
+func (c *Client) usage(u rawUsage) types.TokenUsage {
+ out := types.TokenUsage{
+ PromptTokens: u.PromptTokenCount,
+ CompletionTokens: u.CandidatesTokenCount + u.ThoughtsTokenCount,
+ TotalTokens: u.TotalTokenCount,
+ }
+ if out.TotalTokens == 0 {
+ out.TotalTokens = out.PromptTokens + out.CompletionTokens
+ }
+ switch {
+ case u.CachedContentTokenCount != nil:
+ cached := *u.CachedContentTokenCount
+ out.SetPromptCacheUsage(cached, 0, max(0, u.PromptTokenCount-cached), true)
+ case c.cfg.Settings.PromptCacheAcct:
+ out.SetPromptCacheUsage(0, 0, 0, false)
+ default:
+ out.MarkPromptCacheUnsupported()
+ }
+ return out
+}
+
+// toolCall lifts a functionCall part into the neutral tool call, minting an
+// id when the vendor sent none and keeping the thought signature as
+// provider metadata so it can be replayed verbatim.
+func (c *Client) toolCall(p rawPart) types.LLMToolCall {
+ fc := p.FunctionCall
+ id := fc.ID
+ if id == "" {
+ id = newCallID()
+ }
+ args := "{}"
+ if len(fc.Args) > 0 && string(fc.Args) != "null" {
+ args = string(fc.Args)
+ }
+ call := types.LLMToolCall{
+ ID: id,
+ Type: "function",
+ Function: types.FunctionCall{Name: fc.Name, Arguments: args},
+ }
+ if p.ThoughtSignature != "" {
+ sig, _ := json.Marshal(p.ThoughtSignature)
+ call.ProviderMetadata = types.ToolCallMetadata{metadataThoughtSignature: sig}
+ }
+ return call
+}
+
+func newCallID() string {
+ var b [6]byte
+ if _, err := rand.Read(b[:]); err != nil {
+ return "call_000000000000"
+ }
+ return "call_" + hex.EncodeToString(b[:])
+}
+
+// mapFinishReason maps Gemini finish reasons onto the OpenAI vocabulary the
+// rest of the system understands.
+func mapFinishReason(reason string, hasToolCalls bool) string {
+ switch reason {
+ case "":
+ return ""
+ case "STOP":
+ if hasToolCalls {
+ return "tool_calls"
+ }
+ return "stop"
+ case "MAX_TOKENS":
+ return "length"
+ case "SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT":
+ return "content_filter"
+ default:
+ return strings.ToLower(reason)
+ }
+}
+
+func (c *Client) parseResponse(raw []byte) (*types.ChatResponse, error) {
+ var env rawResponse
+ if err := json.Unmarshal(raw, &env); err != nil {
+ return nil, fmt.Errorf("decode response: %w", err)
+ }
+ if env.Error != nil && env.Error.Message != "" {
+ return nil, fmt.Errorf("API error: %s", env.Error.Message)
+ }
+ if len(env.Candidates) == 0 {
+ if env.PromptFeedback != nil && env.PromptFeedback.BlockReason != "" {
+ return nil, fmt.Errorf("blocked: %s", env.PromptFeedback.BlockReason)
+ }
+ return nil, fmt.Errorf("no response from API")
+ }
+ cand := env.Candidates[0]
+ result := &types.ChatResponse{}
+ var content, reasoning strings.Builder
+ for _, p := range cand.Content.Parts {
+ if p.ThoughtSignature != "" {
+ result.ReasoningSignature = api.TagSignature(api.APIGoogleGenerativeAI, p.ThoughtSignature)
+ }
+ switch {
+ case p.FunctionCall != nil:
+ result.ToolCalls = append(result.ToolCalls, c.toolCall(p))
+ case p.Thought:
+ reasoning.WriteString(p.Text)
+ default:
+ content.WriteString(p.Text)
+ }
+ }
+ result.Content = content.String()
+ result.ReasoningContent = reasoning.String()
+ result.FinishReason = mapFinishReason(cand.FinishReason, len(result.ToolCalls) > 0)
+ // Classify the cache status even without usageMetadata: an empty
+ // CacheStatus is indistinguishable from a miss downstream.
+ usage := rawUsage{}
+ if env.UsageMetadata != nil {
+ usage = *env.UsageMetadata
+ }
+ result.Usage = c.usage(usage)
+ return result, nil
+}
+
+// processStream decodes the alt=sse stream: every data line carries a full
+// GenerateContentResponse chunk. Function calls arrive complete in one part;
+// they are fed to the assembler as a name delta followed by an arguments
+// delta so the early ResponseTypeToolCall notification fires as it does for
+// the fragment-based protocols.
+func (c *Client) processStream(
+ ctx context.Context, body io.Reader, ch chan<- types.StreamResponse, dumper *api.StreamPacketDumper,
+) {
+ assembler := api.NewStreamAssembler(ctx, c.cfg.Endpoint.Model)
+ reader := api.NewSSEReader(body)
+ toolIndex := 0
+
+ for {
+ // The consumer went away (client disconnect, aborted agent turn): stop
+ // decoding a stream nobody will read instead of spinning to EOF.
+ if assembler.Aborted() {
+ return
+ }
+ event, err := reader.ReadEvent()
+ if err != nil {
+ if err == io.EOF {
+ assembler.End(ch)
+ } else {
+ assembler.Fail(ch, err)
+ }
+ return
+ }
+ if event == nil {
+ continue
+ }
+ if event.Done {
+ assembler.End(ch)
+ return
+ }
+ if len(event.Data) == 0 {
+ continue
+ }
+ if dumper != nil {
+ raw := make([]byte, len(event.Data))
+ copy(raw, event.Data)
+ dumper.WritePacketRaw(raw)
+ }
+
+ var env rawResponse
+ if err := json.Unmarshal(event.Data, &env); err != nil {
+ assembler.Fail(ch, fmt.Errorf("decode stream chunk: %w", err))
+ return
+ }
+ if env.Error != nil && env.Error.Message != "" {
+ assembler.Fail(ch, fmt.Errorf("API stream error: %s", env.Error.Message))
+ return
+ }
+ if env.UsageMetadata != nil {
+ assembler.SetUsage(c.usage(*env.UsageMetadata))
+ }
+ if len(env.Candidates) == 0 {
+ if env.PromptFeedback != nil && env.PromptFeedback.BlockReason != "" {
+ assembler.Fail(ch, fmt.Errorf("blocked: %s", env.PromptFeedback.BlockReason))
+ return
+ }
+ continue
+ }
+
+ cand := env.Candidates[0]
+ var delta api.Delta
+ var calls []rawPart
+ for _, p := range cand.Content.Parts {
+ if p.ThoughtSignature != "" {
+ assembler.ReasoningSignature = api.TagSignature(api.APIGoogleGenerativeAI, p.ThoughtSignature)
+ }
+ switch {
+ case p.FunctionCall != nil:
+ calls = append(calls, p)
+ case p.Thought:
+ delta.Reasoning += p.Text
+ default:
+ delta.Content += p.Text
+ }
+ }
+ if delta.Reasoning != "" || delta.Content != "" {
+ assembler.Process(ch, delta)
+ }
+ for _, p := range calls {
+ call := c.toolCall(p)
+ idx := toolIndex
+ toolIndex++
+ assembler.Process(ch, api.Delta{ToolCalls: []api.ToolCallDelta{{
+ Index: idx, ID: call.ID, Type: call.Type, Name: call.Function.Name,
+ }}})
+ if len(call.ProviderMetadata) > 0 {
+ assembler.SetToolCallMetadata(idx, call.ProviderMetadata)
+ }
+ assembler.Process(ch, api.Delta{ToolCalls: []api.ToolCallDelta{{
+ Index: idx, Arguments: call.Function.Arguments,
+ }}})
+ }
+ if cand.FinishReason != "" {
+ assembler.Process(ch, api.Delta{FinishReason: mapFinishReason(cand.FinishReason, toolIndex > 0)})
+ }
+ }
+}
diff --git a/internal/models/api/googlegenai/googlegenai_test.go b/internal/models/api/googlegenai/googlegenai_test.go
new file mode 100644
index 000000000..bf0abbf64
--- /dev/null
+++ b/internal/models/api/googlegenai/googlegenai_test.go
@@ -0,0 +1,700 @@
+package googlegenai
+
+import (
+ "context"
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "reflect"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+func newTestClient(t *testing.T, baseURL string, mutate func(*Config)) *Client {
+ t.Helper()
+ cfg := Config{
+ Endpoint: api.Endpoint{
+ BaseURL: baseURL,
+ Model: "gemini-2.5-pro",
+ ModelID: "model-123",
+ Auth: api.HeaderAuth("x-goog-api-key", "test-key"),
+ },
+ Settings: catalog.DefaultGoogleGenerativeAI(),
+ Reasoning: true,
+ }
+ if mutate != nil {
+ mutate(&cfg)
+ }
+ return New(cfg)
+}
+
+// normalize round-trips a body through JSON so typed slices and ints compare
+// equal to a parsed expectation.
+func normalize(t *testing.T, v any) any {
+ t.Helper()
+ data, err := json.Marshal(v)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ var out any
+ if err := json.Unmarshal(data, &out); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ return out
+}
+
+func parseJSON(t *testing.T, s string) any {
+ t.Helper()
+ var out any
+ if err := json.Unmarshal([]byte(s), &out); err != nil {
+ t.Fatalf("parse expected json: %v", err)
+ }
+ return out
+}
+
+func goldenMessages() []api.Message {
+ return []api.Message{
+ {Role: "system", Content: "You are helpful."},
+ {Role: "user", MultiContent: []api.MessageContentPart{
+ {Type: "image_url", ImageURL: &api.ImageURL{URL: "data:image/png;base64,AAAA"}},
+ {Type: "text", Text: "What is this?"},
+ }},
+ {Role: "assistant", ReasoningContent: "never replayed", ToolCalls: []api.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Function: api.FunctionCall{
+ Name: "get_weather",
+ Arguments: `{"city":"Paris"}`,
+ },
+ ProviderMetadata: types.ToolCallMetadata{"thought_signature": json.RawMessage(`"sig-1"`)},
+ },
+ {ID: "call_2", Type: "function", Function: api.FunctionCall{Name: "get_time", Arguments: ""}},
+ }},
+ {Role: "tool", ToolCallID: "call_1", Content: `{"temp": 20}`},
+ {Role: "tool", ToolCallID: "call_2", Name: "get_time", Content: "noon"},
+ }
+}
+
+func goldenOptions() *api.Options {
+ return &api.Options{
+ Temperature: 0.7,
+ MaxTokens: 1024,
+ ReasoningEffort: api.ReasoningHigh,
+ ToolChoice: "auto",
+ Tools: []api.Tool{
+ {Type: "function", Function: api.FunctionDef{
+ Name: "get_weather",
+ Description: "Weather",
+ Parameters: json.RawMessage(`{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "type": "object",
+ "title": "Weather",
+ "additionalProperties": false,
+ "properties": {
+ "city": {"type": "string", "default": "Paris", "examples": ["Paris"]},
+ "title": {"type": "string", "description": "a property named title"}
+ },
+ "required": ["city"]
+ }`),
+ }},
+ {Type: "function", Function: api.FunctionDef{Name: "get_time", Description: "Time"}},
+ },
+ }
+}
+
+const goldenBase = `{
+ "systemInstruction": {"parts": [{"text": "You are helpful."}]},
+ "contents": [
+ {"role": "user", "parts": [
+ {"inlineData": {"mimeType": "image/png", "data": "AAAA"}},
+ {"text": "What is this?"}
+ ]},
+ {"role": "model", "parts": [
+ {"functionCall": {"id": "call_1", "name": "get_weather", "args": {"city": "Paris"}}, "thoughtSignature": "sig-1"},
+ {"functionCall": {"id": "call_2", "name": "get_time", "args": {}}}
+ ]},
+ {"role": "user", "parts": [
+ {"functionResponse": {"id": "call_1", "name": "get_weather", "response": {"result": {"temp": 20}}}},
+ {"functionResponse": {"id": "call_2", "name": "get_time", "response": {"result": "noon"}}}
+ ]}
+ ],
+ "tools": [{"functionDeclarations": [
+ {"name": "get_weather", "description": "Weather", "parameters": {
+ "type": "object",
+ "properties": {
+ "city": {"type": "string"},
+ "title": {"type": "string", "description": "a property named title"}
+ },
+ "required": ["city"]
+ }},
+ {"name": "get_time", "description": "Time"}
+ ]}],
+ "toolConfig": {"functionCallingConfig": {"mode": "AUTO"}},
+ "generationConfig": {
+ "temperature": 0.7,
+ "maxOutputTokens": 1024,
+ "thinkingConfig": THINKING
+ }
+}`
+
+// TestThinkingConfigOmittedForNonReasoningModels guards models the catalog
+// does not mark as reasoning (gemini-2.0-flash, Gemma): they may reject any
+// thinkingConfig, including the thinkingBudget 0 an agent's default "off" maps to.
+func TestThinkingConfigOmittedForNonReasoningModels(t *testing.T) {
+ client := newTestClient(t, "https://generativelanguage.googleapis.com",
+ func(c *Config) { c.Reasoning = false })
+ off := false
+ body, err := client.BuildRequestBody(
+ []api.Message{{Role: "user", Content: "hi"}}, &api.Options{Thinking: &off}, false)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if gc, ok := body["generationConfig"].(map[string]any); ok {
+ if _, has := gc["thinkingConfig"]; has {
+ t.Fatalf("thinkingConfig sent for a non-reasoning model: %v", gc)
+ }
+ }
+}
+
+// TestForeignSignatureNotReplayed guards cross-provider replay: a signature
+// issued by another protocol must never reach Gemini as thoughtSignature.
+func TestForeignSignatureNotReplayed(t *testing.T) {
+ client := newTestClient(t, "https://generativelanguage.googleapis.com", nil)
+ body, err := client.BuildRequestBody([]api.Message{
+ {Role: "user", Content: "hi"},
+ {
+ Role: "assistant", Content: "ok",
+ ReasoningSignature: api.TagSignature(api.APIAnthropicMessages, "claude-sig"),
+ },
+ {Role: "user", Content: "again"},
+ }, nil, false)
+ if err != nil {
+ t.Fatal(err)
+ }
+ data, _ := json.Marshal(body)
+ if strings.Contains(string(data), "claude-sig") {
+ t.Fatalf("foreign signature replayed: %s", data)
+ }
+}
+
+func TestBuildRequestBodyGolden(t *testing.T) {
+ cases := []struct {
+ name string
+ mutate func(*Config)
+ thinking string
+ }{
+ {
+ name: "budget mode",
+ thinking: `{"thinkingBudget": 24576, "includeThoughts": true}`,
+ },
+ {
+ name: "level mode",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingMode = catalog.GoogleThinkingLevel
+ c.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningHigh: api.StringPtr("high")}
+ },
+ thinking: `{"thinkingLevel": "high", "includeThoughts": true}`,
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ client := newTestClient(t, "https://generativelanguage.googleapis.com", tc.mutate)
+ body, err := client.BuildRequestBody(goldenMessages(), goldenOptions(), false)
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ expected := parseJSON(t, replaceThinking(goldenBase, tc.thinking))
+ got := normalize(t, body)
+ if !reflect.DeepEqual(got, expected) {
+ gotJSON, _ := json.MarshalIndent(got, "", " ")
+ wantJSON, _ := json.MarshalIndent(expected, "", " ")
+ t.Fatalf("body mismatch\n got: %s\nwant: %s", gotJSON, wantJSON)
+ }
+ })
+ }
+}
+
+func replaceThinking(tmpl, thinking string) string {
+ return strings.Replace(tmpl, "THINKING", thinking, 1)
+}
+
+func TestThinkingConfigVariants(t *testing.T) {
+ cases := []struct {
+ name string
+ mutate func(*Config)
+ opts *api.Options
+ want string // "" means no thinkingConfig
+ }{
+ {name: "not requested", opts: &api.Options{}, want: ""},
+ {
+ name: "budget off supported", opts: &api.Options{ReasoningEffort: api.ReasoningOff},
+ want: `{"thinkingBudget": 0}`,
+ },
+ {
+ name: "budget off unsupported",
+ mutate: func(c *Config) { c.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningOff: nil} },
+ opts: &api.Options{ReasoningEffort: api.ReasoningOff},
+ want: "",
+ },
+ {
+ name: "budget auto", opts: &api.Options{ReasoningEffort: api.ReasoningAuto},
+ want: `{"thinkingBudget": -1, "includeThoughts": true}`,
+ },
+ {
+ name: "budget explicit tokens",
+ opts: &api.Options{ReasoningEffort: api.ReasoningLow, ThinkingBudgetTokens: 512},
+ want: `{"thinkingBudget": 512, "includeThoughts": true}`,
+ },
+ {
+ name: "mode none",
+ mutate: func(c *Config) { c.Settings.ThinkingMode = catalog.GoogleThinkingNone },
+ opts: &api.Options{ReasoningEffort: api.ReasoningHigh},
+ want: "",
+ },
+ {
+ name: "level off unmapped",
+ mutate: func(c *Config) { c.Settings.ThinkingMode = catalog.GoogleThinkingLevel },
+ opts: &api.Options{ReasoningEffort: api.ReasoningOff},
+ want: "",
+ },
+ {
+ name: "level auto",
+ mutate: func(c *Config) { c.Settings.ThinkingMode = catalog.GoogleThinkingLevel },
+ opts: &api.Options{ReasoningEffort: api.ReasoningAuto},
+ want: `{"includeThoughts": true}`,
+ },
+ {
+ name: "level clamps unsupported rung",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingMode = catalog.GoogleThinkingLevel
+ c.ThinkingLevels = api.ThinkingLevelMap{
+ api.ReasoningMedium: nil,
+ api.ReasoningHigh: api.StringPtr("high"),
+ }
+ },
+ opts: &api.Options{ReasoningEffort: api.ReasoningMedium},
+ want: `{"thinkingLevel": "high", "includeThoughts": true}`,
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ client := newTestClient(t, "https://generativelanguage.googleapis.com", tc.mutate)
+ body, err := client.BuildRequestBody([]api.Message{{Role: "user", Content: "hi"}}, tc.opts, false)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var got any
+ if gen, ok := body["generationConfig"].(map[string]any); ok {
+ if tcfg, ok := gen["thinkingConfig"]; ok {
+ got = normalize(t, tcfg)
+ }
+ }
+ var want any
+ if tc.want != "" {
+ want = parseJSON(t, tc.want)
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("thinkingConfig = %v, want %v", got, want)
+ }
+ })
+ }
+}
+
+func TestToolChoiceAndFormat(t *testing.T) {
+ client := newTestClient(t, "https://generativelanguage.googleapis.com", nil)
+ opts := &api.Options{
+ ToolChoice: "get_weather",
+ Tools: []api.Tool{{Function: api.FunctionDef{Name: "get_weather"}}},
+ Format: json.RawMessage(`{"type":"object"}`),
+ }
+ body, err := client.BuildRequestBody([]api.Message{{Role: "user", Content: "hi"}}, opts, false)
+ if err != nil {
+ t.Fatal(err)
+ }
+ got := normalize(t, body["toolConfig"])
+ want := parseJSON(t, `{"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": ["get_weather"]}}`)
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("toolConfig = %v, want %v", got, want)
+ }
+ gen := body["generationConfig"].(map[string]any)
+ if gen["responseMimeType"] != "application/json" {
+ t.Fatalf("responseMimeType = %v", gen["responseMimeType"])
+ }
+ contents := body["contents"].([]map[string]any)
+ text := contents[0]["parts"].([]part)[0]["text"].(string)
+ if text != "hi\nUse this JSON schema: {\"type\":\"object\"}" {
+ t.Fatalf("schema hint not appended: %q", text)
+ }
+}
+
+func TestRequestURL(t *testing.T) {
+ cases := []struct {
+ name string
+ base string
+ stream bool
+ want string
+ }{
+ {
+ "bare host non-stream", "https://generativelanguage.googleapis.com", false,
+ "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent",
+ },
+ {
+ "bare host trailing slash stream", "https://generativelanguage.googleapis.com/", true,
+ "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse",
+ },
+ {
+ "versioned base non-stream", "https://proxy.example.com/gemini/v1beta", false,
+ "https://proxy.example.com/gemini/v1beta/models/gemini-2.5-pro:generateContent",
+ },
+ {
+ "versioned base stream", "https://proxy.example.com/v1beta/", true,
+ "https://proxy.example.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse",
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ client := newTestClient(t, tc.base, nil)
+ if got := client.requestURL(tc.stream); got != tc.want {
+ t.Fatalf("requestURL = %q, want %q", got, tc.want)
+ }
+ })
+ }
+
+ t.Run("explicit URL override", func(t *testing.T) {
+ client := newTestClient(t, "https://ignored.example.com", func(c *Config) {
+ c.Endpoint.URL = "https://custom.example.com/route:generateContent"
+ })
+ if got := client.requestURL(false); got != "https://custom.example.com/route:generateContent" {
+ t.Fatalf("requestURL = %q", got)
+ }
+ // A streaming call must name the streaming method: ":generateContent"
+ // answers with one buffered JSON document even with alt=sse, which the
+ // SSE reader would see as an empty stream.
+ want := "https://custom.example.com/route:streamGenerateContent?alt=sse"
+ if got := client.requestURL(true); got != want {
+ t.Fatalf("requestURL = %q, want %q", got, want)
+ }
+ })
+
+ t.Run("explicit URL override without a known method is left alone", func(t *testing.T) {
+ client := newTestClient(t, "https://ignored.example.com", func(c *Config) {
+ c.Endpoint.URL = "https://custom.example.com/route"
+ })
+ if got := client.requestURL(true); got != "https://custom.example.com/route?alt=sse" {
+ t.Fatalf("requestURL = %q", got)
+ }
+ })
+}
+
+func TestChatDecodesResponse(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ var gotPath, gotQuery, gotKey string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ gotQuery = r.URL.RawQuery
+ gotKey = r.Header.Get("x-goog-api-key")
+ raw, _ := io.ReadAll(r.Body)
+ _ = json.Unmarshal(raw, &gotBody)
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{
+ "candidates": [{
+ "content": {"role": "model", "parts": [
+ {"text": "Thinking about Paris.", "thought": true, "thoughtSignature": "sig-thought"},
+ {"text": "Let me check."},
+ {"functionCall": {"id": "fc-1", "name": "get_weather", "args": {"city": "Paris"}},
+ "thoughtSignature": "sig-fc"}
+ ]},
+ "finishReason": "STOP"
+ }],
+ "usageMetadata": {"promptTokenCount": 10, "candidatesTokenCount": 5, "thoughtsTokenCount": 3,
+ "totalTokenCount": 18, "cachedContentTokenCount": 4}
+ }`))
+ }))
+ defer srv.Close()
+
+ client := newTestClient(t, srv.URL, nil)
+ resp, err := client.Chat(context.Background(), []api.Message{{Role: "user", Content: "weather?"}}, &api.Options{})
+ if err != nil {
+ t.Fatalf("Chat: %v", err)
+ }
+ if gotPath != "/v1beta/models/gemini-2.5-pro:generateContent" || gotQuery != "" {
+ t.Fatalf("request path = %q query = %q", gotPath, gotQuery)
+ }
+ if gotKey != "test-key" {
+ t.Fatalf("x-goog-api-key = %q", gotKey)
+ }
+ if _, ok := gotBody["contents"]; !ok {
+ t.Fatalf("request body missing contents: %v", gotBody)
+ }
+ if resp.Content != "Let me check." {
+ t.Fatalf("Content = %q", resp.Content)
+ }
+ if resp.ReasoningContent != "Thinking about Paris." {
+ t.Fatalf("ReasoningContent = %q", resp.ReasoningContent)
+ }
+ if resp.ReasoningSignature != "google-generative-ai:sig-fc" {
+ t.Fatalf("ReasoningSignature = %q", resp.ReasoningSignature)
+ }
+ if resp.FinishReason != "tool_calls" {
+ t.Fatalf("FinishReason = %q", resp.FinishReason)
+ }
+ if len(resp.ToolCalls) != 1 {
+ t.Fatalf("ToolCalls = %+v", resp.ToolCalls)
+ }
+ tc := resp.ToolCalls[0]
+ if tc.ID != "fc-1" || tc.Type != "function" || tc.Function.Name != "get_weather" ||
+ tc.Function.Arguments != `{"city": "Paris"}` {
+ t.Fatalf("tool call = %+v", tc)
+ }
+ if string(tc.ProviderMetadata["thought_signature"]) != `"sig-fc"` {
+ t.Fatalf("thought_signature = %s", tc.ProviderMetadata["thought_signature"])
+ }
+ u := resp.Usage
+ if u.PromptTokens != 10 || u.CompletionTokens != 8 || u.TotalTokens != 18 {
+ t.Fatalf("usage = %+v", u)
+ }
+ if u.CacheReadTokens != 4 || u.CacheMissTokens != 6 || !u.CacheReported ||
+ u.CacheStatus != types.PromptCacheStatusHit {
+ t.Fatalf("cache usage = %+v", u)
+ }
+}
+
+func TestChatErrors(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ cases := []struct {
+ name string
+ body string
+ want string
+ }{
+ {
+ "error payload", `{"error": {"code": 400, "message": "bad request", "status": "INVALID_ARGUMENT"}}`,
+ "API error: bad request",
+ },
+ {"blocked prompt", `{"promptFeedback": {"blockReason": "SAFETY"}}`, "blocked: SAFETY"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ _, _ = w.Write([]byte(tc.body))
+ }))
+ defer srv.Close()
+ client := newTestClient(t, srv.URL, nil)
+ _, err := client.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err == nil || err.Error() != tc.want {
+ t.Fatalf("err = %v, want %q", err, tc.want)
+ }
+ })
+ }
+}
+
+func TestChatStreamDecodesSSE(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ var gotPath, gotQuery string
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ gotQuery = r.URL.RawQuery
+ w.Header().Set("Content-Type", "text/event-stream")
+ chunks := []string{
+ `{"candidates":[{"content":{"role":"model","parts":[{"text":"Let me think.","thought":true}]}}]}`,
+ `{"candidates":[{"content":{"role":"model","parts":[{"text":"Checking "}]}}]}`,
+ `{"candidates":[{"content":{"role":"model","parts":[{"text":"weather."}]}}]}`,
+ `{"candidates":[{"content":{"role":"model","parts":[{"functionCall":{"name":"get_weather",` +
+ `"args":{"city":"Paris"}},"thoughtSignature":"sig-stream"}]},"finishReason":"STOP"}],` +
+ `"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":5,"thoughtsTokenCount":3,` +
+ `"totalTokenCount":18}}`,
+ }
+ for _, c := range chunks {
+ _, _ = w.Write([]byte("data: " + c + "\n\n"))
+ }
+ }))
+ defer srv.Close()
+
+ client := newTestClient(t, srv.URL, nil)
+ ch, err := client.ChatStream(context.Background(),
+ []api.Message{{Role: "user", Content: "weather?"}}, &api.Options{})
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var events []types.StreamResponse
+ for ev := range ch {
+ events = append(events, ev)
+ }
+ if gotPath != "/v1beta/models/gemini-2.5-pro:streamGenerateContent" || gotQuery != "alt=sse" {
+ t.Fatalf("request path = %q query = %q", gotPath, gotQuery)
+ }
+ if len(events) == 0 {
+ t.Fatal("no events")
+ }
+
+ firstThinking, firstAnswer, toolCallEvent := -1, -1, -1
+ var thinking, answer string
+ for i, ev := range events {
+ switch ev.ResponseType {
+ case types.ResponseTypeThinking:
+ if !ev.Done {
+ if firstThinking < 0 {
+ firstThinking = i
+ }
+ thinking += ev.Content
+ }
+ case types.ResponseTypeAnswer:
+ if ev.Content != "" {
+ if firstAnswer < 0 {
+ firstAnswer = i
+ }
+ answer += ev.Content
+ }
+ case types.ResponseTypeToolCall:
+ if toolCallEvent < 0 {
+ toolCallEvent = i
+ }
+ if ev.Data["tool_name"] != "get_weather" || ev.Data["tool_call_id"] == "" {
+ t.Fatalf("tool_call event data = %v", ev.Data)
+ }
+ case types.ResponseTypeError:
+ t.Fatalf("stream error: %s", ev.Content)
+ }
+ }
+ if firstThinking < 0 || firstAnswer < 0 || firstThinking > firstAnswer {
+ t.Fatalf("thinking (%d) must precede answer (%d)", firstThinking, firstAnswer)
+ }
+ if thinking != "Let me think." || answer != "Checking weather." {
+ t.Fatalf("thinking = %q answer = %q", thinking, answer)
+ }
+ if toolCallEvent < 0 {
+ t.Fatal("no ResponseTypeToolCall event")
+ }
+
+ final := events[len(events)-1]
+ if final.ResponseType != types.ResponseTypeAnswer || !final.Done {
+ t.Fatalf("final event = %+v", final)
+ }
+ if final.FinishReason != "tool_calls" {
+ t.Fatalf("final FinishReason = %q", final.FinishReason)
+ }
+ if final.Usage == nil || final.Usage.PromptTokens != 10 || final.Usage.CompletionTokens != 8 ||
+ final.Usage.TotalTokens != 18 {
+ t.Fatalf("final usage = %+v", final.Usage)
+ }
+ if final.Usage.CacheStatus != types.PromptCacheStatusUnreported || final.Usage.CacheReported {
+ t.Fatalf("cache status = %+v", final.Usage)
+ }
+ if len(final.ToolCalls) != 1 {
+ t.Fatalf("final tool calls = %+v", final.ToolCalls)
+ }
+ tc := final.ToolCalls[0]
+ if tc.Function.Name != "get_weather" || tc.Function.Arguments != `{"city":"Paris"}` || tc.Type != "function" {
+ t.Fatalf("tool call = %+v", tc)
+ }
+ if len(tc.ID) != len("call_")+12 || tc.ID[:5] != "call_" {
+ t.Fatalf("generated tool call id = %q", tc.ID)
+ }
+ if string(tc.ProviderMetadata["thought_signature"]) != `"sig-stream"` {
+ t.Fatalf("thought_signature = %s", tc.ProviderMetadata["thought_signature"])
+ }
+ if final.Data["reasoning_signature"] != "google-generative-ai:sig-stream" {
+ t.Fatalf("Data = %v", final.Data)
+ }
+}
+
+func TestChatStreamErrorPayload(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ _, _ = w.Write([]byte("data: {\"error\": {\"code\": 429, \"message\": \"quota exceeded\"}}\n\n"))
+ }))
+ defer srv.Close()
+
+ client := newTestClient(t, srv.URL, nil)
+ ch, err := client.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var last types.StreamResponse
+ for ev := range ch {
+ last = ev
+ }
+ if last.ResponseType != types.ResponseTypeError || last.Content != "API stream error: quota exceeded" {
+ t.Fatalf("last event = %+v", last)
+ }
+}
+
+// "contents" is required and must be an array. A request that produced no
+// turns (only system prompts) used to marshal a nil slice as null, which
+// generateContent rejects with 400.
+func TestBuildRequestBodyContentsNeverNull(t *testing.T) {
+ client := newTestClient(t, "https://generativelanguage.googleapis.com", nil)
+ for _, msgs := range [][]api.Message{nil, {{Role: "system", Content: "be brief"}}} {
+ body, err := client.BuildRequestBody(msgs, nil, false)
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ data, err := json.Marshal(body)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ if strings.Contains(string(data), `"contents":null`) {
+ t.Fatalf("contents marshalled as null: %s", data)
+ }
+ if !strings.Contains(string(data), `"contents":[]`) {
+ t.Fatalf("contents not an empty array: %s", data)
+ }
+ }
+}
+
+// Without usageMetadata the cache status must still be classified, otherwise
+// "the vendor reported nothing" is indistinguishable from a real miss on the
+// usage dashboards.
+func TestChatClassifiesCacheStatusWithoutUsageMetadata(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"candidates":[{"content":{"role":"model","parts":[{"text":"hi"}]},` +
+ `"finishReason":"STOP"}]}`))
+ }))
+ defer srv.Close()
+
+ client := newTestClient(t, srv.URL, nil)
+ resp, err := client.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("Chat: %v", err)
+ }
+ if resp.Usage.CacheStatus == "" {
+ t.Fatal("CacheStatus is empty; the usage block must still be classified")
+ }
+}
+
+// A chunk that blocks the prompt mid-stream must surface as an error rather
+// than being skipped as "no candidates".
+func TestChatStreamSurfacesPromptFeedbackBlock(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte("data: {\"promptFeedback\":{\"blockReason\":\"SAFETY\"}}\n\n"))
+ }))
+ defer srv.Close()
+
+ client := newTestClient(t, srv.URL, nil)
+ ch, err := client.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var sawError bool
+ for chunk := range ch {
+ if chunk.ResponseType == types.ResponseTypeError {
+ sawError = true
+ if !strings.Contains(chunk.Content, "SAFETY") {
+ t.Fatalf("error chunk = %q, want the block reason", chunk.Content)
+ }
+ }
+ }
+ if !sawError {
+ t.Fatal("blocked prompt did not produce an error chunk")
+ }
+}
diff --git a/internal/models/api/googlegenai/request.go b/internal/models/api/googlegenai/request.go
new file mode 100644
index 000000000..7c9b3795a
--- /dev/null
+++ b/internal/models/api/googlegenai/request.go
@@ -0,0 +1,524 @@
+// Package googlegenai implements the native Google Gemini generateContent
+// wire protocol (https://ai.google.dev/api/generate-content). Every
+// model-specific deviation is driven by catalog.GoogleGenerativeAISettings;
+// this package contains no vendor names beyond the protocol itself.
+package googlegenai
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "mime"
+ "net/url"
+ "path"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+)
+
+// Config is everything the client needs, already resolved by the catalog.
+type Config struct {
+ Endpoint api.Endpoint
+ Settings catalog.GoogleGenerativeAISettings
+ // ThinkingLevels maps neutral levels to the vendor vocabulary
+ // (thinkingLevel values for Gemini 3, "off" support for budget models).
+ ThinkingLevels api.ThinkingLevelMap
+ // Reasoning marks a reasoning model. The Gemini protocol has no
+ // role selection to gate on it; the field is informational and mirrors
+ // the other protocol configs.
+ Reasoning bool
+}
+
+const (
+ roleUser = "user"
+ roleModel = "model"
+
+ // metadataThoughtSignature is the ToolCallMetadata key under which a
+ // function call's thoughtSignature round-trips. Gemini 3 rejects a
+ // replayed function call whose signature is missing or altered.
+ metadataThoughtSignature = "thought_signature"
+
+ defaultImageMIME = "image/jpeg"
+)
+
+type part = map[string]any
+
+// convertMessages splits neutral messages into the system instruction text
+// and the Gemini contents array. Consecutive tool results are merged into one
+// user content carrying several functionResponse parts, as Gemini requires
+// every functionCall of a model turn to be answered in the next content.
+func (c *Client) convertMessages(messages []api.Message) (system []string, contents []map[string]any) {
+ toolNames := map[string]string{}
+ openToolBatch := -1 // index in contents of the functionResponse content being filled
+ for _, msg := range messages {
+ msg = api.NeutralizeMessageSpecialTokens(msg)
+ switch msg.Role {
+ case "system":
+ if text := systemText(msg); text != "" {
+ system = append(system, text)
+ }
+ case "assistant":
+ for _, tc := range msg.ToolCalls {
+ if tc.ID != "" {
+ toolNames[tc.ID] = tc.Function.Name
+ }
+ }
+ contents = append(contents, map[string]any{"role": roleModel, "parts": assistantParts(msg)})
+ case "tool":
+ p := toolResultPart(msg, toolNames)
+ if openToolBatch >= 0 && openToolBatch == len(contents)-1 {
+ batch := contents[openToolBatch]
+ batch["parts"] = append(batch["parts"].([]part), p)
+ continue
+ }
+ contents = append(contents, map[string]any{"role": roleUser, "parts": []part{p}})
+ openToolBatch = len(contents) - 1
+ default:
+ contents = append(contents, map[string]any{"role": roleUser, "parts": userParts(msg)})
+ }
+ }
+ return system, contents
+}
+
+func systemText(msg api.Message) string {
+ if len(msg.MultiContent) == 0 {
+ return msg.Content
+ }
+ var texts []string
+ for _, p := range msg.MultiContent {
+ if p.Type == "text" && p.Text != "" {
+ texts = append(texts, p.Text)
+ }
+ }
+ return strings.Join(texts, "\n")
+}
+
+// userParts renders a user turn. Legacy Message.Images are emitted before the
+// text part, matching the Chat Completions package.
+func userParts(msg api.Message) []part {
+ var parts []part
+ switch {
+ case len(msg.MultiContent) > 0:
+ for _, p := range msg.MultiContent {
+ switch p.Type {
+ case "text":
+ if p.Text != "" {
+ parts = append(parts, part{"text": p.Text})
+ }
+ case "image_url":
+ if p.ImageURL != nil {
+ if ip := imagePart(p.ImageURL.URL); ip != nil {
+ parts = append(parts, ip)
+ }
+ }
+ }
+ }
+ case len(msg.Images) > 0:
+ for _, img := range msg.Images {
+ if ip := imagePart(img); ip != nil {
+ parts = append(parts, ip)
+ }
+ }
+ parts = append(parts, part{"text": msg.Content})
+ }
+ if len(parts) == 0 {
+ parts = append(parts, part{"text": msg.Content})
+ }
+ return parts
+}
+
+// assistantParts renders a model turn: the answer text (carrying the thought
+// signature when the turn had no function calls) followed by one functionCall
+// part per tool call, each replaying its own thought signature. Reasoning
+// text is never replayed as a thought part: Gemini only needs signatures.
+func assistantParts(msg api.Message) []part {
+ var parts []part
+ if msg.Content != "" || len(msg.ToolCalls) == 0 {
+ p := part{"text": msg.Content}
+ sig := api.SignatureFor(api.APIGoogleGenerativeAI, msg.ReasoningSignature)
+ if sig != "" && len(msg.ToolCalls) == 0 {
+ p["thoughtSignature"] = sig
+ }
+ parts = append(parts, p)
+ }
+ for _, tc := range msg.ToolCalls {
+ fc := map[string]any{
+ "name": tc.Function.Name,
+ "args": parseArgs(tc.Function.Arguments),
+ }
+ if tc.ID != "" {
+ fc["id"] = tc.ID
+ }
+ p := part{"functionCall": fc}
+ if sig := thoughtSignatureFromMetadata(tc.ProviderMetadata); sig != "" {
+ p["thoughtSignature"] = sig
+ }
+ parts = append(parts, p)
+ }
+ return parts
+}
+
+// toolResultPart renders a tool result as a functionResponse part. The tool
+// name comes from the message or, failing that, from the assistant turn that
+// issued the call.
+func toolResultPart(msg api.Message, toolNames map[string]string) part {
+ name := msg.Name
+ if name == "" {
+ name = toolNames[msg.ToolCallID]
+ }
+ fr := map[string]any{
+ "name": name,
+ "response": map[string]any{"result": decodeToolResult(msg.Content)},
+ }
+ if msg.ToolCallID != "" {
+ fr["id"] = msg.ToolCallID
+ }
+ return part{"functionResponse": fr}
+}
+
+// decodeToolResult returns the tool output as a JSON value when it is a JSON
+// object or array, otherwise the raw string.
+func decodeToolResult(content string) any {
+ trimmed := strings.TrimSpace(content)
+ if strings.HasPrefix(trimmed, "{") || strings.HasPrefix(trimmed, "[") {
+ var v any
+ if err := json.Unmarshal([]byte(trimmed), &v); err == nil {
+ return v
+ }
+ }
+ return content
+}
+
+// parseArgs decodes a tool call's JSON arguments into the object Gemini
+// expects; anything that is not a JSON object becomes an empty object.
+func parseArgs(arguments string) map[string]any {
+ args := map[string]any{}
+ if strings.TrimSpace(arguments) == "" {
+ return args
+ }
+ if err := json.Unmarshal([]byte(arguments), &args); err != nil || args == nil {
+ return map[string]any{}
+ }
+ return args
+}
+
+func thoughtSignatureFromMetadata(md map[string]json.RawMessage) string {
+ raw, ok := md[metadataThoughtSignature]
+ if !ok || len(raw) == 0 {
+ return ""
+ }
+ var sig string
+ if err := json.Unmarshal(raw, &sig); err != nil {
+ return ""
+ }
+ return sig
+}
+
+// imagePart renders an image reference. Stored images are resolved to data
+// URIs first; data URIs become inlineData, everything else is passed as
+// fileData with a MIME type guessed from the extension.
+func imagePart(ref string) part {
+ resolved := api.ResolveImageURLForLLM(ref)
+ if strings.HasPrefix(resolved, "data:") {
+ mimeType, data, ok := parseDataURI(resolved)
+ if !ok {
+ return nil
+ }
+ return part{"inlineData": map[string]any{"mimeType": mimeType, "data": data}}
+ }
+ return part{"fileData": map[string]any{"mimeType": guessImageMIME(resolved), "fileUri": resolved}}
+}
+
+// parseDataURI splits "data:<mime>[;base64],<payload>" into the MIME type and
+// the base64 payload Gemini wants. Non-base64 payloads are re-encoded.
+func parseDataURI(uri string) (mimeType, data string, ok bool) {
+ comma := strings.Index(uri, ",")
+ if comma < 0 {
+ return "", "", false
+ }
+ header := uri[len("data:"):comma]
+ payload := uri[comma+1:]
+ isBase64 := false
+ if strings.HasSuffix(header, ";base64") {
+ header = strings.TrimSuffix(header, ";base64")
+ isBase64 = true
+ }
+ mimeType = header
+ if idx := strings.Index(mimeType, ";"); idx >= 0 {
+ mimeType = mimeType[:idx]
+ }
+ if mimeType == "" {
+ mimeType = defaultImageMIME
+ }
+ if isBase64 {
+ return mimeType, payload, true
+ }
+ decoded, err := url.PathUnescape(payload)
+ if err != nil {
+ decoded = payload
+ }
+ return mimeType, base64.StdEncoding.EncodeToString([]byte(decoded)), true
+}
+
+func guessImageMIME(ref string) string {
+ ext := path.Ext(ref)
+ if u, err := url.Parse(ref); err == nil && u.Path != "" {
+ ext = path.Ext(u.Path)
+ }
+ if ext != "" {
+ if mt := mime.TypeByExtension(strings.ToLower(ext)); strings.HasPrefix(mt, "image/") {
+ return mt
+ }
+ }
+ return defaultImageMIME
+}
+
+// buildBody assembles the generateContent request body. The body is the
+// same for streaming and non-streaming calls; streaming is selected by the
+// URL. It returns nested maps so golden tests can inspect it.
+func (c *Client) buildBody(messages []api.Message, opts *api.Options) (map[string]any, error) {
+ s := c.cfg.Settings
+ system, contents := c.convertMessages(messages)
+ if contents == nil {
+ // "contents" is required and must be an array: a nil slice marshals to
+ // null and generateContent answers 400. A request carrying only system
+ // messages legitimately produces no turns.
+ contents = []map[string]any{}
+ }
+ body := map[string]any{"contents": contents}
+ if len(system) > 0 {
+ body["systemInstruction"] = map[string]any{
+ "parts": []part{{"text": strings.Join(system, "\n\n")}},
+ }
+ }
+
+ gen := map[string]any{}
+ if opts != nil {
+ c.applySampling(gen, opts)
+ if budget := opts.CompletionBudget(); budget > 0 {
+ gen["maxOutputTokens"] = budget
+ }
+ c.applyTools(body, opts)
+ if len(opts.Format) > 0 {
+ gen["responseMimeType"] = "application/json"
+ appendSchemaHint(contents, opts.Format)
+ }
+ if tc := c.thinkingConfig(opts); tc != nil {
+ gen["thinkingConfig"] = tc
+ }
+ }
+ for k, v := range s.ExtraGeneration {
+ if _, exists := gen[k]; !exists {
+ gen[k] = v
+ }
+ }
+ if len(gen) > 0 {
+ body["generationConfig"] = gen
+ }
+ return body, nil
+}
+
+func (c *Client) applySampling(gen map[string]any, opts *api.Options) {
+ s := c.cfg.Settings
+ if opts.Temperature > 0 {
+ gen["temperature"] = opts.Temperature
+ }
+ if opts.TopP > 0 {
+ gen["topP"] = opts.TopP
+ }
+ if opts.Seed > 0 && s.SupportsSeed {
+ gen["seed"] = opts.Seed
+ }
+ if s.SupportsPenalty {
+ if opts.FrequencyPenalty > 0 {
+ gen["frequencyPenalty"] = opts.FrequencyPenalty
+ }
+ if opts.PresencePenalty > 0 {
+ gen["presencePenalty"] = opts.PresencePenalty
+ }
+ }
+}
+
+func (c *Client) applyTools(body map[string]any, opts *api.Options) {
+ if len(opts.Tools) == 0 {
+ return
+ }
+ decls := make([]map[string]any, 0, len(opts.Tools))
+ for _, tool := range opts.Tools {
+ decl := map[string]any{
+ "name": tool.Function.Name,
+ "description": tool.Function.Description,
+ }
+ if schema := sanitizeParameters(tool.Function.Parameters); schema != nil {
+ decl["parameters"] = schema
+ }
+ decls = append(decls, decl)
+ }
+ body["tools"] = []map[string]any{{"functionDeclarations": decls}}
+
+ if opts.ToolChoice == "" {
+ return
+ }
+ cfg := map[string]any{}
+ switch opts.ToolChoice {
+ case "auto":
+ cfg["mode"] = "AUTO"
+ case "required":
+ cfg["mode"] = "ANY"
+ case "none":
+ cfg["mode"] = "NONE"
+ default:
+ cfg["mode"] = "ANY"
+ cfg["allowedFunctionNames"] = []string{opts.ToolChoice}
+ }
+ body["toolConfig"] = map[string]any{"functionCallingConfig": cfg}
+}
+
+// unsupportedSchemaKeys are JSON Schema members the Gemini Schema type
+// rejects. They are stripped recursively; property names are never touched.
+var unsupportedSchemaKeys = map[string]bool{
+ "$schema": true,
+ "$id": true,
+ "$ref": true,
+ "$defs": true,
+ "definitions": true,
+ "additionalProperties": true,
+ "default": true,
+ "examples": true,
+ "title": true,
+}
+
+// sanitizeParameters decodes a tool's JSON schema and strips the members
+// Gemini does not accept. Empty or undecodable schemas yield nil.
+func sanitizeParameters(raw json.RawMessage) any {
+ if len(raw) == 0 || string(raw) == "null" {
+ return nil
+ }
+ var schema any
+ if err := json.Unmarshal(raw, &schema); err != nil {
+ return nil
+ }
+ if _, ok := schema.(map[string]any); !ok {
+ return nil
+ }
+ return sanitizeSchema(schema)
+}
+
+func sanitizeSchema(v any) any {
+ switch t := v.(type) {
+ case map[string]any:
+ out := make(map[string]any, len(t))
+ for k, val := range t {
+ if unsupportedSchemaKeys[k] {
+ continue
+ }
+ if k == "properties" {
+ if props, ok := val.(map[string]any); ok {
+ cleaned := make(map[string]any, len(props))
+ for name, sub := range props {
+ cleaned[name] = sanitizeSchema(sub)
+ }
+ out[k] = cleaned
+ continue
+ }
+ }
+ out[k] = sanitizeSchema(val)
+ }
+ return out
+ case []any:
+ for i := range t {
+ t[i] = sanitizeSchema(t[i])
+ }
+ return t
+ }
+ return v
+}
+
+// appendSchemaHint appends the JSON schema instruction to the last user text
+// part, mirroring the Chat Completions package.
+func appendSchemaHint(contents []map[string]any, format json.RawMessage) {
+ hint := fmt.Sprintf("\nUse this JSON schema: %s", format)
+ for i := len(contents) - 1; i >= 0; i-- {
+ if contents[i]["role"] != roleUser {
+ continue
+ }
+ parts, _ := contents[i]["parts"].([]part)
+ for j := len(parts) - 1; j >= 0; j-- {
+ if text, ok := parts[j]["text"].(string); ok {
+ parts[j]["text"] = text + hint
+ return
+ }
+ }
+ contents[i]["parts"] = append(parts, part{"text": strings.TrimPrefix(hint, "\n")})
+ return
+ }
+}
+
+// thinkingConfig encodes the requested reasoning level in the shape the
+// model generation supports: thinkingBudget (Gemini 2.5) or thinkingLevel
+// (Gemini 3). nil means "send no thinkingConfig".
+func (c *Client) thinkingConfig(opts *api.Options) map[string]any {
+ s := c.cfg.Settings
+ levels := c.cfg.ThinkingLevels
+ level, requested := opts.Reasoning()
+ // Models the catalog does not mark as reasoning (gemini-2.0-flash, Gemma,
+ // unknown ids) may reject thinkingConfig outright, so send none.
+ if !requested || !c.cfg.Reasoning {
+ return nil
+ }
+ mode := s.ThinkingMode
+ if mode == "" {
+ mode = catalog.GoogleThinkingBudget
+ }
+ switch mode {
+ case catalog.GoogleThinkingBudget:
+ switch level {
+ case api.ReasoningOff:
+ if levels.Supports(api.ReasoningOff) {
+ return map[string]any{"thinkingBudget": 0}
+ }
+ return nil
+ case api.ReasoningAuto:
+ return map[string]any{"thinkingBudget": -1, "includeThoughts": s.IncludeThoughts}
+ default:
+ level = levels.Clamp(level)
+ budget := opts.ThinkingBudgetTokens
+ if budget <= 0 {
+ if b, ok := s.ThinkingBudgets[level]; ok && level.Graded() {
+ budget = b
+ } else {
+ budget = -1
+ }
+ }
+ return map[string]any{"thinkingBudget": budget, "includeThoughts": s.IncludeThoughts}
+ }
+ case catalog.GoogleThinkingLevel:
+ switch level {
+ case api.ReasoningOff:
+ // Gemini 3 cannot switch thinking off; only send a level when the
+ // vendor explicitly mapped "off" to a wire value.
+ if v, ok := levels[api.ReasoningOff]; ok && v != nil && *v != "" {
+ return map[string]any{"thinkingLevel": *v}
+ }
+ return nil
+ case api.ReasoningAuto:
+ return map[string]any{"includeThoughts": s.IncludeThoughts}
+ default:
+ level = levels.Clamp(level)
+ if !level.Graded() {
+ return map[string]any{"includeThoughts": s.IncludeThoughts}
+ }
+ return map[string]any{"thinkingLevel": levels.Value(level), "includeThoughts": s.IncludeThoughts}
+ }
+ }
+ return nil
+}
+
+// BuildRequestBody is the golden-test entry point: it returns the exact
+// JSON object that would be sent for the given inputs. The stream flag is
+// accepted for interface parity; Gemini selects streaming through the URL.
+func (c *Client) BuildRequestBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error) {
+ _ = stream
+ return c.buildBody(messages, opts)
+}
diff --git a/internal/models/api/images.go b/internal/models/api/images.go
new file mode 100644
index 000000000..93f9f5b9d
--- /dev/null
+++ b/internal/models/api/images.go
@@ -0,0 +1,157 @@
+package api
+
+import (
+ "encoding/base64"
+ "errors"
+ "fmt"
+ "log"
+ "net/http"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+// ResolveImageURLForLLM converts stored image paths to a format that LLM APIs can consume.
+// - data: URIs and http(s):// URLs are returned as-is.
+// - resource:// and provider-backed local paths are read through the
+// application resolver and converted to base64 data URIs.
+func ResolveImageURLForLLM(imageURL string) string {
+ if strings.HasPrefix(imageURL, "data:") ||
+ strings.HasPrefix(imageURL, "http://") ||
+ strings.HasPrefix(imageURL, "https://") {
+ return imageURL
+ }
+ if isApplicationStoredImage(imageURL) {
+ data := readLocalStorageBytes(imageURL)
+ if data != nil {
+ mime := http.DetectContentType(data)
+ return fmt.Sprintf("data:%s;base64,%s", mime, base64.StdEncoding.EncodeToString(data))
+ }
+ }
+ return imageURL
+}
+
+// ResolveImageURLForOllama converts stored image paths to raw bytes for the Ollama API.
+func ResolveImageURLForOllama(imageURL string) []byte {
+ if strings.HasPrefix(imageURL, "data:") {
+ idx := strings.Index(imageURL, ";base64,")
+ if idx < 0 {
+ return nil
+ }
+ decoded, err := base64.StdEncoding.DecodeString(imageURL[idx+8:])
+ if err != nil {
+ return nil
+ }
+ return decoded
+ }
+ if isApplicationStoredImage(imageURL) {
+ return readLocalStorageBytes(imageURL)
+ }
+ return nil
+}
+
+func isApplicationStoredImage(imageURL string) bool {
+ return strings.HasPrefix(imageURL, "resource://") ||
+ strings.HasPrefix(imageURL, "local://") ||
+ strings.HasPrefix(imageURL, "storage://")
+}
+
+// LocalImageResolver resolves a resource:// or provider storage URL to bytes
+// using the owning tenant's storage config. The application layer sets it at
+// startup.
+// Stored local:// URLs are relative to the storage base dir and do NOT encode
+// the tenant's configured PathPrefix, so a plain env-based join would miss the
+// prefix. When nil (e.g. in tests), callers fall back to the env-based
+// LOCAL_STORAGE_BASE_DIR resolution below.
+var LocalImageResolver func(storageURL string) ([]byte, bool)
+
+// readLocalStorageBytes resolves a local:// storage path to disk bytes.
+func readLocalStorageBytes(storagePath string) []byte {
+ if LocalImageResolver != nil {
+ if data, ok := LocalImageResolver(storagePath); ok {
+ return data
+ }
+ }
+ relPath := strings.TrimPrefix(storagePath, "local://")
+ baseDir := os.Getenv("LOCAL_STORAGE_BASE_DIR")
+ if baseDir == "" {
+ baseDir = "/data/files"
+ }
+ localPath := filepath.Join(baseDir, filepath.FromSlash(relPath))
+ data, err := os.ReadFile(localPath)
+ if err != nil {
+ log.Printf("[image-resolve] failed to read local file %s: %v", localPath, err)
+ return nil
+ }
+ return data
+}
+
+// IsMultimodalNotSupportedError checks if an error indicates the model does not
+// support multimodal/image input.
+//
+// The status is read off the error, never matched as text: HTTPError.Error()
+// prints "status 400" for every 400, and vendor bodies carry "400" inside
+// unrelated numbers ("max 4000 px"), so a substring test turned any failure
+// that merely mentions an image into a "model is not multimodal" verdict and
+// silently retried it stripped.
+func IsMultimodalNotSupportedError(err error) bool {
+ if err == nil {
+ return false
+ }
+ msg := strings.ToLower(err.Error())
+ mentionsImages := strings.Contains(msg, "multimodal") ||
+ strings.Contains(msg, "image") ||
+ strings.Contains(msg, "vision")
+ if !mentionsImages {
+ return false
+ }
+ if strings.Contains(msg, "not support") || strings.Contains(msg, "unsupported") {
+ return true
+ }
+ // No explicit wording: only a genuine 400 (the status vendors use to reject
+ // an input their model cannot read) is worth a stripped retry.
+ var httpErr *HTTPError
+ return errors.As(err, &httpErr) && httpErr.StatusCode == http.StatusBadRequest
+}
+
+// StripImagesFromMessages returns a copy of messages with all image data removed.
+//
+// Images travel in two shapes: the Images list (chat history, Ollama) and
+// image_url parts inside MultiContent, which is what the remote VLM path and
+// every assembled multimodal turn actually send. Clearing only the first left
+// the retry sending the identical request, so the "retry without images"
+// fallback never recovered anything on those paths.
+func StripImagesFromMessages(messages []Message) []Message {
+ cleaned := make([]Message, len(messages))
+ for i, msg := range messages {
+ cleaned[i] = msg
+ cleaned[i].Images = nil
+ cleaned[i].MultiContent = stripImageParts(msg.MultiContent)
+ }
+ return cleaned
+}
+
+// stripImageParts drops image parts from one MultiContent list, copying it
+// only when there is something to drop so the caller's slice is never mutated.
+// A list that was nothing but images becomes nil: the protocol packages then
+// fall back to the message's plain Content instead of sending an empty parts
+// array, which some vendors reject.
+func stripImageParts(parts []MessageContentPart) []MessageContentPart {
+ if len(parts) == 0 {
+ return parts
+ }
+ kept := make([]MessageContentPart, 0, len(parts))
+ for _, part := range parts {
+ if part.Type == "image_url" || part.ImageURL != nil {
+ continue
+ }
+ kept = append(kept, part)
+ }
+ if len(kept) == len(parts) {
+ return parts
+ }
+ if len(kept) == 0 {
+ return nil
+ }
+ return kept
+}
diff --git a/internal/models/api/images_test.go b/internal/models/api/images_test.go
new file mode 100644
index 000000000..743346a48
--- /dev/null
+++ b/internal/models/api/images_test.go
@@ -0,0 +1,104 @@
+package api
+
+import (
+ "fmt"
+ "testing"
+)
+
+// The remote VLM path sends its pictures as image_url parts in MultiContent,
+// not in Images, so a strip that only cleared Images re-sent the identical
+// request and the "retry without images" fallback could never succeed.
+func TestStripImagesFromMessages_RemovesMultiContentImageParts(t *testing.T) {
+ messages := []Message{{
+ Role: "user",
+ Images: []string{"data:image/png;base64,AAA"},
+ MultiContent: []MessageContentPart{
+ {Type: "text", Text: "describe this"},
+ {Type: "image_url", ImageURL: &ImageURL{URL: "data:image/png;base64,AAA"}},
+ },
+ }}
+
+ cleaned := StripImagesFromMessages(messages)
+
+ if cleaned[0].Images != nil {
+ t.Errorf("Images = %v, want nil", cleaned[0].Images)
+ }
+ if len(cleaned[0].MultiContent) != 1 || cleaned[0].MultiContent[0].Type != "text" {
+ t.Fatalf("MultiContent = %#v, want the text part only", cleaned[0].MultiContent)
+ }
+ // The caller's slice must survive: the retry is built from the same
+ // messages the first attempt used.
+ if len(messages[0].MultiContent) != 2 || len(messages[0].Images) != 1 {
+ t.Fatalf("input mutated: %#v", messages[0])
+ }
+}
+
+// An images-only turn loses MultiContent entirely rather than going out as an
+// empty parts array, which some vendors reject.
+func TestStripImagesFromMessages_DropsEmptiedMultiContent(t *testing.T) {
+ cleaned := StripImagesFromMessages([]Message{{
+ Role: "user",
+ Content: "what is this",
+ MultiContent: []MessageContentPart{
+ {Type: "image_url", ImageURL: &ImageURL{URL: "https://example.com/a.png"}},
+ },
+ }})
+ if cleaned[0].MultiContent != nil {
+ t.Fatalf("MultiContent = %#v, want nil", cleaned[0].MultiContent)
+ }
+ if cleaned[0].Content != "what is this" {
+ t.Fatalf("Content = %q, want it untouched", cleaned[0].Content)
+ }
+}
+
+func TestIsMultimodalNotSupportedError(t *testing.T) {
+ cases := []struct {
+ name string
+ err error
+ want bool
+ }{
+ {
+ name: "explicit wording, no status",
+ err: fmt.Errorf("this model does not support image input"),
+ want: true,
+ },
+ {
+ name: "400 rejecting the image",
+ err: &HTTPError{StatusCode: 400, Body: `{"error":"invalid content type image_url"}`},
+ want: true,
+ },
+ {
+ name: "wrapped 400 still matches",
+ err: fmt.Errorf("create chat completion: %w",
+ &HTTPError{StatusCode: 400, Body: "image input rejected"}),
+ want: true,
+ },
+ {
+ // The old substring test fired here: HTTPError.Error() prints the
+ // status, so every 5xx mentioning an image looked like "model is
+ // not multimodal" and was retried stripped.
+ name: "server error mentioning an image is not a capability verdict",
+ err: &HTTPError{StatusCode: 500, Body: "image upload backend unavailable"},
+ want: false,
+ },
+ {
+ // "400" also hides inside ordinary numbers in vendor bodies.
+ name: "429 whose body merely contains 400",
+ err: &HTTPError{StatusCode: 429, Body: "image exceeds 4000 px, slow down"},
+ want: false,
+ },
+ {
+ name: "unrelated failure",
+ err: fmt.Errorf("context deadline exceeded"),
+ want: false,
+ },
+ {name: "nil", err: nil, want: false},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := IsMultimodalNotSupportedError(tc.err); got != tc.want {
+ t.Errorf("IsMultimodalNotSupportedError(%v) = %v, want %v", tc.err, got, tc.want)
+ }
+ })
+ }
+}
diff --git a/internal/models/chat/json_field_extractor.go b/internal/models/api/json_field_extractor.go
similarity index 93%
rename from internal/models/chat/json_field_extractor.go
rename to internal/models/api/json_field_extractor.go
index f0bfa4ebb..08f050794 100644
--- a/internal/models/chat/json_field_extractor.go
+++ b/internal/models/api/json_field_extractor.go
@@ -1,16 +1,16 @@
-package chat
+package api
import (
"strings"
"unicode/utf8"
)
-// jsonFieldExtractor extracts a specific string field value from streaming JSON fragments.
+// JSONFieldExtractor extracts a specific string field value from streaming JSON fragments.
// It processes incremental JSON argument chunks from LLM tool calls.
//
// Example: for fieldName="answer", expected JSON format: {"answer":"...content..."}
// The extractor uses a simple state machine to skip the JSON prefix and extract the string value.
-type jsonFieldExtractor struct {
+type JSONFieldExtractor struct {
fieldName string // the JSON field name to extract (e.g. "answer", "thought")
buffer string // accumulated full arguments string
valueStart int // byte offset where the field value starts (-1 if not found yet)
@@ -18,9 +18,9 @@ type jsonFieldExtractor struct {
done bool // whether we've seen the closing quote
}
-// newJSONFieldExtractor creates a new extractor instance for the given field name
-func newJSONFieldExtractor(fieldName string) *jsonFieldExtractor {
- return &jsonFieldExtractor{
+// NewJSONFieldExtractor creates a new extractor instance for the given field name
+func NewJSONFieldExtractor(fieldName string) *JSONFieldExtractor {
+ return &JSONFieldExtractor{
fieldName: fieldName,
valueStart: -1,
lastEmit: 0,
@@ -29,7 +29,7 @@ func newJSONFieldExtractor(fieldName string) *jsonFieldExtractor {
// Feed processes a new argument delta and returns any new content to emit.
// Returns empty string if no new content is available yet.
-func (e *jsonFieldExtractor) Feed(argsDelta string) string {
+func (e *JSONFieldExtractor) Feed(argsDelta string) string {
if e.done {
return ""
}
@@ -72,7 +72,7 @@ func (e *jsonFieldExtractor) Feed(argsDelta string) string {
}
// IsDone returns whether the extractor has finished (closing quote found)
-func (e *jsonFieldExtractor) IsDone() bool {
+func (e *JSONFieldExtractor) IsDone() bool {
return e.done
}
diff --git a/internal/models/chat/json_field_extractor_test.go b/internal/models/api/json_field_extractor_test.go
similarity index 89%
rename from internal/models/chat/json_field_extractor_test.go
rename to internal/models/api/json_field_extractor_test.go
index 2b84df7ae..952ca1754 100644
--- a/internal/models/chat/json_field_extractor_test.go
+++ b/internal/models/api/json_field_extractor_test.go
@@ -1,11 +1,11 @@
-package chat
+package api
import (
"testing"
)
func TestJSONFieldExtractor_Basic(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
// Simulate streaming JSON: {"answer":"Hello world"}
got := ""
@@ -23,7 +23,7 @@ func TestJSONFieldExtractor_Basic(t *testing.T) {
}
func TestJSONFieldExtractor_WithEscapes(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
// Simulate: {"answer":"line1\nline2 and \"quoted\""}
got := ""
@@ -38,7 +38,7 @@ func TestJSONFieldExtractor_WithEscapes(t *testing.T) {
}
func TestJSONFieldExtractor_OneChunk(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
got := e.Feed(`{"answer":"complete answer here"}`)
@@ -51,7 +51,7 @@ func TestJSONFieldExtractor_OneChunk(t *testing.T) {
}
func TestJSONFieldExtractor_SmallChunks(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
// Very small chunks
got := ""
@@ -66,7 +66,7 @@ func TestJSONFieldExtractor_SmallChunks(t *testing.T) {
}
func TestJSONFieldExtractor_Markdown(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
got := ""
got += e.Feed(`{"answer":"# Title\n\n`)
@@ -82,7 +82,7 @@ func TestJSONFieldExtractor_Markdown(t *testing.T) {
}
func TestJSONFieldExtractor_UnicodeEscape(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
got := ""
got += e.Feed(`{"answer":"Hello \u4e16\u754c`)
@@ -95,7 +95,7 @@ func TestJSONFieldExtractor_UnicodeEscape(t *testing.T) {
}
func TestJSONFieldExtractor_IncompleteEscapeAtBoundary(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
// Escape sequence split across chunks
got := ""
@@ -109,7 +109,7 @@ func TestJSONFieldExtractor_IncompleteEscapeAtBoundary(t *testing.T) {
}
func TestJSONFieldExtractor_WhitespaceInJSON(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
// Whitespace around colon
got := e.Feed(`{ "answer" : "content here" }`)
@@ -120,7 +120,7 @@ func TestJSONFieldExtractor_WhitespaceInJSON(t *testing.T) {
}
func TestJSONFieldExtractor_EmptyAnswer(t *testing.T) {
- e := newJSONFieldExtractor("answer")
+ e := NewJSONFieldExtractor("answer")
got := e.Feed(`{"answer":""}`)
@@ -134,7 +134,7 @@ func TestJSONFieldExtractor_EmptyAnswer(t *testing.T) {
// Test extracting "thought" field (for thinking tool)
func TestJSONFieldExtractor_ThoughtField(t *testing.T) {
- e := newJSONFieldExtractor("thought")
+ e := NewJSONFieldExtractor("thought")
got := ""
got += e.Feed(`{"thought":"Let me analyze`)
@@ -151,7 +151,7 @@ func TestJSONFieldExtractor_ThoughtField(t *testing.T) {
}
func TestJSONFieldExtractor_ThoughtFieldWithEscapes(t *testing.T) {
- e := newJSONFieldExtractor("thought")
+ e := NewJSONFieldExtractor("thought")
got := ""
got += e.Feed(`{"thought":"Step 1:\n- Analyze the query\n- `)
diff --git a/internal/models/api/openaicompletions/client.go b/internal/models/api/openaicompletions/client.go
new file mode 100644
index 000000000..062e46fda
--- /dev/null
+++ b/internal/models/api/openaicompletions/client.go
@@ -0,0 +1,398 @@
+package openaicompletions
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+const defaultPath = "/chat/completions"
+
+// Client talks Chat Completions to one endpoint.
+type Client struct {
+ cfg Config
+}
+
+// New creates a client. The endpoint must already carry auth and headers.
+func New(cfg Config) *Client {
+ if cfg.ThinkingLevels == nil {
+ cfg.ThinkingLevels = api.ThinkingLevelMap{}
+ }
+ return &Client{cfg: cfg}
+}
+
+// GetModelName returns the wire model name.
+func (c *Client) GetModelName() string { return c.cfg.Endpoint.Model }
+
+// GetModelID returns WeKnora's model identifier.
+func (c *Client) GetModelID() string { return c.cfg.Endpoint.ModelID }
+
+// Settings exposes the resolved settings (diagnostics, tests).
+func (c *Client) Settings() Config { return c.cfg }
+
+func (c *Client) url() string { return c.cfg.Endpoint.Resolve(defaultPath) }
+
+func (c *Client) send(
+ ctx context.Context, messages []api.Message, opts *api.Options, stream bool,
+) (*http.Response, []byte, error) {
+ opts = api.WithSessionCacheKey(ctx, opts)
+ body, err := c.BuildRequestBody(messages, opts, stream)
+ if err != nil {
+ return nil, nil, err
+ }
+ url := c.url()
+ req, data, err := c.cfg.Endpoint.NewRequest(ctx, url, body, stream)
+ if err != nil {
+ return nil, nil, err
+ }
+ if c.cfg.Settings.PromptCacheKey {
+ key := c.cfg.SessionID
+ if opts != nil && opts.PromptCacheKey != "" {
+ key = opts.PromptCacheKey
+ }
+ api.AttachSessionAffinityHeaders(req, api.ClampPromptCacheKey(key))
+ }
+ api.LogRequest(ctx, url, c.cfg.Endpoint.Model, data, stream)
+ resp, err := c.cfg.Endpoint.Do(req)
+ if err != nil {
+ return nil, data, err
+ }
+ return resp, data, nil
+}
+
+// Chat performs a non-streaming completion.
+func (c *Client) Chat(ctx context.Context, messages []api.Message, opts *api.Options) (*types.ChatResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultChatTimeout)
+ defer cancel()
+
+ resp, _, err := c.send(ctx, messages, opts, false)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Request] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, _, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, false)
+ }
+ if err != nil {
+ return nil, fmt.Errorf("create chat completion: %w", err)
+ }
+ }
+ defer func() { _ = resp.Body.Close() }()
+ raw, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return nil, fmt.Errorf("read response: %w", err)
+ }
+ result, err := c.parseResponse(raw)
+ if err != nil {
+ return nil, err
+ }
+ api.LogUsage(ctx, c.cfg.Endpoint.Model, &result.Usage)
+ return result, nil
+}
+
+// ChatStream performs a streaming completion.
+func (c *Client) ChatStream(
+ ctx context.Context, messages []api.Message, opts *api.Options,
+) (<-chan types.StreamResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultStreamTimeout)
+
+ resp, data, err := c.send(ctx, messages, opts, true)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Stream] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, data, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, true)
+ }
+ if err != nil {
+ cancel()
+ return nil, fmt.Errorf("create chat completion stream: %w", err)
+ }
+ }
+
+ ch := make(chan types.StreamResponse)
+ dumper := api.NewStreamPacketDumper(c.cfg.Endpoint.Model, json.RawMessage(data))
+ if dumper != nil {
+ logger.Infof(ctx, "[LLM Stream Raw Dump] writing packets to %s", dumper.Path())
+ }
+ go func() {
+ defer cancel()
+ defer close(ch)
+ defer func() { _ = resp.Body.Close() }()
+ if dumper != nil {
+ defer dumper.Close()
+ }
+ c.processStream(ctx, resp.Body, ch, dumper)
+ }()
+ return ch, nil
+}
+
+// --- response decoding ---
+
+type rawToolCall struct {
+ Index *int `json:"index,omitempty"`
+ ID string `json:"id,omitempty"`
+ Type string `json:"type,omitempty"`
+ Function struct {
+ Name string `json:"name,omitempty"`
+ Arguments string `json:"arguments,omitempty"`
+ } `json:"function"`
+}
+
+type rawMessage struct {
+ Role string `json:"role,omitempty"`
+ Content string `json:"content,omitempty"`
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ Reasoning string `json:"reasoning,omitempty"`
+ ReasoningText string `json:"reasoning_text,omitempty"`
+ ReasoningDetails json.RawMessage `json:"reasoning_details,omitempty"`
+ ToolCalls []json.RawMessage `json:"tool_calls,omitempty"`
+}
+
+type rawChoice struct {
+ Index int `json:"index"`
+ Message rawMessage `json:"message"`
+ Delta rawMessage `json:"delta"`
+ FinishReason string `json:"finish_reason,omitempty"`
+}
+
+type rawEnvelope struct {
+ Choices []rawChoice `json:"choices"`
+ Usage *api.OpenAIUsage `json:"usage,omitempty"`
+ Error *struct {
+ Message string `json:"message"`
+ Type string `json:"type"`
+ Code any `json:"code"`
+ } `json:"error,omitempty"`
+}
+
+func (c *Client) reasoningText(m rawMessage) string {
+ for _, field := range c.cfg.Settings.ReasoningFields {
+ switch field {
+ case "reasoning_content":
+ if m.ReasoningContent != "" {
+ return m.ReasoningContent
+ }
+ case "reasoning":
+ if m.Reasoning != "" {
+ return m.Reasoning
+ }
+ case "reasoning_text":
+ if m.ReasoningText != "" {
+ return m.ReasoningText
+ }
+ }
+ }
+ return ""
+}
+
+func (c *Client) decodeToolCalls(raws []json.RawMessage) ([]types.LLMToolCall, []api.ToolCallDelta, error) {
+ calls := make([]types.LLMToolCall, 0, len(raws))
+ deltas := make([]api.ToolCallDelta, 0, len(raws))
+ for i, raw := range raws {
+ var tc rawToolCall
+ if err := json.Unmarshal(raw, &tc); err != nil {
+ // Dropping the entry turns a round that wanted to call a tool into
+ // a plain answer, and the agent has no way to notice the action it
+ // was told to take went missing. Surface it instead.
+ return nil, nil, fmt.Errorf("decode tool call %d: %w", i, err)
+ }
+ idx := i
+ if tc.Index != nil {
+ idx = *tc.Index
+ }
+ call := types.LLMToolCall{
+ ID: tc.ID,
+ Type: orDefault(tc.Type, "function"),
+ Function: types.FunctionCall{Name: tc.Function.Name, Arguments: tc.Function.Arguments},
+ }
+ call.ProviderMetadata = c.extractToolCallMetadata(raw)
+ calls = append(calls, call)
+ deltas = append(deltas, api.ToolCallDelta{
+ Index: idx, ID: tc.ID, Type: tc.Type, Name: tc.Function.Name, Arguments: tc.Function.Arguments,
+ })
+ }
+ return calls, deltas, nil
+}
+
+func (c *Client) extractToolCallMetadata(raw json.RawMessage) types.ToolCallMetadata {
+ if len(c.cfg.Settings.ToolCallExtraFields) == 0 {
+ return nil
+ }
+ var obj map[string]json.RawMessage
+ if err := json.Unmarshal(raw, &obj); err != nil {
+ return nil
+ }
+ var md types.ToolCallMetadata
+ for _, key := range c.cfg.Settings.ToolCallExtraFields {
+ if v, ok := obj[key]; ok && len(v) > 0 && string(v) != "null" {
+ if md == nil {
+ md = types.ToolCallMetadata{}
+ }
+ md[key] = v
+ }
+ }
+ return md
+}
+
+func (c *Client) parseResponse(raw []byte) (*types.ChatResponse, error) {
+ var env rawEnvelope
+ if err := json.Unmarshal(raw, &env); err != nil {
+ return nil, fmt.Errorf("decode response: %w", err)
+ }
+ if env.Error != nil && env.Error.Message != "" {
+ return nil, fmt.Errorf("API error: %s", env.Error.Message)
+ }
+ if len(env.Choices) == 0 {
+ return nil, fmt.Errorf("no response from API")
+ }
+ choice := env.Choices[0]
+ content, inlineReasoning := splitThinkTags(choice.Message.Content)
+ result := &types.ChatResponse{
+ Content: content,
+ ReasoningContent: c.reasoningText(choice.Message),
+ FinishReason: choice.FinishReason,
+ }
+ if result.ReasoningContent == "" {
+ result.ReasoningContent = inlineReasoning
+ }
+ if len(choice.Message.ReasoningDetails) > 0 {
+ result.ReasoningMetadata = types.ProviderMetadata{metadataReasoningDetails: choice.Message.ReasoningDetails}
+ }
+ if len(choice.Message.ToolCalls) > 0 {
+ calls, _, err := c.decodeToolCalls(choice.Message.ToolCalls)
+ if err != nil {
+ return nil, err
+ }
+ result.ToolCalls = calls
+ }
+ // Classify the cache status even when the vendor omitted the usage block,
+ // so "no counters at all" is still distinguishable from a real miss on the
+ // usage dashboards instead of landing as an empty CacheStatus.
+ usage := api.OpenAIUsage{}
+ if env.Usage != nil {
+ usage = *env.Usage
+ }
+ result.Usage = usage.ToTokenUsage(c.cfg.Settings.PromptCacheAccounting)
+ return result, nil
+}
+
+// splitThinkTags handles models that inline their chain of thought as a
+// leading <think>...</think> block instead of a reasoning field.
+func splitThinkTags(content string) (answer, reasoning string) {
+ const start, end = "<think>", "</think>"
+ trimmed := strings.TrimSpace(content)
+ if !strings.HasPrefix(trimmed, start) {
+ return content, ""
+ }
+ idx := strings.LastIndex(trimmed, end)
+ if idx < 0 {
+ // Unterminated: the whole output is (truncated) reasoning.
+ return "", strings.TrimSpace(trimmed[len(start):])
+ }
+ return strings.TrimSpace(trimmed[idx+len(end):]), strings.TrimSpace(trimmed[len(start):idx])
+}
+
+func (c *Client) processStream(
+ ctx context.Context, body io.Reader, ch chan<- types.StreamResponse, dumper *api.StreamPacketDumper,
+) {
+ assembler := api.NewStreamAssembler(ctx, c.cfg.Endpoint.Model)
+ reader := api.NewSSEReader(body)
+ var reasoningDetails []json.RawMessage
+
+ finish := func() {
+ if len(reasoningDetails) > 0 {
+ merged, _ := json.Marshal(reasoningDetails)
+ assembler.ReasoningMetadata = types.ProviderMetadata{metadataReasoningDetails: merged}
+ }
+ assembler.End(ch)
+ }
+
+ for {
+ // The consumer went away (client disconnect, aborted agent turn): stop
+ // decoding a stream nobody will read instead of spinning to EOF.
+ if assembler.Aborted() {
+ return
+ }
+ event, err := reader.ReadEvent()
+ if err != nil {
+ if err == io.EOF {
+ finish()
+ } else {
+ assembler.Fail(ch, err)
+ }
+ return
+ }
+ if event == nil {
+ continue
+ }
+ if event.Done {
+ finish()
+ return
+ }
+ if len(event.Data) == 0 {
+ continue
+ }
+ if dumper != nil {
+ raw := make([]byte, len(event.Data))
+ copy(raw, event.Data)
+ dumper.WritePacketRaw(raw)
+ }
+
+ var env rawEnvelope
+ if err := json.Unmarshal(event.Data, &env); err != nil {
+ // Fail rather than skip, as the Anthropic and Gemini loops do. A
+ // chunk we cannot decode is a hole in the answer: skipping it ends
+ // the stream on EOF, which reaches the caller as a *successful*
+ // truncated reply and gets persisted as the model's answer. An
+ // error at least surfaces the proxy that corrupted the stream.
+ assembler.Fail(ch, fmt.Errorf("decode stream chunk: %w", err))
+ return
+ }
+ if env.Error != nil && env.Error.Message != "" {
+ assembler.Fail(ch, fmt.Errorf("API stream error: %s", env.Error.Message))
+ return
+ }
+ if env.Usage != nil {
+ assembler.SetUsage(env.Usage.ToTokenUsage(c.cfg.Settings.PromptCacheAccounting))
+ }
+ if len(env.Choices) == 0 {
+ continue
+ }
+ choice := env.Choices[0]
+ delta := api.Delta{
+ Reasoning: c.reasoningText(choice.Delta),
+ Content: choice.Delta.Content,
+ FinishReason: choice.FinishReason,
+ }
+ if len(choice.Delta.ReasoningDetails) > 0 {
+ var items []json.RawMessage
+ if err := json.Unmarshal(choice.Delta.ReasoningDetails, &items); err == nil {
+ reasoningDetails = append(reasoningDetails, items...)
+ }
+ }
+ if len(choice.Delta.ToolCalls) > 0 {
+ _, deltas, err := c.decodeToolCalls(choice.Delta.ToolCalls)
+ if err != nil {
+ assembler.Fail(ch, err)
+ return
+ }
+ delta.ToolCalls = deltas
+ for i, raw := range choice.Delta.ToolCalls {
+ if md := c.extractToolCallMetadata(raw); len(md) > 0 {
+ idx := i
+ if i < len(deltas) {
+ idx = deltas[i].Index
+ }
+ assembler.SetToolCallMetadata(idx, md)
+ }
+ }
+ }
+ assembler.Process(ch, delta)
+ }
+}
diff --git a/internal/models/api/openaicompletions/golden_test.go b/internal/models/api/openaicompletions/golden_test.go
new file mode 100644
index 000000000..33898a63a
--- /dev/null
+++ b/internal/models/api/openaicompletions/golden_test.go
@@ -0,0 +1,632 @@
+package openaicompletions
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func newClient(t *testing.T, mutate func(*Config)) *Client {
+ t.Helper()
+ cfg := Config{
+ Endpoint: api.Endpoint{
+ BaseURL: "https://example.com/v1", Model: "m", ModelID: "id", Auth: api.BearerAuth("k"),
+ },
+ Settings: catalog.DefaultOpenAICompletions(),
+ ThinkingLevels: api.ThinkingLevelMap{},
+ }
+ if mutate != nil {
+ mutate(&cfg)
+ }
+ return New(cfg)
+}
+
+func bodyJSON(t *testing.T, c *Client, msgs []api.Message, opts *api.Options, stream bool) map[string]any {
+ t.Helper()
+ body, err := c.BuildRequestBody(msgs, opts, stream)
+ require.NoError(t, err)
+ data, err := json.Marshal(body)
+ require.NoError(t, err)
+ var out map[string]any
+ require.NoError(t, json.Unmarshal(data, &out))
+ return out
+}
+
+func ptrBool(b bool) *bool { return &b }
+
+var conversation = []api.Message{
+ {Role: "system", Content: "You are helpful."},
+ {Role: "user", Content: "hi"},
+ {Role: "assistant", ReasoningContent: "thinking...", ToolCalls: []api.ToolCall{{
+ ID: "call_1", Type: "function", Function: api.FunctionCall{Name: "search", Arguments: `{"q":"x"}`},
+ }}},
+ {Role: "tool", ToolCallID: "call_1", Name: "search", Content: "result"},
+}
+
+var toolOpts = &api.Options{
+ Temperature: 0.7, MaxTokens: 1000,
+ Tools: []api.Tool{{Type: "function", Function: api.FunctionDef{
+ Name: "search", Description: "d", Parameters: json.RawMessage(`{"type":"object","properties":{}}`),
+ }}},
+ ToolChoice: "required", ParallelToolCalls: ptrBool(true),
+}
+
+// TestGolden pins the exact wire body per vendor dialect. Each case is one
+// row of the vendor fact table; changing a vendor's behaviour means changing
+// the expectation here on purpose.
+func TestGolden(t *testing.T) {
+ cases := []struct {
+ name string
+ mutate func(*Config)
+ opts *api.Options
+ stream bool
+ want map[string]any // keys asserted; value nil means "must be absent"
+ }{
+ {
+ name: "openai baseline: max_completion_tokens, store, developer role off for non-reasoning",
+ mutate: func(c *Config) {
+ c.Settings.SupportsStore = true
+ c.Settings.SupportsDeveloperRole = true
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatOpenAI
+ c.Settings.SupportsReasoningEffort = true
+ },
+ opts: toolOpts,
+ stream: true,
+ want: map[string]any{
+ "max_completion_tokens": float64(1000), "max_tokens": nil,
+ "store": false, "stream": true, "stream_options": map[string]any{"include_usage": true},
+ "temperature": 0.7, "tool_choice": "required", "parallel_tool_calls": true,
+ "reasoning_effort": nil,
+ },
+ },
+ {
+ name: "openai reasoning model: developer role, no sampling, effort medium",
+ mutate: func(c *Config) {
+ c.Reasoning = true
+ c.Settings.SupportsDeveloperRole = true
+ c.Settings.SupportsTemperature = false
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatOpenAI
+ c.Settings.SupportsReasoningEffort = true
+ },
+ opts: &api.Options{Temperature: 0.7, MaxTokens: 10, ReasoningEffort: api.ReasoningMedium},
+ want: map[string]any{
+ "temperature": nil, "reasoning_effort": "medium", "max_completion_tokens": float64(10),
+ },
+ },
+ {
+ name: "openai gpt-5.1 off maps to reasoning_effort none",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatOpenAI
+ c.Settings.SupportsReasoningEffort = true
+ c.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningOff: api.StringPtr("none")}
+ },
+ opts: &api.Options{Thinking: ptrBool(false)},
+ want: map[string]any{"reasoning_effort": "none"},
+ },
+ {
+ name: "deepseek: max_tokens, thinking.type + effort clamp, tool_choice required dropped",
+ mutate: func(c *Config) {
+ c.Settings.MaxTokensField = "max_tokens"
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatThinkingType
+ c.Settings.SupportsReasoningEffort = true
+ c.Settings.ToolChoiceModes = []string{"none", "auto"}
+ c.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningMedium: api.StringPtr("high")}
+ },
+ opts: func() *api.Options { o := *toolOpts; o.ReasoningEffort = api.ReasoningMedium; return &o }(),
+ want: map[string]any{
+ "max_tokens": float64(1000), "max_completion_tokens": nil,
+ "thinking": map[string]any{"type": "enabled"}, "reasoning_effort": "high",
+ "tool_choice": nil, "parallel_tool_calls": true,
+ },
+ },
+ {
+ name: "deepseek reasoner: always-on, off request sends nothing",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatThinkingType
+ c.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningOff: nil}
+ },
+ opts: &api.Options{Thinking: ptrBool(false)},
+ want: map[string]any{"thinking": nil},
+ },
+ {
+ name: "zhipu: thinking disabled explicitly",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatThinkingType
+ },
+ opts: &api.Options{Thinking: ptrBool(false)},
+ want: map[string]any{"thinking": map[string]any{"type": "disabled"}},
+ },
+ {
+ name: "minimax m3: adaptive thinking value",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatThinkingType
+ c.Settings.ThinkingEnabledValue = "adaptive"
+ },
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"thinking": map[string]any{"type": "adaptive"}, "reasoning_effort": nil},
+ },
+ {
+ name: "dashscope hybrid: enable_thinking always sent, budget, non-stream forces off",
+ mutate: func(c *Config) {
+ c.Settings.MaxTokensField = "max_tokens"
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatEnableThinking
+ c.Settings.ThinkingBudgetField = "thinking_budget"
+ c.Settings.ThinkingAlwaysSend = true
+ c.Settings.ThinkingDisableOnNonStream = true
+ },
+ opts: &api.Options{Thinking: ptrBool(true), ThinkingBudgetTokens: 4096},
+ stream: false,
+ want: map[string]any{"enable_thinking": false, "thinking_budget": nil},
+ },
+ {
+ name: "dashscope hybrid streaming: enable_thinking true with budget",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatEnableThinking
+ c.Settings.ThinkingBudgetField = "thinking_budget"
+ c.Settings.ThinkingAlwaysSend = true
+ c.Settings.ThinkingDisableOnNonStream = true
+ },
+ opts: &api.Options{Thinking: ptrBool(true), ThinkingBudgetTokens: 4096},
+ stream: true,
+ want: map[string]any{"enable_thinking": true, "thinking_budget": float64(4096)},
+ },
+ {
+ name: "dashscope: no preference still pins enable_thinking false",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatEnableThinking
+ c.Settings.ThinkingAlwaysSend = true
+ },
+ opts: &api.Options{Temperature: 0.1},
+ want: map[string]any{"enable_thinking": false},
+ },
+ {
+ name: "vllm: chat_template_kwargs",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatChatTemplateKwargs
+ },
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"chat_template_kwargs": map[string]any{"enable_thinking": true}},
+ },
+ {
+ name: "openrouter: reasoning effort object and enabled=false",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatOpenRouter
+ c.Settings.SupportsReasoningEffort = true
+ },
+ opts: &api.Options{ReasoningEffort: api.ReasoningHigh},
+ want: map[string]any{"reasoning": map[string]any{"effort": "high"}},
+ },
+ {
+ name: "openrouter: auto enables without effort",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatOpenRouter
+ c.Settings.SupportsReasoningEffort = true
+ },
+ opts: &api.Options{ReasoningEffort: api.ReasoningAuto},
+ want: map[string]any{"reasoning": map[string]any{"enabled": true}},
+ },
+ {
+ name: "moonshot v1: fixed temperature, other sampling dropped",
+ mutate: func(c *Config) {
+ one := 1.0
+ c.Settings.FixedTemperature = &one
+ },
+ opts: &api.Options{Temperature: 0.2, TopP: 0.9},
+ want: map[string]any{"temperature": 1.0, "top_p": nil},
+ },
+ {
+ name: "no thinking preference on a plain vendor sends no thinking fields",
+ mutate: func(c *Config) {
+ c.Settings.ThinkingFormat = catalog.ThinkingFormatThinkingType
+ },
+ opts: &api.Options{Temperature: 0.2},
+ want: map[string]any{"thinking": nil, "reasoning_effort": nil, "enable_thinking": nil},
+ },
+ {
+ name: "prompt cache key and long retention",
+ mutate: func(c *Config) {
+ c.Settings.PromptCacheKey = true
+ },
+ opts: &api.Options{PromptCacheKey: "sess-1", CacheRetention: api.CacheRetentionLong},
+ want: map[string]any{"prompt_cache_key": "sess-1", "prompt_cache_retention": "24h"},
+ },
+ {
+ name: "extra_body merges vendor knobs without overriding caller fields",
+ mutate: func(c *Config) {
+ c.Settings.ExtraBody = map[string]any{"enable_search": true, "temperature": 0.9}
+ },
+ opts: &api.Options{Temperature: 0.2},
+ want: map[string]any{"enable_search": true, "temperature": 0.2},
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ c := newClient(t, tc.mutate)
+ got := bodyJSON(t, c, conversation, tc.opts, tc.stream)
+ for key, want := range tc.want {
+ if want == nil {
+ _, present := got[key]
+ assert.False(t, present, "field %q must be absent, got %v", key, got[key])
+ continue
+ }
+ assert.Equal(t, want, got[key], "field %q", key)
+ }
+ })
+ }
+}
+
+func TestMessages_RolesToolsAndReasoningReplay(t *testing.T) {
+ c := newClient(t, func(c *Config) {
+ c.Reasoning = true
+ c.Settings.SupportsDeveloperRole = true
+ })
+ got := bodyJSON(t, c, conversation, nil, false)
+ msgs := got["messages"].([]any)
+ require.Len(t, msgs, 4)
+ assert.Equal(t, "developer", msgs[0].(map[string]any)["role"])
+ assistant := msgs[2].(map[string]any)
+ assert.Equal(t, "thinking...", assistant["reasoning_content"])
+ _, hasContent := assistant["content"]
+ assert.False(t, hasContent, "empty content omitted next to tool_calls")
+ tc := assistant["tool_calls"].([]any)[0].(map[string]any)
+ assert.Equal(t, "call_1", tc["id"])
+ assert.Equal(t, `{"q":"x"}`, tc["function"].(map[string]any)["arguments"])
+ tool := msgs[3].(map[string]any)
+ assert.Equal(t, "call_1", tool["tool_call_id"])
+ assert.Equal(t, "search", tool["name"])
+
+ plain := newClient(t, func(c *Config) { c.Settings.ReplayReasoningContent = false })
+ got = bodyJSON(t, plain, conversation, nil, false)
+ assistant = got["messages"].([]any)[2].(map[string]any)
+ _, has := assistant["reasoning_content"]
+ assert.False(t, has)
+ assert.Equal(t, "system", got["messages"].([]any)[0].(map[string]any)["role"])
+}
+
+func TestMessages_ImagesAndMultiContentDowngrade(t *testing.T) {
+ msgs := []api.Message{{Role: "user", Content: "look", Images: []string{"https://img/x.png"}}}
+ c := newClient(t, nil)
+ got := bodyJSON(t, c, msgs, nil, false)
+ parts := got["messages"].([]any)[0].(map[string]any)["content"].([]any)
+ require.Len(t, parts, 2)
+ assert.Equal(t, "image_url", parts[0].(map[string]any)["type"])
+ assert.Equal(t, "look", parts[1].(map[string]any)["text"])
+
+ flat := newClient(t, func(c *Config) { c.Settings.SupportsMultiContent = false })
+ got = bodyJSON(t, flat, msgs, nil, false)
+ assert.Equal(t, "look", got["messages"].([]any)[0].(map[string]any)["content"])
+}
+
+func TestToolCallExtraFieldsRoundTrip(t *testing.T) {
+ c := newClient(t, func(c *Config) { c.Settings.ToolCallExtraFields = []string{"extra_content"} })
+ md := c.extractToolCallMetadata(json.RawMessage(`{"id":"call_1","type":"function",` +
+ `"function":{"name":"f","arguments":"{}"},"extra_content":{"google":{"thought_signature":"abc"}}}`))
+ require.NotNil(t, md)
+ assert.JSONEq(t, `{"google":{"thought_signature":"abc"}}`, string(md["extra_content"]))
+
+ msgs := []api.Message{{Role: "assistant", ToolCalls: []api.ToolCall{{
+ ID: "call_1", Type: "function", Function: api.FunctionCall{Name: "f", Arguments: "{}"}, ProviderMetadata: md,
+ }}}}
+ got := bodyJSON(t, c, msgs, nil, false)
+ tc := got["messages"].([]any)[0].(map[string]any)["tool_calls"].([]any)[0].(map[string]any)
+ assert.Equal(t, map[string]any{"google": map[string]any{"thought_signature": "abc"}}, tc["extra_content"])
+}
+
+func TestCacheControlBreakpoints(t *testing.T) {
+ c := newClient(t, func(c *Config) { c.Settings.CacheControlFormat = "anthropic" })
+ got := bodyJSON(t, c, conversation, toolOpts, false)
+ data, _ := json.Marshal(got)
+ assert.Equal(t, 3, strings.Count(string(data), `"cache_control"`))
+
+ none := bodyJSON(t, c, conversation, &api.Options{CacheRetention: api.CacheRetentionNone}, false)
+ data, _ = json.Marshal(none)
+ assert.NotContains(t, string(data), "cache_control")
+}
+
+func TestChat_NonStreamDecoding(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ var captured http.Header
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ captured = r.Header.Clone()
+ assert.Equal(t, "/v1/chat/completions", r.URL.Path)
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"index":0,"message":{"role":"assistant",` +
+ `"content":"<think>deep</think>answer",` +
+ `"tool_calls":[{"id":"c1","type":"function","function":{"name":"f","arguments":"{\"a\":1}"}}]},` +
+ `"finish_reason":"tool_calls"}],` +
+ `"usage":{"prompt_tokens":30,"completion_tokens":5,` +
+ `"prompt_cache_hit_tokens":20,"prompt_cache_miss_tokens":10}}`))
+ }))
+ defer server.Close()
+
+ c := New(Config{
+ Endpoint: api.Endpoint{
+ BaseURL: server.URL + "/v1", Model: "m", Auth: api.BearerAuth("sk"),
+ Headers: map[string]string{"X-Custom": "1", "Authorization": "Bearer evil"},
+ },
+ Settings: func() catalog.OpenAICompletionsSettings {
+ s := catalog.DefaultOpenAICompletions()
+ s.PromptCacheAccounting = true
+ return s
+ }(),
+ })
+ resp, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.NoError(t, err)
+ assert.Equal(t, "Bearer sk", captured.Get("Authorization"), "user headers cannot override auth")
+ assert.Equal(t, "1", captured.Get("X-Custom"))
+ assert.Equal(t, "answer", resp.Content)
+ assert.Equal(t, "deep", resp.ReasoningContent)
+ assert.Equal(t, "tool_calls", resp.FinishReason)
+ require.Len(t, resp.ToolCalls, 1)
+ assert.Equal(t, 20, resp.Usage.CacheReadTokens)
+ assert.Equal(t, 10, resp.Usage.CacheMissTokens)
+}
+
+func TestChat_HTTPErrorSurfacesBody(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.WriteHeader(http.StatusBadRequest)
+ _, _ = w.Write([]byte(`{"error":{"message":"max_tokens is not supported"}}`))
+ }))
+ defer server.Close()
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL, Model: "m"}, Settings: catalog.DefaultOpenAICompletions(),
+ })
+ _, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "status 400")
+ assert.Contains(t, err.Error(), "max_tokens is not supported")
+}
+
+const streamFixture = `data: {"choices":[{"index":0,"delta":{"role":"assistant","reasoning_content":"thi"}}]}
+
+data: {"choices":[{"index":0,"delta":{"reasoning_content":"nk"}}]}
+
+data: {"choices":[{"index":0,"delta":{"content":"Hel"}}]}
+
+data: {"choices":[{"index":0,"delta":{"content":"lo"}}]}
+
+data: {"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"c1","type":"function",` +
+ `"function":{"name":"search"}}]}}]}
+
+data: {"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"q\":"}}]}}]}
+
+data: {"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\"x\"}"}}]}}]}
+
+data: {"choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}
+
+data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":7,"prompt_tokens_details":{"cached_tokens":4}}}
+
+data: [DONE]
+`
+
+func TestChatStream_Sequence(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var body map[string]any
+ require.NoError(t, json.NewDecoder(r.Body).Decode(&body))
+ assert.Equal(t, true, body["stream"])
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(streamFixture))
+ }))
+ defer server.Close()
+
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL, Model: "m"}, Settings: catalog.DefaultOpenAICompletions(),
+ })
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.NoError(t, err)
+
+ var thinking, answer strings.Builder
+ var seenTypes []types.ResponseType
+ var last types.StreamResponse
+ thinkingDone := false
+ for chunk := range ch {
+ seenTypes = append(seenTypes, chunk.ResponseType)
+ switch chunk.ResponseType {
+ case types.ResponseTypeThinking:
+ if chunk.Done {
+ thinkingDone = true
+ }
+ thinking.WriteString(chunk.Content)
+ case types.ResponseTypeAnswer:
+ answer.WriteString(chunk.Content)
+ if chunk.Done {
+ last = chunk
+ }
+ case types.ResponseTypeToolCall:
+ assert.Equal(t, "search", chunk.Data["tool_name"])
+ assert.Equal(t, "c1", chunk.Data["tool_call_id"])
+ case types.ResponseTypeError:
+ t.Fatalf("unexpected error: %s", chunk.Content)
+ }
+ }
+ assert.Equal(t, "think", thinking.String())
+ assert.True(t, thinkingDone, "thinking done marker emitted before the answer")
+ assert.Equal(t, "Hello", answer.String())
+ assert.Contains(t, seenTypes, types.ResponseTypeToolCall)
+ require.Len(t, last.ToolCalls, 1)
+ assert.Equal(t, `{"q":"x"}`, last.ToolCalls[0].Function.Arguments)
+ assert.Equal(t, "tool_calls", last.FinishReason)
+ require.NotNil(t, last.Usage)
+ assert.Equal(t, 12, last.Usage.PromptTokens)
+ assert.Equal(t, 4, last.Usage.CacheReadTokens)
+}
+
+func TestSplitThinkTags(t *testing.T) {
+ answer, reasoning := splitThinkTags("<think>a</think>b")
+ assert.Equal(t, "b", answer)
+ assert.Equal(t, "a", reasoning)
+ answer, reasoning = splitThinkTags("<think>truncated")
+ assert.Equal(t, "", answer)
+ assert.Equal(t, "truncated", reasoning)
+ answer, reasoning = splitThinkTags("plain")
+ assert.Equal(t, "plain", answer)
+ assert.Equal(t, "", reasoning)
+}
+
+// A response without a usage block must still classify the cache status:
+// leaving it empty makes "the vendor reported nothing" look like a real miss
+// on the usage dashboards. The pre-split implementation always classified.
+func TestChat_ClassifiesCacheStatusWithoutUsageBlock(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"index":0,"message":{"role":"assistant","content":"hi"},` +
+ `"finish_reason":"stop"}]}`))
+ }))
+ defer server.Close()
+
+ for _, tc := range []struct {
+ name string
+ accounting bool
+ want types.PromptCacheStatus
+ }{
+ {"vendor documents cache accounting", true, types.PromptCacheStatusUnreported},
+ {"vendor has no cache accounting", false, types.PromptCacheStatusUnsupported},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL + "/v1", Model: "m", Auth: api.BearerAuth("sk")},
+ Settings: func() catalog.OpenAICompletionsSettings {
+ s := catalog.DefaultOpenAICompletions()
+ s.PromptCacheAccounting = tc.accounting
+ return s
+ }(),
+ })
+ resp, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.NoError(t, err)
+ assert.Equal(t, tc.want, resp.Usage.CacheStatus)
+ })
+ }
+}
+
+// A stream that ends on the [DONE] sentinel without a space after the colon
+// must still terminate cleanly rather than logging a JSON parse failure.
+func TestChatStream_TolerantDoneSentinel(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(
+ "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"hi\"},\"finish_reason\":\"stop\"}]}\n\n" +
+ "data:[DONE]\n\n"))
+ }))
+ defer server.Close()
+
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL + "/v1", Model: "m", Auth: api.BearerAuth("sk")},
+ Settings: catalog.DefaultOpenAICompletions(),
+ })
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.NoError(t, err)
+ var answer strings.Builder
+ for chunk := range ch {
+ if chunk.ResponseType == types.ResponseTypeError {
+ t.Fatalf("unexpected error chunk: %s", chunk.Content)
+ }
+ answer.WriteString(chunk.Content)
+ }
+ assert.Equal(t, "hi", answer.String())
+}
+
+// A chunk that will not decode is a hole in the answer. Skipping it (the old
+// behaviour) ended the stream on EOF, so a proxy that corrupted one packet
+// produced a truncated reply that every caller recorded as a successful one.
+// The Anthropic and Gemini loops fail in this situation; so does this one.
+func TestChatStream_UndecodableChunkFailsTheStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(
+ "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hel\"}}]}\n\n" +
+ "data: <html>502 Bad Gateway</html>\n\n" +
+ "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"lo\"},\"finish_reason\":\"stop\"}]}\n\n" +
+ "data: [DONE]\n\n"))
+ }))
+ defer server.Close()
+
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL + "/v1", Model: "m", Auth: api.BearerAuth("sk")},
+ Settings: catalog.DefaultOpenAICompletions(),
+ })
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.NoError(t, err)
+
+ var sawError bool
+ var answer strings.Builder
+ for chunk := range ch {
+ if chunk.ResponseType == types.ResponseTypeError {
+ sawError = true
+ assert.Contains(t, chunk.Content, "decode stream chunk")
+ continue
+ }
+ answer.WriteString(chunk.Content)
+ }
+ assert.True(t, sawError, "a truncated stream must surface as an error, not as a short answer")
+ assert.Equal(t, "Hel", answer.String(), "decoding stops at the bad chunk")
+}
+
+// A tool_calls entry we cannot decode used to be skipped, so a round that
+// wanted to call a tool arrived at the agent as a plain answer with nothing
+// to act on. Losing the action is worse than failing the round.
+func TestChat_MalformedToolCallIsAnError(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"index":0,"message":{"role":"assistant","content":"",` +
+ `"tool_calls":["not-an-object"]},"finish_reason":"tool_calls"}]}`))
+ }))
+ defer server.Close()
+
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL + "/v1", Model: "m", Auth: api.BearerAuth("sk")},
+ Settings: catalog.DefaultOpenAICompletions(),
+ })
+ _, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.Error(t, err, "a tool call that will not decode must not pass as a plain answer")
+ assert.Contains(t, err.Error(), "decode tool call")
+}
+
+// The streaming counterpart: the round must end as an error rather than as a
+// short answer whose tool call quietly vanished.
+func TestChatStream_MalformedToolCallFailsTheStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(
+ "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"ok\"}}]}\n\n" +
+ "data: {\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[42]}}]}\n\n" +
+ "data: {\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"tool_calls\"}]}\n\n" +
+ "data: [DONE]\n\n"))
+ }))
+ defer server.Close()
+
+ c := New(Config{
+ Endpoint: api.Endpoint{BaseURL: server.URL + "/v1", Model: "m", Auth: api.BearerAuth("sk")},
+ Settings: catalog.DefaultOpenAICompletions(),
+ })
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ require.NoError(t, err)
+
+ var sawError bool
+ var answer strings.Builder
+ for chunk := range ch {
+ if chunk.ResponseType == types.ResponseTypeError {
+ sawError = true
+ assert.Contains(t, chunk.Content, "decode tool call")
+ continue
+ }
+ answer.WriteString(chunk.Content)
+ }
+ assert.True(t, sawError, "a dropped tool call must surface as an error")
+ assert.Equal(t, "ok", answer.String(), "decoding stops at the bad chunk")
+}
diff --git a/internal/models/api/openaicompletions/request.go b/internal/models/api/openaicompletions/request.go
new file mode 100644
index 000000000..67ddf8836
--- /dev/null
+++ b/internal/models/api/openaicompletions/request.go
@@ -0,0 +1,427 @@
+// Package openaicompletions implements the OpenAI Chat Completions wire
+// protocol. Every vendor-specific deviation is driven by
+// catalog.OpenAICompletionsSettings; this package contains no vendor names.
+package openaicompletions
+
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+)
+
+// Config is everything the client needs, already resolved by the catalog.
+type Config struct {
+ Endpoint api.Endpoint
+ Settings catalog.OpenAICompletionsSettings
+ // ThinkingLevels maps neutral levels to the vendor vocabulary.
+ ThinkingLevels api.ThinkingLevelMap
+ // Reasoning marks a reasoning model (developer role, no sampling params
+ // are decided by Settings, this only gates role selection).
+ Reasoning bool
+ // SessionID feeds prompt_cache_key when the caller sets none.
+ SessionID string
+}
+
+type wireToolCall struct {
+ ID string `json:"id,omitempty"`
+ Type string `json:"type"`
+ Function wireFunctionCall `json:"function"`
+ extra map[string]json.RawMessage
+}
+
+type wireFunctionCall struct {
+ Name string `json:"name"`
+ Arguments string `json:"arguments"`
+}
+
+// MarshalJSON appends opaque vendor fields (Gemini extra_content) next to
+// the standard members.
+func (t wireToolCall) MarshalJSON() ([]byte, error) {
+ type plain wireToolCall
+ data, err := json.Marshal(plain(t))
+ if err != nil {
+ return nil, err
+ }
+ if len(t.extra) == 0 {
+ return data, nil
+ }
+ var obj map[string]json.RawMessage
+ if err := json.Unmarshal(data, &obj); err != nil {
+ return nil, err
+ }
+ for k, v := range t.extra {
+ obj[k] = v
+ }
+ return json.Marshal(obj)
+}
+
+type wireMessage struct {
+ Role string `json:"role"`
+ Content any `json:"content,omitempty"`
+ Name string `json:"name,omitempty"`
+ ToolCallID string `json:"tool_call_id,omitempty"`
+ ToolCalls []wireToolCall `json:"tool_calls,omitempty"`
+ ReasoningContent *string `json:"reasoning_content,omitempty"`
+ ReasoningDetails json.RawMessage `json:"reasoning_details,omitempty"`
+}
+
+type wirePart struct {
+ Type string `json:"type"`
+ Text string `json:"text,omitempty"`
+ ImageURL *wireImageURL `json:"image_url,omitempty"`
+}
+
+type wireImageURL struct {
+ URL string `json:"url"`
+ Detail string `json:"detail,omitempty"`
+}
+
+// convertMessages maps neutral messages onto Chat Completions messages.
+func (c *Client) convertMessages(messages []api.Message) []wireMessage {
+ s := c.cfg.Settings
+ instructionRole := "system"
+ if c.cfg.Reasoning && s.SupportsDeveloperRole {
+ instructionRole = "developer"
+ }
+ out := make([]wireMessage, 0, len(messages))
+ for _, msg := range messages {
+ msg = api.NeutralizeMessageSpecialTokens(msg)
+ wm := wireMessage{Role: msg.Role}
+ if msg.Role == "system" {
+ wm.Role = instructionRole
+ }
+
+ switch {
+ case len(msg.MultiContent) > 0:
+ parts := make([]wirePart, 0, len(msg.MultiContent))
+ for _, part := range msg.MultiContent {
+ switch part.Type {
+ case "text":
+ parts = append(parts, wirePart{Type: "text", Text: part.Text})
+ case "image_url":
+ if part.ImageURL != nil {
+ parts = append(parts, wirePart{Type: "image_url", ImageURL: &wireImageURL{
+ URL: api.ResolveImageURLForLLM(part.ImageURL.URL), Detail: part.ImageURL.Detail,
+ }})
+ }
+ }
+ }
+ wm.Content = c.contentParts(parts)
+ case len(msg.Images) > 0 && msg.Role == "user":
+ parts := make([]wirePart, 0, len(msg.Images)+1)
+ for _, img := range msg.Images {
+ parts = append(parts, wirePart{Type: "image_url", ImageURL: &wireImageURL{
+ URL: api.ResolveImageURLForLLM(img), Detail: "auto",
+ }})
+ }
+ parts = append(parts, wirePart{Type: "text", Text: msg.Content})
+ wm.Content = c.contentParts(parts)
+ default:
+ if msg.Content != "" || len(msg.ToolCalls) == 0 {
+ wm.Content = msg.Content
+ }
+ }
+
+ if len(msg.ToolCalls) > 0 {
+ wm.ToolCalls = make([]wireToolCall, 0, len(msg.ToolCalls))
+ for _, tc := range msg.ToolCalls {
+ wtc := wireToolCall{
+ ID: tc.ID,
+ Type: orDefault(tc.Type, "function"),
+ Function: wireFunctionCall{Name: tc.Function.Name, Arguments: tc.Function.Arguments},
+ }
+ for _, key := range s.ToolCallExtraFields {
+ if raw, ok := tc.ProviderMetadata[key]; ok && len(raw) > 0 {
+ if wtc.extra == nil {
+ wtc.extra = map[string]json.RawMessage{}
+ }
+ wtc.extra[key] = raw
+ }
+ }
+ wm.ToolCalls = append(wm.ToolCalls, wtc)
+ }
+ }
+
+ if msg.Role == "tool" {
+ wm.ToolCallID = msg.ToolCallID
+ wm.Name = msg.Name
+ }
+
+ if msg.Role == "assistant" {
+ if s.ReplayReasoningContent && msg.ReasoningContent != "" {
+ rc := msg.ReasoningContent
+ wm.ReasoningContent = &rc
+ }
+ // reasoning_details is OpenRouter's format; other vendors reject it.
+ raw, ok := msg.ReasoningMetadata[metadataReasoningDetails]
+ if ok && len(raw) > 0 && s.ThinkingFormat == catalog.ThinkingFormatOpenRouter {
+ wm.ReasoningDetails = raw
+ }
+ }
+ out = append(out, wm)
+ }
+ return out
+}
+
+// contentParts flattens rich content to plain text for vendors that only
+// accept strings (WeKnora Cloud), otherwise returns the parts as-is.
+func (c *Client) contentParts(parts []wirePart) any {
+ if c.cfg.Settings.SupportsMultiContent {
+ return parts
+ }
+ var texts []string
+ for _, p := range parts {
+ if p.Type == "text" && p.Text != "" {
+ texts = append(texts, p.Text)
+ }
+ }
+ return strings.Join(texts, "\n")
+}
+
+const metadataReasoningDetails = "reasoning_details"
+
+// buildBody assembles the request body. It returns a map so vendor-specific
+// top-level fields can be added without a struct per vendor; key order in
+// the encoded JSON is alphabetical, which keeps golden tests stable.
+func (c *Client) buildBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error) {
+ s := c.cfg.Settings
+ body := map[string]any{
+ "model": c.cfg.Endpoint.Model,
+ "messages": c.convertMessages(messages),
+ }
+ if stream {
+ body["stream"] = true
+ if s.SupportsUsageInStreaming {
+ body["stream_options"] = map[string]any{"include_usage": true}
+ }
+ }
+ if s.SupportsStore {
+ body["store"] = false
+ }
+
+ if opts != nil {
+ c.applySampling(body, opts)
+ if budget := opts.CompletionBudget(); budget > 0 {
+ field := s.MaxTokensField
+ if field == "" {
+ field = "max_completion_tokens"
+ }
+ body[field] = budget
+ }
+ c.applyTools(body, opts)
+ if len(opts.Format) > 0 && s.SupportsResponseFormat {
+ body["response_format"] = map[string]any{"type": "json_object"}
+ msgs := body["messages"].([]wireMessage)
+ if len(msgs) > 0 {
+ last := &msgs[len(msgs)-1]
+ if text, ok := last.Content.(string); ok {
+ last.Content = text + fmt.Sprintf("\nUse this JSON schema: %s", opts.Format)
+ }
+ }
+ }
+ if s.PromptCacheKey && api.ResolveCacheRetention(opts) != api.CacheRetentionNone {
+ key := opts.PromptCacheKey
+ if key == "" {
+ key = c.cfg.SessionID
+ }
+ if key = api.ClampPromptCacheKey(key); key != "" {
+ body["prompt_cache_key"] = key
+ if api.ResolveCacheRetention(opts) == api.CacheRetentionLong {
+ body["prompt_cache_retention"] = "24h"
+ }
+ }
+ }
+ }
+ c.applyThinking(body, opts, stream)
+
+ for k, v := range s.ExtraBody {
+ if _, exists := body[k]; !exists {
+ body[k] = v
+ }
+ }
+ return body, nil
+}
+
+func (c *Client) applySampling(body map[string]any, opts *api.Options) {
+ s := c.cfg.Settings
+ if !s.SupportsTemperature {
+ return
+ }
+ if s.FixedTemperature != nil {
+ body["temperature"] = *s.FixedTemperature
+ return
+ }
+ if opts.Temperature > 0 {
+ body["temperature"] = opts.Temperature
+ }
+ if opts.TopP > 0 {
+ body["top_p"] = opts.TopP
+ }
+ if opts.FrequencyPenalty > 0 {
+ body["frequency_penalty"] = opts.FrequencyPenalty
+ }
+ if opts.PresencePenalty > 0 {
+ body["presence_penalty"] = opts.PresencePenalty
+ }
+ if opts.Seed > 0 && s.SupportsSeed {
+ body["seed"] = opts.Seed
+ }
+}
+
+func (c *Client) applyTools(body map[string]any, opts *api.Options) {
+ s := c.cfg.Settings
+ if len(opts.Tools) == 0 {
+ return
+ }
+ tools := make([]map[string]any, 0, len(opts.Tools))
+ for _, tool := range opts.Tools {
+ fn := map[string]any{
+ "name": tool.Function.Name,
+ "description": tool.Function.Description,
+ }
+ if len(tool.Function.Parameters) > 0 {
+ fn["parameters"] = tool.Function.Parameters
+ }
+ tools = append(tools, map[string]any{"type": orDefault(tool.Type, "function"), "function": fn})
+ }
+ body["tools"] = tools
+ if opts.ParallelToolCalls != nil && s.SupportsParallelToolCalls {
+ body["parallel_tool_calls"] = *opts.ParallelToolCalls
+ }
+ if opts.ToolChoice == "" {
+ return
+ }
+ switch opts.ToolChoice {
+ case "none", "required", "auto":
+ if s.AllowsToolChoice(opts.ToolChoice) {
+ body["tool_choice"] = opts.ToolChoice
+ }
+ default:
+ if s.AllowsToolChoice("function") {
+ body["tool_choice"] = map[string]any{
+ "type": "function",
+ "function": map[string]any{"name": opts.ToolChoice},
+ }
+ }
+ }
+}
+
+// applyThinking encodes the requested reasoning level in the vendor's
+// dialect. See catalog.ThinkingFormat for the dialects.
+func (c *Client) applyThinking(body map[string]any, opts *api.Options, stream bool) {
+ s := c.cfg.Settings
+ if s.ThinkingFormat == catalog.ThinkingFormatNone || s.ThinkingFormat == "" {
+ return
+ }
+ levels := c.cfg.ThinkingLevels
+ level, requested := opts.Reasoning()
+ if !requested {
+ if !s.ThinkingAlwaysSend {
+ return
+ }
+ level = api.ReasoningOff
+ }
+ if level.Graded() {
+ level = levels.Clamp(level)
+ }
+ enabled := level.Enabled()
+ if enabled && s.ThinkingDisableOnNonStream && !stream {
+ enabled = false
+ }
+ if !enabled && !levels.Supports(api.ReasoningOff) {
+ // Always-on reasoning model: there is nothing to switch off and the
+ // vendor rejects the attempt.
+ return
+ }
+
+ effort := ""
+ if enabled && level.Graded() && s.SupportsReasoningEffort {
+ effort = levels.Value(level)
+ }
+ effortField := orDefault(s.ReasoningEffortField, "reasoning_effort")
+ if enabled && opts != nil && opts.ThinkingBudgetTokens > 0 && s.ThinkingBudgetField != "" {
+ body[s.ThinkingBudgetField] = opts.ThinkingBudgetTokens
+ }
+
+ switch s.ThinkingFormat {
+ case catalog.ThinkingFormatOpenAI:
+ if enabled {
+ if effort != "" {
+ body[effortField] = effort
+ }
+ } else if v, ok := levels[api.ReasoningOff]; ok && v != nil && *v != "" {
+ body[effortField] = *v
+ }
+ case catalog.ThinkingFormatThinkingType:
+ if enabled {
+ body["thinking"] = map[string]any{"type": orDefault(s.ThinkingEnabledValue, "enabled")}
+ if effort != "" {
+ body[effortField] = effort
+ }
+ } else {
+ body["thinking"] = map[string]any{"type": "disabled"}
+ }
+ case catalog.ThinkingFormatEnableThinking:
+ body["enable_thinking"] = enabled
+ if effort != "" {
+ body[effortField] = effort
+ }
+ case catalog.ThinkingFormatChatTemplateKwargs:
+ body["chat_template_kwargs"] = map[string]any{"enable_thinking": enabled}
+ case catalog.ThinkingFormatOpenRouter:
+ if enabled {
+ reasoning := map[string]any{}
+ if effort != "" {
+ reasoning["effort"] = effort
+ } else {
+ reasoning["enabled"] = true
+ }
+ body["reasoning"] = reasoning
+ } else {
+ body["reasoning"] = map[string]any{"enabled": false}
+ }
+ }
+}
+
+// finalizeBody applies transformations that need the JSON object form
+// (cache_control breakpoints) and returns the bytes to send.
+func (c *Client) finalizeBody(body map[string]any, opts *api.Options) (map[string]any, error) {
+ s := c.cfg.Settings
+ if s.CacheControlFormat != "anthropic" {
+ return body, nil
+ }
+ marker := api.CacheControlFor(api.ResolveCacheRetention(opts), "1h")
+ if marker == nil {
+ return body, nil
+ }
+ data, err := json.Marshal(body)
+ if err != nil {
+ return nil, err
+ }
+ var payload map[string]any
+ if err := json.Unmarshal(data, &payload); err != nil {
+ return nil, err
+ }
+ api.ApplyCacheControlBreakpoints(payload, marker)
+ return payload, nil
+}
+
+// BuildRequestBody is the golden-test entry point: it returns the exact
+// JSON object that would be sent for the given inputs.
+func (c *Client) BuildRequestBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error) {
+ body, err := c.buildBody(messages, opts, stream)
+ if err != nil {
+ return nil, err
+ }
+ return c.finalizeBody(body, opts)
+}
+
+func orDefault(v, def string) string {
+ if v == "" {
+ return def
+ }
+ return v
+}
diff --git a/internal/models/api/openairesponses/client.go b/internal/models/api/openairesponses/client.go
new file mode 100644
index 000000000..39a7a8f03
--- /dev/null
+++ b/internal/models/api/openairesponses/client.go
@@ -0,0 +1,552 @@
+package openairesponses
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+const defaultPath = "/responses"
+
+// Client talks the Responses protocol to one endpoint.
+type Client struct {
+ cfg Config
+}
+
+// New creates a client. The endpoint must already carry auth and headers.
+func New(cfg Config) *Client {
+ if cfg.ThinkingLevels == nil {
+ cfg.ThinkingLevels = api.ThinkingLevelMap{}
+ }
+ return &Client{cfg: cfg}
+}
+
+// GetModelName returns the wire model name.
+func (c *Client) GetModelName() string { return c.cfg.Endpoint.Model }
+
+// GetModelID returns WeKnora's model identifier.
+func (c *Client) GetModelID() string { return c.cfg.Endpoint.ModelID }
+
+// Settings exposes the resolved settings (diagnostics, tests).
+func (c *Client) Settings() Config { return c.cfg }
+
+func (c *Client) url() string { return c.cfg.Endpoint.Resolve(defaultPath) }
+
+func (c *Client) send(
+ ctx context.Context, messages []api.Message, opts *api.Options, stream bool,
+) (*http.Response, []byte, error) {
+ opts = api.WithSessionCacheKey(ctx, opts)
+ body, err := c.BuildRequestBody(messages, opts, stream)
+ if err != nil {
+ return nil, nil, err
+ }
+ url := c.url()
+ req, data, err := c.cfg.Endpoint.NewRequest(ctx, url, body, stream)
+ if err != nil {
+ return nil, nil, err
+ }
+ if c.cfg.Settings.PromptCacheKey {
+ key := c.cfg.SessionID
+ if opts != nil && opts.PromptCacheKey != "" {
+ key = opts.PromptCacheKey
+ }
+ api.AttachSessionAffinityHeaders(req, api.ClampPromptCacheKey(key))
+ }
+ api.LogRequest(ctx, url, c.cfg.Endpoint.Model, data, stream)
+ resp, err := c.cfg.Endpoint.Do(req)
+ if err != nil {
+ return nil, data, err
+ }
+ return resp, data, nil
+}
+
+// Chat performs a non-streaming response creation.
+func (c *Client) Chat(ctx context.Context, messages []api.Message, opts *api.Options) (*types.ChatResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultChatTimeout)
+ defer cancel()
+
+ resp, _, err := c.send(ctx, messages, opts, false)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Request] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, _, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, false)
+ }
+ if err != nil {
+ return nil, fmt.Errorf("create response: %w", err)
+ }
+ }
+ defer func() { _ = resp.Body.Close() }()
+ raw, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return nil, fmt.Errorf("read response: %w", err)
+ }
+ result, err := c.parseResponse(raw)
+ if err != nil {
+ return nil, err
+ }
+ api.LogUsage(ctx, c.cfg.Endpoint.Model, &result.Usage)
+ return result, nil
+}
+
+// ChatStream performs a streaming response creation.
+func (c *Client) ChatStream(
+ ctx context.Context, messages []api.Message, opts *api.Options,
+) (<-chan types.StreamResponse, error) {
+ ctx, cancel := api.WithLLMTimeout(ctx, api.DefaultStreamTimeout)
+
+ resp, data, err := c.send(ctx, messages, opts, true)
+ if err != nil {
+ if api.IsMultimodalNotSupportedError(err) {
+ logger.Warnf(ctx, "[LLM Stream] Model %s does not support multimodal, retrying without images",
+ c.cfg.Endpoint.Model)
+ resp, data, err = c.send(ctx, api.StripImagesFromMessages(messages), opts, true)
+ }
+ if err != nil {
+ cancel()
+ return nil, fmt.Errorf("create response stream: %w", err)
+ }
+ }
+
+ ch := make(chan types.StreamResponse)
+ dumper := api.NewStreamPacketDumper(c.cfg.Endpoint.Model, json.RawMessage(data))
+ if dumper != nil {
+ logger.Infof(ctx, "[LLM Stream Raw Dump] writing packets to %s", dumper.Path())
+ }
+ go func() {
+ defer cancel()
+ defer close(ch)
+ defer func() { _ = resp.Body.Close() }()
+ if dumper != nil {
+ defer dumper.Close()
+ }
+ c.processStream(ctx, resp.Body, ch, dumper)
+ }()
+ return ch, nil
+}
+
+// --- response decoding ---
+
+type rawContentPart struct {
+ Type string `json:"type"`
+ Text string `json:"text"`
+}
+
+// rawOutputItem is the union of the output item shapes this package reads:
+// message, function_call and reasoning.
+type rawOutputItem struct {
+ Type string `json:"type"`
+ ID json.RawMessage `json:"id,omitempty"`
+ Status string `json:"status,omitempty"`
+ Role string `json:"role,omitempty"`
+ Content []rawContentPart `json:"content,omitempty"`
+ CallID string `json:"call_id,omitempty"`
+ Name string `json:"name,omitempty"`
+ Arguments string `json:"arguments,omitempty"`
+ Summary []rawContentPart `json:"summary,omitempty"`
+}
+
+type rawUsage struct {
+ InputTokens int `json:"input_tokens"`
+ OutputTokens int `json:"output_tokens"`
+ TotalTokens int `json:"total_tokens"`
+ InputTokensDetails *struct {
+ CachedTokens int `json:"cached_tokens"`
+ } `json:"input_tokens_details,omitempty"`
+}
+
+func (u rawUsage) toTokenUsage() types.TokenUsage {
+ out := types.TokenUsage{
+ PromptTokens: u.InputTokens,
+ CompletionTokens: u.OutputTokens,
+ TotalTokens: u.TotalTokens,
+ }
+ if out.TotalTokens == 0 {
+ out.TotalTokens = out.PromptTokens + out.CompletionTokens
+ }
+ if u.InputTokensDetails != nil {
+ cached := u.InputTokensDetails.CachedTokens
+ out.SetPromptCacheUsage(cached, 0, max(0, u.InputTokens-cached), true)
+ } else {
+ out.SetPromptCacheUsage(0, 0, 0, false)
+ }
+ return out
+}
+
+type rawError struct {
+ Code any `json:"code,omitempty"`
+ Message string `json:"message"`
+}
+
+type rawResponse struct {
+ ID string `json:"id,omitempty"`
+ Status string `json:"status,omitempty"`
+ IncompleteDetails *struct {
+ Reason string `json:"reason"`
+ } `json:"incomplete_details,omitempty"`
+ Output []json.RawMessage `json:"output,omitempty"`
+ Usage *rawUsage `json:"usage,omitempty"`
+ Error *rawError `json:"error,omitempty"`
+}
+
+// finishReason maps the response status onto the Chat Completions
+// vocabulary the rest of the engine understands.
+func (r *rawResponse) finishReason(hasToolCalls bool) string {
+ if hasToolCalls {
+ return "tool_calls"
+ }
+ if r != nil && r.Status == "incomplete" && r.IncompleteDetails != nil {
+ switch r.IncompleteDetails.Reason {
+ case "max_output_tokens":
+ return "length"
+ case "content_filter":
+ return "content_filter"
+ }
+ }
+ return "stop"
+}
+
+func decodeItem(raw json.RawMessage) (rawOutputItem, error) {
+ var item rawOutputItem
+ if err := json.Unmarshal(raw, &item); err != nil {
+ return rawOutputItem{}, fmt.Errorf("decode output item: %w", err)
+ }
+ return item, nil
+}
+
+// streamItem decodes the item carried by an output_item event. An event that
+// carries no item at all is simply nothing to decode, but an item we cannot
+// read is lost output, possibly a whole function_call, so the caller must
+// surface it instead of moving on.
+func streamItem(raw json.RawMessage) (rawOutputItem, bool, error) {
+ if len(raw) == 0 {
+ return rawOutputItem{}, false, nil
+ }
+ item, err := decodeItem(raw)
+ if err != nil {
+ return rawOutputItem{}, false, err
+ }
+ return item, true, nil
+}
+
+func itemText(item rawOutputItem) string {
+ var b strings.Builder
+ for _, part := range item.Content {
+ if part.Type == "output_text" {
+ b.WriteString(part.Text)
+ }
+ }
+ return b.String()
+}
+
+func itemSummary(item rawOutputItem) string {
+ texts := make([]string, 0, len(item.Summary))
+ for _, part := range item.Summary {
+ if part.Text != "" {
+ texts = append(texts, part.Text)
+ }
+ }
+ return strings.Join(texts, "\n")
+}
+
+func toolCallMetadata(item rawOutputItem) types.ToolCallMetadata {
+ if len(item.ID) == 0 || string(item.ID) == "null" {
+ return nil
+ }
+ return types.ToolCallMetadata{metadataToolCallItemID: item.ID}
+}
+
+func reasoningMetadata(items []json.RawMessage) types.ProviderMetadata {
+ if len(items) == 0 {
+ return nil
+ }
+ merged, err := json.Marshal(items)
+ if err != nil {
+ return nil
+ }
+ return types.ProviderMetadata{metadataReasoningItems: merged}
+}
+
+func (c *Client) parseResponse(raw []byte) (*types.ChatResponse, error) {
+ var env rawResponse
+ if err := json.Unmarshal(raw, &env); err != nil {
+ return nil, fmt.Errorf("decode response: %w", err)
+ }
+ if env.Error != nil && env.Error.Message != "" {
+ return nil, fmt.Errorf("API error: %s", env.Error.Message)
+ }
+ if env.Status == "failed" {
+ return nil, fmt.Errorf("API error: response failed")
+ }
+
+ result := &types.ChatResponse{}
+ var content, reasoning []string
+ var reasoningItems []json.RawMessage
+ for _, rawItem := range env.Output {
+ // An output item we cannot read may be the round's tool call. Dropping
+ // it hands the agent what looks like a plain answer, so fail instead.
+ item, err := decodeItem(rawItem)
+ if err != nil {
+ return nil, err
+ }
+ switch item.Type {
+ case "message":
+ content = append(content, itemText(item))
+ case "function_call":
+ result.ToolCalls = append(result.ToolCalls, types.LLMToolCall{
+ ID: item.CallID,
+ Type: "function",
+ Function: types.FunctionCall{Name: item.Name, Arguments: item.Arguments},
+ ProviderMetadata: toolCallMetadata(item),
+ })
+ case "reasoning":
+ if summary := itemSummary(item); summary != "" {
+ reasoning = append(reasoning, summary)
+ }
+ reasoningItems = append(reasoningItems, rawItem)
+ }
+ }
+ result.Content = strings.Join(content, "")
+ result.ReasoningContent = strings.Join(reasoning, "\n")
+ result.ReasoningMetadata = reasoningMetadata(reasoningItems)
+ result.FinishReason = env.finishReason(len(result.ToolCalls) > 0)
+ // Classify the cache status even without a usage block, so an empty
+ // CacheStatus never reaches the usage dashboards as a silent miss.
+ usage := rawUsage{}
+ if env.Usage != nil {
+ usage = *env.Usage
+ }
+ result.Usage = usage.toTokenUsage()
+ return result, nil
+}
+
+// --- streaming ---
+
+// rawStreamEvent is the union of the fields this package reads from the
+// Responses SSE events. Every event carries "type".
+type rawStreamEvent struct {
+ Type string `json:"type"`
+ Delta string `json:"delta,omitempty"`
+ ItemID string `json:"item_id,omitempty"`
+ OutputIndex int `json:"output_index,omitempty"`
+ SummaryIndex int `json:"summary_index,omitempty"`
+ Item json.RawMessage `json:"item,omitempty"`
+ Response *rawResponse `json:"response,omitempty"`
+ // Message/Code are set on the top-level "error" event.
+ Message string `json:"message,omitempty"`
+ Code any `json:"code,omitempty"`
+}
+
+// streamState tracks the function_call items seen so far so argument deltas
+// can be routed to the assembler index that announced the call.
+type streamState struct {
+ toolIndex map[string]int // item id -> assembler index
+ argsSeen map[string]bool
+ nextToolIndex int
+ reasoningItems []json.RawMessage
+}
+
+func (st *streamState) indexFor(itemID string) int {
+ if idx, ok := st.toolIndex[itemID]; ok {
+ return idx
+ }
+ idx := st.nextToolIndex
+ st.nextToolIndex++
+ st.toolIndex[itemID] = idx
+ return idx
+}
+
+func (c *Client) processStream(
+ ctx context.Context, body io.Reader, ch chan<- types.StreamResponse, dumper *api.StreamPacketDumper,
+) {
+ assembler := api.NewStreamAssembler(ctx, c.cfg.Endpoint.Model)
+ reader := api.NewSSEReader(body)
+ st := &streamState{toolIndex: map[string]int{}, argsSeen: map[string]bool{}}
+
+ finish := func() {
+ assembler.ReasoningMetadata = reasoningMetadata(st.reasoningItems)
+ assembler.End(ch)
+ }
+
+ for {
+ // The consumer went away (client disconnect, aborted agent turn): stop
+ // decoding a stream nobody will read instead of spinning to EOF.
+ if assembler.Aborted() {
+ return
+ }
+ event, err := reader.ReadEvent()
+ if err != nil {
+ if err == io.EOF {
+ finish()
+ } else {
+ assembler.Fail(ch, err)
+ }
+ return
+ }
+ if event == nil {
+ continue
+ }
+ if event.Done {
+ finish()
+ return
+ }
+ if len(event.Data) == 0 {
+ continue
+ }
+ if dumper != nil {
+ raw := make([]byte, len(event.Data))
+ copy(raw, event.Data)
+ dumper.WritePacketRaw(raw)
+ }
+
+ var ev rawStreamEvent
+ if err := json.Unmarshal(event.Data, &ev); err != nil {
+ // An event whose *type* we do not know is routine and the switch
+ // below already ignores it. A payload that is not JSON at all is
+ // not: it is a truncated frame or a gateway error page, i.e. a
+ // hole in the answer. Skipping it runs the loop to EOF, which the
+ // caller cannot tell from a complete reply and then stores as the
+ // model's answer. Fail, as the Completions loop does.
+ assembler.Fail(ch, fmt.Errorf("decode stream chunk: %w", err))
+ return
+ }
+
+ switch ev.Type {
+ case "response.output_text.delta":
+ if ev.Delta != "" {
+ assembler.Process(ch, api.Delta{Content: ev.Delta})
+ }
+ case "response.reasoning_summary_text.delta", "response.reasoning_text.delta":
+ if ev.Delta != "" {
+ assembler.Process(ch, api.Delta{Reasoning: ev.Delta})
+ }
+ case "response.reasoning_summary_part.added":
+ // Mirror the non-stream join of summary parts with a newline.
+ if ev.SummaryIndex > 0 {
+ assembler.Process(ch, api.Delta{Reasoning: "\n"})
+ }
+ case "response.output_item.added":
+ item, ok, err := streamItem(ev.Item)
+ if err != nil {
+ assembler.Fail(ch, err)
+ return
+ }
+ if !ok || item.Type != "function_call" {
+ continue
+ }
+ itemID := streamItemID(item, ev.OutputIndex)
+ idx := st.indexFor(itemID)
+ assembler.Process(ch, api.Delta{ToolCalls: []api.ToolCallDelta{{
+ Index: idx, ID: item.CallID, Type: "function", Name: item.Name,
+ }}})
+ assembler.SetToolCallMetadata(idx, toolCallMetadata(item))
+ case "response.function_call_arguments.delta":
+ if ev.Delta == "" {
+ continue
+ }
+ // Correlate on the same key output_item.added registered. Vendors
+ // that omit item ids would otherwise send every call's arguments
+ // to the single index keyed by "", merging distinct tool calls.
+ key := streamEventKey(ev.ItemID, ev.OutputIndex)
+ st.argsSeen[key] = true
+ assembler.Process(ch, api.Delta{ToolCalls: []api.ToolCallDelta{{
+ Index: st.indexFor(key), Arguments: ev.Delta,
+ }}})
+ case "response.output_item.done":
+ item, ok, err := streamItem(ev.Item)
+ if err != nil {
+ assembler.Fail(ch, err)
+ return
+ }
+ if !ok {
+ continue
+ }
+ switch item.Type {
+ case "reasoning":
+ st.reasoningItems = append(st.reasoningItems, ev.Item)
+ case "function_call":
+ // Providers that never stream argument deltas deliver the
+ // arguments only on the done item.
+ itemID := streamItemID(item, ev.OutputIndex)
+ if !st.argsSeen[itemID] && item.Arguments != "" {
+ st.argsSeen[itemID] = true
+ assembler.Process(ch, api.Delta{ToolCalls: []api.ToolCallDelta{{
+ Index: st.indexFor(itemID), ID: item.CallID, Type: "function",
+ Name: item.Name, Arguments: item.Arguments,
+ }}})
+ assembler.SetToolCallMetadata(st.indexFor(itemID), toolCallMetadata(item))
+ }
+ }
+ case "response.completed", "response.incomplete":
+ c.completeStream(ch, assembler, st, ev.Response, ev.Type == "response.incomplete")
+ return
+ case "response.failed":
+ msg := "response failed"
+ if ev.Response != nil && ev.Response.Error != nil && ev.Response.Error.Message != "" {
+ msg = ev.Response.Error.Message
+ }
+ assembler.Fail(ch, fmt.Errorf("API stream error: %s", msg))
+ return
+ case "error":
+ assembler.Fail(ch, fmt.Errorf("API stream error: %s", orDefault(ev.Message, "unknown error")))
+ return
+ }
+ }
+}
+
+// streamItemID returns the item id used to correlate added/delta/done
+// events, falling back to the output index when the vendor omits ids.
+func streamItemID(item rawOutputItem, outputIndex int) string {
+ var id string
+ if len(item.ID) > 0 {
+ _ = json.Unmarshal(item.ID, &id)
+ }
+ return streamEventKey(id, outputIndex)
+}
+
+// streamEventKey is the correlation key for one output item: its id when the
+// vendor sends one, otherwise its position in the output list.
+func streamEventKey(itemID string, outputIndex int) string {
+ if itemID != "" {
+ return itemID
+ }
+ return fmt.Sprintf("output_index:%d", outputIndex)
+}
+
+// completeStream handles the terminal response.completed / response.incomplete
+// event: usage, finish reason, reasoning artifacts and the closing chunks.
+func (c *Client) completeStream(
+ ch chan<- types.StreamResponse, assembler *api.StreamAssembler, st *streamState, resp *rawResponse, incomplete bool,
+) {
+ if resp != nil {
+ if resp.Usage != nil {
+ assembler.SetUsage(resp.Usage.toTokenUsage())
+ }
+ // Fall back to the final response body for reasoning items when the
+ // vendor never emitted output_item.done for them.
+ if len(st.reasoningItems) == 0 {
+ for _, rawItem := range resp.Output {
+ // Tolerated on purpose, unlike the item events above: the
+ // deltas already carried the answer and its tool calls, so an
+ // unreadable item here costs at most a reasoning artifact.
+ if item, err := decodeItem(rawItem); err == nil && item.Type == "reasoning" {
+ st.reasoningItems = append(st.reasoningItems, rawItem)
+ }
+ }
+ }
+ }
+ finishReason := resp.finishReason(assembler.ToolCallCount() > 0)
+ if incomplete && finishReason == "stop" {
+ finishReason = "length"
+ }
+ assembler.Process(ch, api.Delta{FinishReason: finishReason})
+ assembler.ReasoningMetadata = reasoningMetadata(st.reasoningItems)
+ assembler.End(ch)
+}
diff --git a/internal/models/api/openairesponses/openairesponses_test.go b/internal/models/api/openairesponses/openairesponses_test.go
new file mode 100644
index 000000000..97908f553
--- /dev/null
+++ b/internal/models/api/openairesponses/openairesponses_test.go
@@ -0,0 +1,677 @@
+package openairesponses
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+func newTestClient(t *testing.T, server *httptest.Server, reasoning bool) *Client {
+ t.Helper()
+ ep := api.Endpoint{
+ Model: "gpt-5",
+ ModelID: "model-1",
+ Auth: api.BearerAuth("sk-test"),
+ }
+ if server != nil {
+ ep.BaseURL = server.URL
+ ep.Client = server.Client()
+ } else {
+ ep.BaseURL = "https://api.openai.com/v1"
+ }
+ return New(Config{
+ Endpoint: ep,
+ Settings: catalog.DefaultOpenAIResponses(),
+ Reasoning: reasoning,
+ SessionID: "session-fallback",
+ })
+}
+
+// roundTrip marshals and re-decodes the body so struct-typed values compare
+// as plain JSON.
+func roundTrip(t *testing.T, body map[string]any) map[string]any {
+ t.Helper()
+ data, err := json.Marshal(body)
+ if err != nil {
+ t.Fatalf("marshal body: %v", err)
+ }
+ var out map[string]any
+ if err := json.Unmarshal(data, &out); err != nil {
+ t.Fatalf("unmarshal body: %v", err)
+ }
+ return out
+}
+
+func conversation() []api.Message {
+ return []api.Message{
+ {Role: "system", Content: "You are a weather assistant."},
+ {Role: "user", Content: "What's the weather in Paris?"},
+ {
+ Role: "assistant",
+ ToolCalls: []api.ToolCall{{
+ ID: "call_1",
+ Type: "function",
+ Function: api.FunctionCall{
+ Name: "get_weather",
+ Arguments: `{"city":"Paris"}`,
+ },
+ ProviderMetadata: types.ToolCallMetadata{
+ "openai_responses_item_id": json.RawMessage(`"fc_1"`),
+ },
+ }},
+ ReasoningMetadata: types.ProviderMetadata{
+ "openai_responses_reasoning": json.RawMessage(
+ `[{"type":"reasoning","id":"rs_1","summary":[],"encrypted_content":"enc-abc"}]`),
+ },
+ },
+ {Role: "tool", ToolCallID: "call_1", Name: "get_weather", Content: "Sunny, 24C"},
+ }
+}
+
+func TestBuildRequestBodyGolden(t *testing.T) {
+ c := newTestClient(t, nil, true)
+ opts := &api.Options{
+ Temperature: 0.7,
+ MaxCompletionTokens: 1000,
+ ReasoningEffort: api.ReasoningHigh,
+ PromptCacheKey: "cache-key-1",
+ Tools: []api.Tool{{
+ Type: "function",
+ Function: api.FunctionDef{
+ Name: "get_weather",
+ Description: "Get weather",
+ Parameters: json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}}}`),
+ },
+ }},
+ ToolChoice: "auto",
+ }
+ body, err := c.BuildRequestBody(conversation(), opts, false)
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ got := roundTrip(t, body)
+
+ want := map[string]any{
+ "model": "gpt-5",
+ "store": false,
+ "instructions": "You are a weather assistant.",
+ "input": []any{
+ map[string]any{"type": "message", "role": "user", "content": "What's the weather in Paris?"},
+ map[string]any{"type": "reasoning", "id": "rs_1", "summary": []any{}, "encrypted_content": "enc-abc"},
+ map[string]any{
+ "type": "function_call", "id": "fc_1", "call_id": "call_1",
+ "name": "get_weather", "arguments": `{"city":"Paris"}`,
+ },
+ map[string]any{"type": "function_call_output", "call_id": "call_1", "output": "Sunny, 24C"},
+ },
+ "max_output_tokens": float64(1000),
+ "tools": []any{
+ map[string]any{
+ "type": "function",
+ "name": "get_weather",
+ "description": "Get weather",
+ "parameters": map[string]any{
+ "type": "object", "properties": map[string]any{"city": map[string]any{"type": "string"}},
+ },
+ },
+ },
+ "tool_choice": "auto",
+ "reasoning": map[string]any{"effort": "high", "summary": "auto"},
+ "include": []any{"reasoning.encrypted_content"},
+ "prompt_cache_key": "cache-key-1",
+ }
+ wantJSON, _ := json.Marshal(want)
+ gotJSON, _ := json.Marshal(got)
+ if string(wantJSON) != string(gotJSON) {
+ t.Fatalf("body mismatch\n got: %s\nwant: %s", gotJSON, wantJSON)
+ }
+ for _, absent := range []string{"temperature", "stream", "messages", "frequency_penalty", "presence_penalty"} {
+ if _, ok := got[absent]; ok {
+ t.Errorf("unexpected key %q in body", absent)
+ }
+ }
+}
+
+func TestBuildRequestBodyNonReasoningStream(t *testing.T) {
+ c := newTestClient(t, nil, false)
+ c.cfg.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningOff: api.StringPtr("none")}
+ off := false
+ opts := &api.Options{
+ Temperature: 0.3,
+ TopP: 0.9,
+ Thinking: &off,
+ CacheRetention: api.CacheRetentionLong,
+ MaxTokens: 4,
+ Format: json.RawMessage(`{"type":"object"}`),
+ }
+ body, err := c.BuildRequestBody([]api.Message{{Role: "user", Content: "hi"}}, opts, true)
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ got := roundTrip(t, body)
+
+ if got["stream"] != true {
+ t.Errorf("stream = %v, want true", got["stream"])
+ }
+ if got["temperature"] != 0.3 || got["top_p"] != 0.9 {
+ t.Errorf("sampling = %v / %v", got["temperature"], got["top_p"])
+ }
+ if got["max_output_tokens"] != float64(16) {
+ t.Errorf("max_output_tokens = %v, want 16 (minimum)", got["max_output_tokens"])
+ }
+ if got["prompt_cache_key"] != "session-fallback" {
+ t.Errorf("prompt_cache_key = %v", got["prompt_cache_key"])
+ }
+ if got["prompt_cache_retention"] != "24h" {
+ t.Errorf("prompt_cache_retention = %v", got["prompt_cache_retention"])
+ }
+ if _, ok := got["include"]; ok {
+ t.Errorf("include must not be sent for non-reasoning models")
+ }
+ reasoning, _ := got["reasoning"].(map[string]any)
+ if reasoning["effort"] != "none" {
+ t.Errorf("reasoning = %v, want effort none", got["reasoning"])
+ }
+ text, _ := got["text"].(map[string]any)
+ format, _ := text["format"].(map[string]any)
+ if format["type"] != "json_object" {
+ t.Errorf("text.format = %v", got["text"])
+ }
+ input, _ := got["input"].([]any)
+ if len(input) != 1 {
+ t.Fatalf("input = %v", got["input"])
+ }
+ msg := input[0].(map[string]any)
+ if content, _ := msg["content"].(string); !strings.HasSuffix(content, `Use this JSON schema: {"type":"object"}`) {
+ t.Errorf("schema hint not appended: %q", content)
+ }
+}
+
+func TestBuildRequestBodyOffWithoutMapping(t *testing.T) {
+ c := newTestClient(t, nil, false)
+ off := false
+ body, err := c.BuildRequestBody([]api.Message{{Role: "user", Content: "hi"}}, &api.Options{Thinking: &off}, false)
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ if _, ok := body["reasoning"]; ok {
+ t.Fatalf("reasoning must be omitted when off has no vendor value: %v", body["reasoning"])
+ }
+}
+
+func TestBuildRequestBodyImagesAndAuto(t *testing.T) {
+ c := newTestClient(t, nil, true)
+ on := true
+ msgs := []api.Message{{
+ Role: "user",
+ MultiContent: []api.MessageContentPart{
+ {Type: "text", Text: "Describe"},
+ {Type: "image_url", ImageURL: &api.ImageURL{URL: "https://example.com/a.png"}},
+ },
+ }}
+ body, err := c.BuildRequestBody(msgs, &api.Options{Thinking: &on}, false)
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ got := roundTrip(t, body)
+ input := got["input"].([]any)
+ parts := input[0].(map[string]any)["content"].([]any)
+ if len(parts) != 2 {
+ t.Fatalf("parts = %v", parts)
+ }
+ img := parts[1].(map[string]any)
+ if img["type"] != "input_image" || img["image_url"] != "https://example.com/a.png" || img["detail"] != "auto" {
+ t.Errorf("image part = %v", img)
+ }
+ reasoning := got["reasoning"].(map[string]any)
+ if _, ok := reasoning["effort"]; ok {
+ t.Errorf("auto must not send effort: %v", reasoning)
+ }
+ if reasoning["summary"] != "auto" {
+ t.Errorf("reasoning summary = %v", reasoning)
+ }
+}
+
+func TestChatDecodesResponse(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ var gotPath string
+ var gotHeaders http.Header
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ gotHeaders = r.Header.Clone()
+ _, _ = io.ReadAll(r.Body)
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{
+ "id": "resp_1",
+ "status": "completed",
+ "output": [
+ {"type":"reasoning","id":"rs_1","summary":[{"type":"summary_text","text":"Think A"},
+ {"type":"summary_text","text":"Think B"}],"encrypted_content":"enc"},
+ {"type":"message","id":"msg_1","role":"assistant","status":"completed",
+ "content":[{"type":"output_text","text":"Hello "},{"type":"output_text","text":"world"}]},
+ {"type":"function_call","id":"fc_1","call_id":"call_1","name":"get_weather",
+ "arguments":"{\"city\":\"Paris\"}","status":"completed"}
+ ],
+ "usage": {"input_tokens": 100, "output_tokens": 20, "total_tokens": 120,
+ "input_tokens_details": {"cached_tokens": 60}}
+ }`))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, true)
+ resp, err := c.Chat(
+ context.Background(),
+ []api.Message{{Role: "user", Content: "hi"}},
+ &api.Options{PromptCacheKey: "k1"},
+ )
+ if err != nil {
+ t.Fatalf("Chat: %v", err)
+ }
+ if gotPath != "/responses" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotHeaders.Get("Authorization") != "Bearer sk-test" {
+ t.Errorf("auth header = %q", gotHeaders.Get("Authorization"))
+ }
+ if gotHeaders.Get("x-session-affinity") != "k1" {
+ t.Errorf("affinity header = %q", gotHeaders.Get("x-session-affinity"))
+ }
+ if resp.Content != "Hello world" {
+ t.Errorf("content = %q", resp.Content)
+ }
+ if resp.ReasoningContent != "Think A\nThink B" {
+ t.Errorf("reasoning = %q", resp.ReasoningContent)
+ }
+ if resp.FinishReason != "tool_calls" {
+ t.Errorf("finish = %q", resp.FinishReason)
+ }
+ if len(resp.ToolCalls) != 1 {
+ t.Fatalf("tool calls = %+v", resp.ToolCalls)
+ }
+ tc := resp.ToolCalls[0]
+ if tc.ID != "call_1" || tc.Type != "function" || tc.Function.Name != "get_weather" ||
+ tc.Function.Arguments != `{"city":"Paris"}` {
+ t.Errorf("tool call = %+v", tc)
+ }
+ if string(tc.ProviderMetadata["openai_responses_item_id"]) != `"fc_1"` {
+ t.Errorf("item id metadata = %s", tc.ProviderMetadata["openai_responses_item_id"])
+ }
+ var items []map[string]any
+ if err := json.Unmarshal(resp.ReasoningMetadata["openai_responses_reasoning"], &items); err != nil {
+ t.Fatalf("reasoning metadata: %v", err)
+ }
+ if len(items) != 1 || items[0]["id"] != "rs_1" || items[0]["encrypted_content"] != "enc" {
+ t.Errorf("reasoning items = %v", items)
+ }
+ u := resp.Usage
+ if u.PromptTokens != 100 || u.CompletionTokens != 20 || u.TotalTokens != 120 {
+ t.Errorf("usage = %+v", u)
+ }
+ if u.CacheReadTokens != 60 || u.CacheMissTokens != 40 || !u.CacheReported ||
+ u.CacheStatus != types.PromptCacheStatusHit {
+ t.Errorf("cache usage = %+v", u)
+ }
+}
+
+func TestChatIncompleteAndError(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ payload := `{"status":"incomplete","incomplete_details":{"reason":"max_output_tokens"},"output":` +
+ `[{"type":"message","content":[{"type":"output_text","text":"partial"}]}],` +
+ `"usage":{"input_tokens":1,"output_tokens":2}}`
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ _, _ = w.Write([]byte(payload))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, false)
+ resp, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("Chat: %v", err)
+ }
+ if resp.FinishReason != "length" || resp.Content != "partial" {
+ t.Errorf("resp = %+v", resp)
+ }
+ if resp.Usage.TotalTokens != 3 || resp.Usage.CacheReported ||
+ resp.Usage.CacheStatus != types.PromptCacheStatusUnreported {
+ t.Errorf("usage = %+v", resp.Usage)
+ }
+
+ payload = `{"error":{"type":"invalid_request_error","message":"bad model"}}`
+ _, err = c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err == nil || !strings.Contains(err.Error(), "bad model") {
+ t.Fatalf("expected API error, got %v", err)
+ }
+}
+
+func sseBody(events ...string) string {
+ var b strings.Builder
+ for _, ev := range events {
+ var probe struct {
+ Type string `json:"type"`
+ }
+ _ = json.Unmarshal([]byte(ev), &probe)
+ fmt.Fprintf(&b, "event: %s\ndata: %s\n\n", probe.Type, ev)
+ }
+ return b.String()
+}
+
+func TestChatStreamAssemblesToolCall(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ body := sseBody(
+ `{"type":"response.created","response":{"id":"resp_1","status":"in_progress"}}`,
+ `{"type":"response.output_item.added","output_index":0,"item":{"type":"reasoning","id":"rs_1","summary":[]}}`,
+ `{"type":"response.reasoning_summary_text.delta",`+
+ `"item_id":"rs_1","output_index":0,"summary_index":0,"delta":"thinking..."}`,
+ `{"type":"response.output_item.done","output_index":0,"item":{"type":"reasoning",`+
+ `"id":"rs_1","summary":[{"type":"summary_text","text":"thinking..."}],"encrypted_content":"enc"}}`,
+ `{"type":"response.output_item.added","output_index":1,`+
+ `"item":{"type":"message","id":"msg_1","role":"assistant","content":[]}}`,
+ `{"type":"response.output_text.delta","item_id":"msg_1","output_index":1,"delta":"Hello"}`,
+ `{"type":"response.output_text.delta","item_id":"msg_1","output_index":1,"delta":" world"}`,
+ `{"type":"response.output_item.done","output_index":1,"item":{"type":"message",`+
+ `"id":"msg_1","role":"assistant","content":[{"type":"output_text","text":"Hello world"}]}}`,
+ `{"type":"response.output_item.added","output_index":2,"item":{"type":"function_call",`+
+ `"id":"fc_1","call_id":"call_1","name":"get_weather","arguments":""}}`,
+ `{"type":"response.function_call_arguments.delta","item_id":"fc_1","output_index":2,"delta":"{\"city\":"}`,
+ `{"type":"response.function_call_arguments.delta","item_id":"fc_1","output_index":2,"delta":"\"Paris\"}"}`,
+ `{"type":"response.function_call_arguments.done",`+
+ `"item_id":"fc_1","output_index":2,"arguments":"{\"city\":\"Paris\"}"}`,
+ `{"type":"response.output_item.done","output_index":2,"item":{"type":"function_call","id":"fc_1","call_id":`+
+ `"call_1","name":"get_weather","arguments":"{\"city\":\"Paris\"}","status":"completed"}}`,
+ `{"type":"response.completed","response":{"id":"resp_1","status":"completed","output":[],"usage":{"input_to`+
+ `kens":50,"output_tokens":10,"total_tokens":60,"input_tokens_details":{"cached_tokens":0}}}}`,
+ )
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ raw, _ := io.ReadAll(r.Body)
+ var req map[string]any
+ if err := json.Unmarshal(raw, &req); err != nil || req["stream"] != true {
+ w.WriteHeader(http.StatusBadRequest)
+ return
+ }
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(body))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, true)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var events []types.StreamResponse
+ for ev := range ch {
+ events = append(events, ev)
+ }
+ if len(events) == 0 {
+ t.Fatal("no events")
+ }
+
+ var thinking, answer string
+ var sawToolCallEvent, sawThinkingDone bool
+ for _, ev := range events {
+ switch ev.ResponseType {
+ case types.ResponseTypeThinking:
+ if ev.Done {
+ sawThinkingDone = true
+ } else {
+ thinking += ev.Content
+ }
+ case types.ResponseTypeAnswer:
+ answer += ev.Content
+ case types.ResponseTypeToolCall:
+ sawToolCallEvent = true
+ if ev.Data["tool_name"] != "get_weather" || ev.Data["tool_call_id"] != "call_1" {
+ t.Errorf("tool call event data = %v", ev.Data)
+ }
+ case types.ResponseTypeError:
+ t.Fatalf("unexpected error event: %s", ev.Content)
+ }
+ }
+ if thinking != "thinking..." || !sawThinkingDone {
+ t.Errorf("thinking = %q done=%t", thinking, sawThinkingDone)
+ }
+ if answer != "Hello world" {
+ t.Errorf("answer = %q", answer)
+ }
+ if !sawToolCallEvent {
+ t.Error("missing ResponseTypeToolCall event")
+ }
+
+ final := events[len(events)-1]
+ if final.ResponseType != types.ResponseTypeAnswer || !final.Done {
+ t.Fatalf("final event = %+v", final)
+ }
+ if final.Usage == nil || final.Usage.PromptTokens != 50 || final.Usage.CompletionTokens != 10 ||
+ final.Usage.TotalTokens != 60 || !final.Usage.CacheReported {
+ t.Errorf("final usage = %+v", final.Usage)
+ }
+ if final.FinishReason != "tool_calls" {
+ t.Errorf("final finish = %q", final.FinishReason)
+ }
+ if len(final.ToolCalls) != 1 {
+ t.Fatalf("final tool calls = %+v", final.ToolCalls)
+ }
+ tc := final.ToolCalls[0]
+ if tc.ID != "call_1" || tc.Type != "function" || tc.Function.Name != "get_weather" ||
+ tc.Function.Arguments != `{"city":"Paris"}` {
+ t.Errorf("assembled tool call = %+v", tc)
+ }
+ if string(tc.ProviderMetadata["openai_responses_item_id"]) != `"fc_1"` {
+ t.Errorf("item id metadata = %s", tc.ProviderMetadata["openai_responses_item_id"])
+ }
+ md, _ := final.Data["reasoning_metadata"].(types.ProviderMetadata)
+ var items []map[string]any
+ err = json.Unmarshal(md["openai_responses_reasoning"], &items)
+ if err != nil || len(items) != 1 || items[0]["encrypted_content"] != "enc" {
+ t.Errorf("reasoning metadata = %v (err %v)", final.Data, err)
+ }
+}
+
+func TestChatStreamFailedEvent(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ body := sseBody(
+ `{"type":"response.output_text.delta","delta":"partial"}`,
+ `{"type":"response.failed","response":{"status":"failed","error":{"code":"server_error","message":"boom"}}}`,
+ )
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ _, _ = w.Write([]byte(body))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, false)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var last types.StreamResponse
+ for ev := range ch {
+ last = ev
+ }
+ if last.ResponseType != types.ResponseTypeError || !strings.Contains(last.Content, "boom") ||
+ last.FinishReason != types.FinishReasonIncomplete {
+ t.Fatalf("last event = %+v", last)
+ }
+}
+
+func TestOffLevelMapsToNone(t *testing.T) {
+ c := newTestClient(t, nil, true)
+ c.cfg.ThinkingLevels = api.ThinkingLevelMap{api.ReasoningOff: api.StringPtr("none")}
+ body, err := c.BuildRequestBody(
+ []api.Message{{Role: "user", Content: "hi"}},
+ &api.Options{ReasoningEffort: api.ReasoningOff},
+ false,
+ )
+ if err != nil {
+ t.Fatalf("BuildRequestBody: %v", err)
+ }
+ reasoning, _ := body["reasoning"].(map[string]any)
+ if reasoning["effort"] != "none" {
+ t.Fatalf("reasoning = %v, want effort none", body["reasoning"])
+ }
+ if _, ok := reasoning["summary"]; ok {
+ t.Errorf("summary must not accompany an off request: %v", reasoning)
+ }
+}
+
+// Gateways that implement the Responses protocol without item ids exist.
+// Correlating argument deltas by item_id alone routed every call's arguments
+// to the single index keyed by "", merging two distinct tool calls into one
+// and leaving the other with an empty argument string.
+func TestChatStreamCorrelatesToolCallsWithoutItemIDs(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ body := sseBody(
+ `{"type":"response.output_item.added","output_index":0,`+
+ `"item":{"type":"function_call","call_id":"call_a","name":"alpha","arguments":""}}`,
+ `{"type":"response.function_call_arguments.delta","output_index":0,"delta":"{\"a\":1}"}`,
+ `{"type":"response.output_item.added","output_index":1,`+
+ `"item":{"type":"function_call","call_id":"call_b","name":"beta","arguments":""}}`,
+ `{"type":"response.function_call_arguments.delta","output_index":1,"delta":"{\"b\":2}"}`,
+ `{"type":"response.completed","response":{"id":"resp_1","status":"completed","output":[]}}`,
+ )
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(body))
+ }))
+ defer server.Close()
+
+ client := newTestClient(t, server, true)
+ ch, err := client.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var last types.StreamResponse
+ for chunk := range ch {
+ if chunk.ResponseType == types.ResponseTypeError {
+ t.Fatalf("unexpected error chunk: %s", chunk.Content)
+ }
+ if chunk.Done && chunk.ResponseType == types.ResponseTypeAnswer {
+ last = chunk
+ }
+ }
+ if len(last.ToolCalls) != 2 {
+ t.Fatalf("tool calls = %d (%#v), want 2", len(last.ToolCalls), last.ToolCalls)
+ }
+ want := []struct{ id, name, args string }{
+ {"call_a", "alpha", `{"a":1}`},
+ {"call_b", "beta", `{"b":2}`},
+ }
+ for i, w := range want {
+ got := last.ToolCalls[i]
+ if got.ID != w.id || got.Function.Name != w.name || got.Function.Arguments != w.args {
+ t.Fatalf("tool call %d = %+v, want id=%s name=%s args=%s", i, got, w.id, w.name, w.args)
+ }
+ }
+}
+
+// Responses is an event-typed protocol, so an event whose *type* we do not
+// know is routine and the switch ignores it. A payload that is not JSON at
+// all is a different animal: a truncated frame or a gateway error page.
+// Skipping it ran the loop to EOF, which reached the caller as a complete
+// answer and got stored as the model's reply.
+func TestChatStreamUndecodableEventFailsTheStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ body := sseBody(
+ `{"type":"response.output_text.delta","item_id":"msg_1","output_index":0,"delta":"Hel"}`,
+ // An unknown but well-formed event type stays harmless.
+ `{"type":"response.web_search_call.in_progress","item_id":"ws_1","output_index":1}`,
+ ) + "event: response.output_text.delta\ndata: <html>502 Bad Gateway</html>\n\n" +
+ sseBody(
+ `{"type":"response.output_text.delta","item_id":"msg_1","output_index":0,"delta":"lo"}`,
+ `{"type":"response.completed","response":{"id":"resp_1","status":"completed","output":[]}}`,
+ )
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(body))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, false)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var answer string
+ var sawError bool
+ for ev := range ch {
+ if ev.ResponseType == types.ResponseTypeError {
+ sawError = true
+ if !strings.Contains(ev.Content, "decode stream chunk") {
+ t.Errorf("error content = %q", ev.Content)
+ }
+ continue
+ }
+ answer += ev.Content
+ }
+ if !sawError {
+ t.Error("a truncated stream must surface as an error, not as a short answer")
+ }
+ if answer != "Hel" {
+ t.Errorf("answer = %q, decoding must stop at the bad frame", answer)
+ }
+}
+
+// An output item that will not decode may be the round's function_call.
+// Dropping it hands the agent a plain answer with nothing to act on.
+func TestChatMalformedOutputItemIsAnError(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"id":"resp_1","status":"completed","output":[` +
+ `{"type":"message","id":"msg_1","role":"assistant",` +
+ `"content":[{"type":"output_text","text":"done"}]},` +
+ `{"type":"function_call","id":"fc_1","call_id":"call_1","name":{"broken":true}}]}`))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, false)
+ _, err := c.Chat(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err == nil || !strings.Contains(err.Error(), "decode output item") {
+ t.Fatalf("expected a decode error, got %v", err)
+ }
+}
+
+// The streaming counterpart: an item event we cannot read fails the round
+// instead of letting the tool call disappear from it.
+func TestChatStreamMalformedOutputItemFailsTheStream(t *testing.T) {
+ t.Setenv("SSRF_WHITELIST", "127.0.0.1")
+ body := sseBody(
+ `{"type":"response.output_text.delta","item_id":"msg_1","output_index":0,"delta":"ok"}`,
+ `{"type":"response.output_item.added","output_index":1,`+
+ `"item":{"type":"function_call","id":"fc_1","call_id":"call_1","name":{"broken":true}}}`,
+ `{"type":"response.completed","response":{"id":"resp_1","status":"completed","output":[]}}`,
+ )
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = w.Write([]byte(body))
+ }))
+ defer server.Close()
+
+ c := newTestClient(t, server, false)
+ ch, err := c.ChatStream(context.Background(), []api.Message{{Role: "user", Content: "hi"}}, nil)
+ if err != nil {
+ t.Fatalf("ChatStream: %v", err)
+ }
+ var last types.StreamResponse
+ var answer string
+ for ev := range ch {
+ if ev.ResponseType != types.ResponseTypeError {
+ answer += ev.Content
+ }
+ last = ev
+ }
+ if last.ResponseType != types.ResponseTypeError || !strings.Contains(last.Content, "decode output item") {
+ t.Fatalf("last event = %+v", last)
+ }
+ if answer != "ok" {
+ t.Errorf("answer = %q, decoding must stop at the bad item", answer)
+ }
+}
diff --git a/internal/models/api/openairesponses/request.go b/internal/models/api/openairesponses/request.go
new file mode 100644
index 000000000..aaf8cd802
--- /dev/null
+++ b/internal/models/api/openairesponses/request.go
@@ -0,0 +1,349 @@
+// Package openairesponses implements the OpenAI Responses wire protocol
+// (POST /responses). Every vendor-specific deviation is driven by
+// catalog.OpenAIResponsesSettings; this package contains no vendor names.
+package openairesponses
+
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+)
+
+// Config is everything the client needs, already resolved by the catalog.
+type Config struct {
+ Endpoint api.Endpoint
+ Settings catalog.OpenAIResponsesSettings
+ // ThinkingLevels maps neutral levels to the vendor vocabulary.
+ ThinkingLevels api.ThinkingLevelMap
+ // Reasoning marks a reasoning model: sampling parameters are dropped and
+ // encrypted reasoning items are requested where the vendor supports them.
+ Reasoning bool
+ // SessionID feeds prompt_cache_key when the caller sets none.
+ SessionID string
+}
+
+const (
+ // metadataReasoningItems is the ReasoningMetadata key carrying the raw
+ // reasoning output items (JSON array) so they can be replayed verbatim on
+ // the next turn.
+ metadataReasoningItems = "openai_responses_reasoning"
+ // metadataToolCallItemID is the ToolCallMetadata key carrying the
+ // function_call item id (raw JSON string) so replayed calls keep it.
+ metadataToolCallItemID = "openai_responses_item_id"
+
+ minMaxOutputTokens = 16
+)
+
+// --- input items ---
+
+type inputMessage struct {
+ Type string `json:"type"`
+ Role string `json:"role"`
+ Content any `json:"content"`
+}
+
+type inputPart struct {
+ Type string `json:"type"`
+ Text string `json:"text,omitempty"`
+ ImageURL string `json:"image_url,omitempty"`
+ Detail string `json:"detail,omitempty"`
+}
+
+type functionCallItem struct {
+ Type string `json:"type"`
+ ID json.RawMessage `json:"id,omitempty"`
+ CallID string `json:"call_id"`
+ Name string `json:"name"`
+ Arguments string `json:"arguments"`
+}
+
+type functionCallOutputItem struct {
+ Type string `json:"type"`
+ CallID string `json:"call_id"`
+ Output string `json:"output"`
+}
+
+// convertMessages splits neutral messages into the instructions string and
+// the ordered input item list.
+func (c *Client) convertMessages(messages []api.Message) (string, []any) {
+ var instructions []string
+ items := make([]any, 0, len(messages))
+ for _, msg := range messages {
+ msg = api.NeutralizeMessageSpecialTokens(msg)
+ switch msg.Role {
+ case "system":
+ if msg.Content != "" {
+ instructions = append(instructions, msg.Content)
+ }
+ case "assistant":
+ items = append(items, c.assistantItems(msg)...)
+ case "tool":
+ items = append(items, functionCallOutputItem{
+ Type: "function_call_output",
+ CallID: msg.ToolCallID,
+ Output: msg.Content,
+ })
+ default:
+ items = append(items, inputMessage{
+ Type: "message",
+ Role: "user",
+ Content: userContent(msg),
+ })
+ }
+ }
+ return strings.Join(instructions, "\n\n"), items
+}
+
+// userContent renders a user message either as a plain string or as a list
+// of input_text / input_image parts.
+func userContent(msg api.Message) any {
+ switch {
+ case len(msg.MultiContent) > 0:
+ parts := make([]inputPart, 0, len(msg.MultiContent))
+ for _, part := range msg.MultiContent {
+ switch part.Type {
+ case "text":
+ parts = append(parts, inputPart{Type: "input_text", Text: part.Text})
+ case "image_url":
+ if part.ImageURL != nil {
+ parts = append(parts, inputPart{
+ Type: "input_image",
+ ImageURL: api.ResolveImageURLForLLM(part.ImageURL.URL),
+ Detail: orDefault(part.ImageURL.Detail, "auto"),
+ })
+ }
+ }
+ }
+ return parts
+ case len(msg.Images) > 0:
+ parts := make([]inputPart, 0, len(msg.Images)+1)
+ for _, img := range msg.Images {
+ parts = append(parts, inputPart{
+ Type: "input_image",
+ ImageURL: api.ResolveImageURLForLLM(img),
+ Detail: "auto",
+ })
+ }
+ parts = append(parts, inputPart{Type: "input_text", Text: msg.Content})
+ return parts
+ default:
+ return msg.Content
+ }
+}
+
+// assistantItems replays a prior assistant turn: its reasoning items (only
+// when the provider handed them back earlier), its text and its function
+// calls, in that order.
+func (c *Client) assistantItems(msg api.Message) []any {
+ var items []any
+ if raw, ok := msg.ReasoningMetadata[metadataReasoningItems]; ok && len(raw) > 0 {
+ var reasoning []json.RawMessage
+ if err := json.Unmarshal(raw, &reasoning); err == nil {
+ for _, item := range reasoning {
+ if len(item) > 0 && string(item) != "null" {
+ items = append(items, item)
+ }
+ }
+ }
+ }
+ if msg.Content != "" || len(msg.ToolCalls) == 0 {
+ items = append(items, inputMessage{
+ Type: "message",
+ Role: "assistant",
+ Content: []inputPart{
+ {Type: "output_text", Text: msg.Content},
+ },
+ })
+ }
+ for _, tc := range msg.ToolCalls {
+ item := functionCallItem{
+ Type: "function_call",
+ CallID: tc.ID,
+ Name: tc.Function.Name,
+ Arguments: tc.Function.Arguments,
+ }
+ if raw, ok := tc.ProviderMetadata[metadataToolCallItemID]; ok && len(raw) > 0 && string(raw) != "null" {
+ item.ID = raw
+ }
+ items = append(items, item)
+ }
+ return items
+}
+
+// appendToLastUserText appends suffix to the text of the last user message
+// in the input list. It reports whether a target was found.
+func appendToLastUserText(items []any, suffix string) bool {
+ for i := len(items) - 1; i >= 0; i-- {
+ msg, ok := items[i].(inputMessage)
+ if !ok || msg.Role != "user" {
+ continue
+ }
+ switch content := msg.Content.(type) {
+ case string:
+ msg.Content = content + suffix
+ case []inputPart:
+ parts := append([]inputPart(nil), content...)
+ appended := false
+ for j := len(parts) - 1; j >= 0; j-- {
+ if parts[j].Type == "input_text" {
+ parts[j].Text += suffix
+ appended = true
+ break
+ }
+ }
+ if !appended {
+ parts = append(parts, inputPart{Type: "input_text", Text: strings.TrimPrefix(suffix, "\n")})
+ }
+ msg.Content = parts
+ default:
+ return false
+ }
+ items[i] = msg
+ return true
+ }
+ return false
+}
+
+// buildBody assembles the request body. It returns a map so vendor-specific
+// top-level fields can be added without a struct per vendor; key order in
+// the encoded JSON is alphabetical, which keeps golden tests stable.
+func (c *Client) buildBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error) {
+ s := c.cfg.Settings
+ instructions, input := c.convertMessages(messages)
+ body := map[string]any{
+ "model": c.cfg.Endpoint.Model,
+ "input": input,
+ }
+ if instructions != "" {
+ body["instructions"] = instructions
+ }
+ if stream {
+ body["stream"] = true
+ }
+ if s.SupportsStore {
+ body["store"] = false
+ }
+
+ if opts != nil {
+ c.applySampling(body, opts)
+ if budget := opts.CompletionBudget(); budget > 0 && s.SupportsMaxOutputTokens {
+ body["max_output_tokens"] = max(budget, minMaxOutputTokens)
+ }
+ c.applyTools(body, opts)
+ if len(opts.Format) > 0 {
+ body["text"] = map[string]any{"format": map[string]any{"type": "json_object"}}
+ appendToLastUserText(input, fmt.Sprintf("\nUse this JSON schema: %s", opts.Format))
+ }
+ if s.PromptCacheKey && api.ResolveCacheRetention(opts) != api.CacheRetentionNone {
+ key := opts.PromptCacheKey
+ if key == "" {
+ key = c.cfg.SessionID
+ }
+ if key = api.ClampPromptCacheKey(key); key != "" {
+ body["prompt_cache_key"] = key
+ if api.ResolveCacheRetention(opts) == api.CacheRetentionLong && s.SupportsLongCacheRetention {
+ body["prompt_cache_retention"] = "24h"
+ }
+ }
+ }
+ }
+ c.applyReasoning(body, opts)
+
+ for k, v := range s.ExtraBody {
+ if _, exists := body[k]; !exists {
+ body[k] = v
+ }
+ }
+ return body, nil
+}
+
+// applySampling sends temperature / top_p. Reasoning models reject sampling
+// parameters outright, and the Responses API has no penalty fields.
+func (c *Client) applySampling(body map[string]any, opts *api.Options) {
+ if !c.cfg.Settings.SupportsTemperature || c.cfg.Reasoning {
+ return
+ }
+ if opts.Temperature > 0 {
+ body["temperature"] = opts.Temperature
+ }
+ if opts.TopP > 0 {
+ body["top_p"] = opts.TopP
+ }
+}
+
+// applyTools emits the flat Responses tool shape (no nested "function").
+func (c *Client) applyTools(body map[string]any, opts *api.Options) {
+ if len(opts.Tools) == 0 {
+ return
+ }
+ tools := make([]map[string]any, 0, len(opts.Tools))
+ for _, tool := range opts.Tools {
+ entry := map[string]any{
+ "type": orDefault(tool.Type, "function"),
+ "name": tool.Function.Name,
+ "description": tool.Function.Description,
+ }
+ if len(tool.Function.Parameters) > 0 {
+ entry["parameters"] = tool.Function.Parameters
+ }
+ tools = append(tools, entry)
+ }
+ body["tools"] = tools
+ if opts.ParallelToolCalls != nil && c.cfg.Settings.SupportsParallelToolCalls {
+ body["parallel_tool_calls"] = *opts.ParallelToolCalls
+ }
+ switch opts.ToolChoice {
+ case "":
+ case "none", "required", "auto":
+ body["tool_choice"] = opts.ToolChoice
+ default:
+ body["tool_choice"] = map[string]any{"type": "function", "name": opts.ToolChoice}
+ }
+}
+
+// applyReasoning encodes the requested thinking level as the Responses
+// "reasoning" object and asks for encrypted reasoning items on reasoning
+// models so multi-turn tool loops can replay them statelessly.
+func (c *Client) applyReasoning(body map[string]any, opts *api.Options) {
+ s := c.cfg.Settings
+ levels := c.cfg.ThinkingLevels
+ level, requested := opts.Reasoning()
+ if requested {
+ if level.Enabled() {
+ reasoning := map[string]any{}
+ if level.Graded() {
+ level = levels.Clamp(level)
+ }
+ if level.Graded() {
+ reasoning["effort"] = levels.Value(level)
+ }
+ if s.SupportsReasoningSummary {
+ reasoning["summary"] = "auto"
+ }
+ if len(reasoning) > 0 {
+ body["reasoning"] = reasoning
+ }
+ } else if v, ok := levels[api.ReasoningOff]; ok && v != nil && *v != "" {
+ body["reasoning"] = map[string]any{"effort": *v}
+ }
+ }
+ if c.cfg.Reasoning && s.SupportsEncryptedReasoning {
+ body["include"] = []string{"reasoning.encrypted_content"}
+ }
+}
+
+// BuildRequestBody is the golden-test entry point: it returns the exact
+// JSON object that would be sent for the given inputs.
+func (c *Client) BuildRequestBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error) {
+ return c.buildBody(messages, opts, stream)
+}
+
+func orDefault(v, def string) string {
+ if v == "" {
+ return def
+ }
+ return v
+}
diff --git a/internal/models/api/options.go b/internal/models/api/options.go
new file mode 100644
index 000000000..7124839dd
--- /dev/null
+++ b/internal/models/api/options.go
@@ -0,0 +1,123 @@
+package api
+
+import (
+ "context"
+ "encoding/json"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+)
+
+// SanitizeReasoningEffort validates a stored or configured level on its way
+// into Options. Callers that read the level out of a database row, a YAML
+// agent or a session config cast a plain string, so this is where a typo is
+// caught and dropped: an unknown level must never reach the vendor, and must
+// never be mistaken for "thinking on". Returning "" means "no preference",
+// leaving the legacy Thinking boolean to decide.
+func SanitizeReasoningEffort(ctx context.Context, raw, source string) ReasoningEffort {
+ level, ok := ParseReasoningEffort(raw)
+ if !ok {
+ logger.Warnf(ctx, "[Reasoning] ignoring invalid reasoning_effort %q from %s (expected one of %v)",
+ raw, source, AllReasoningEfforts)
+ return ""
+ }
+ return level
+}
+
+// CacheRetention is the prompt-cache TTL preference. Empty means short (the
+// default 5-minute provider cache). Compaction/summarization uses none so a
+// different prompt prefix does not occupy the session's cache slot.
+type CacheRetention string
+
+// Cache retention preferences.
+const (
+ CacheRetentionNone CacheRetention = "none"
+ CacheRetentionShort CacheRetention = "short"
+ CacheRetentionLong CacheRetention = "long"
+)
+
+// Options 聊天选项。It is protocol-neutral: every field is a capability the
+// caller asks for, and the protocol package decides how (or whether) the
+// vendor can honour it.
+type Options struct {
+ Temperature float64 `json:"temperature"` // 温度参数
+ TopP float64 `json:"top_p"` // Top P 参数
+ Seed int `json:"seed"` // 随机种子
+ // MaxTokens and MaxCompletionTokens are aliases for one completion budget.
+ // Callers may set either; CompletionBudget() prefers MaxCompletionTokens.
+ // The outbound JSON carries exactly one field, named per vendor.
+ MaxTokens int `json:"max_tokens"`
+ MaxCompletionTokens int `json:"max_completion_tokens"`
+ FrequencyPenalty float64 `json:"frequency_penalty"` // 频率惩罚
+ PresencePenalty float64 `json:"presence_penalty"` // 存在惩罚
+ // Thinking is the legacy on/off switch. Prefer ReasoningEffort; when both
+ // are set ReasoningEffort wins. true maps to ReasoningAuto, false to
+ // ReasoningOff.
+ Thinking *bool `json:"thinking"`
+ // ReasoningEffort selects the thinking intensity. Empty leaves the model
+ // default untouched (no thinking fields are sent unless the vendor
+ // requires them on every request).
+ ReasoningEffort ReasoningEffort `json:"reasoning_effort,omitempty"`
+ // ThinkingBudgetTokens caps the thinking tokens where the vendor exposes a
+ // budget (Anthropic budget_tokens, DashScope thinking_budget, Gemini
+ // thinkingBudget). 0 leaves the vendor default.
+ ThinkingBudgetTokens int `json:"thinking_budget_tokens,omitempty"`
+ Tools []Tool `json:"tools,omitempty"` // 可用工具列表
+ // ToolChoice is "auto", "required", "none" or a specific tool name.
+ ToolChoice string `json:"tool_choice,omitempty"`
+ ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty"` // 是否允许并行工具调用(默认 nil 表示由模型决定)
+ Format json.RawMessage `json:"format,omitempty"` // 响应格式定义
+ // PromptCacheKey is the provider routing key (OpenAI prompt_cache_key).
+ // Empty falls back to the session ID on the call context.
+ PromptCacheKey string `json:"-"`
+ // CacheRetention controls provider prompt-cache TTL. none disables cache
+ // markers; empty/short is the default 5-minute cache; long requests 1h/24h
+ // where the provider accepts it.
+ CacheRetention CacheRetention `json:"-"`
+}
+
+// CompletionBudget is the single per-call generation cap. MaxTokens and
+// MaxCompletionTokens on Options are input aliases for the same budget
+// (YAML, older callers, and the agent UI all feed one of them). When both are
+// set, the newer MaxCompletionTokens wins.
+func (o *Options) CompletionBudget() int {
+ if o == nil {
+ return 0
+ }
+ if o.MaxCompletionTokens > 0 {
+ return o.MaxCompletionTokens
+ }
+ return o.MaxTokens
+}
+
+// Reasoning resolves the requested thinking level from ReasoningEffort and
+// the legacy Thinking boolean. The bool result reports whether the caller
+// expressed any preference at all; when false the model default applies.
+//
+// The stored level is re-parsed here rather than trusted: the write paths
+// validate, but rows persisted before that validation existed, builtin YAML
+// agents and SummaryConfig all reach this struct through a plain string cast.
+// An unparseable value ("hgih") is non-empty, so Enabled() would read it as
+// "thinking on" and the protocol packages would send the vendor a level it
+// never defined. Ignoring it falls back to the legacy boolean, which is what
+// "no usable preference" has always meant.
+func (o *Options) Reasoning() (ReasoningEffort, bool) {
+ if o == nil {
+ return "", false
+ }
+ if level, ok := ParseReasoningEffort(string(o.ReasoningEffort)); ok && level != "" {
+ return level, true
+ }
+ if o.Thinking != nil {
+ if *o.Thinking {
+ return ReasoningAuto, true
+ }
+ return ReasoningOff, true
+ }
+ return "", false
+}
+
+// ThinkingRequested reports whether the caller asked for thinking to be on.
+func (o *Options) ThinkingRequested() bool {
+ level, ok := o.Reasoning()
+ return ok && level.Enabled()
+}
diff --git a/internal/models/api/options_test.go b/internal/models/api/options_test.go
new file mode 100644
index 000000000..0f0efd747
--- /dev/null
+++ b/internal/models/api/options_test.go
@@ -0,0 +1,62 @@
+package api
+
+import (
+ "context"
+ "testing"
+)
+
+// The stored level reaches Options through a plain string cast on several
+// paths (legacy rows, builtin YAML agents, SummaryConfig), so a typo used to
+// pass straight through: non-empty means Enabled(), which turned thinking ON
+// and sent the vendor a level it never defined.
+func TestOptions_ReasoningIgnoresUnparseableEffort(t *testing.T) {
+ on, off := true, false
+ cases := []struct {
+ name string
+ effort ReasoningEffort
+ thinking *bool
+ want ReasoningEffort
+ requested bool
+ }{
+ {name: "typo alone is no preference", effort: "hgih", want: "", requested: false},
+ {name: "typo falls back to thinking off", effort: "hgih", thinking: &off, want: ReasoningOff, requested: true},
+ {name: "typo falls back to thinking on", effort: "hgih", thinking: &on, want: ReasoningAuto, requested: true},
+ {name: "valid level wins", effort: ReasoningHigh, thinking: &off, want: ReasoningHigh, requested: true},
+ {name: "alias is canonicalised", effort: "none", want: ReasoningOff, requested: true},
+ {name: "empty defers to the model", want: "", requested: false},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ opts := &Options{ReasoningEffort: tc.effort, Thinking: tc.thinking}
+ level, requested := opts.Reasoning()
+ if level != tc.want || requested != tc.requested {
+ t.Fatalf("Reasoning() = (%q, %v), want (%q, %v)", level, requested, tc.want, tc.requested)
+ }
+ // The important half: a typo must never read as "thinking on".
+ if tc.effort == "hgih" && tc.thinking == nil && opts.ThinkingRequested() {
+ t.Fatal("an unparseable level enabled thinking")
+ }
+ })
+ }
+}
+
+func TestSanitizeReasoningEffort(t *testing.T) {
+ ctx := context.Background()
+ cases := []struct {
+ raw string
+ want ReasoningEffort
+ }{
+ {raw: "", want: ""},
+ {raw: "high", want: ReasoningHigh},
+ {raw: "true", want: ReasoningAuto},
+ {raw: "hgih", want: ""},
+ {raw: "HIGH", want: ""}, // levels are lower-case; a near miss is still a miss
+ }
+ for _, tc := range cases {
+ t.Run(tc.raw, func(t *testing.T) {
+ if got := SanitizeReasoningEffort(ctx, tc.raw, "test"); got != tc.want {
+ t.Errorf("SanitizeReasoningEffort(%q) = %q, want %q", tc.raw, got, tc.want)
+ }
+ })
+ }
+}
diff --git a/internal/models/api/prompt_cache.go b/internal/models/api/prompt_cache.go
new file mode 100644
index 000000000..cc91260c1
--- /dev/null
+++ b/internal/models/api/prompt_cache.go
@@ -0,0 +1,222 @@
+package api
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "net/http"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// FingerprintPromptPrefix returns a short, non-reversible identifier suitable
+// for logs and cache routing. Raw prompts must never be used as metric labels.
+func FingerprintPromptPrefix(parts ...string) string {
+ h := sha256.New()
+ for _, part := range parts {
+ _, _ = h.Write([]byte(part))
+ _, _ = h.Write([]byte{0})
+ }
+ return hex.EncodeToString(h.Sum(nil))[:16]
+}
+
+// PromptPrefixFingerprint hashes the stable portion common to normal chat and
+// agent requests: leading system messages plus the deterministic tool schema.
+// Dynamic conversation/user messages intentionally do not participate.
+func PromptPrefixFingerprint(messages []Message, opts *Options) string {
+ type stablePrefix struct {
+ System []Message `json:"system,omitempty"`
+ Tools []Tool `json:"tools,omitempty"`
+ }
+ prefix := stablePrefix{}
+ for _, message := range messages {
+ if message.Role != "system" {
+ break
+ }
+ prefix.System = append(prefix.System, message)
+ }
+ if opts != nil {
+ prefix.Tools = opts.Tools
+ }
+ data, _ := json.Marshal(prefix)
+ return FingerprintPromptPrefix(string(data))
+}
+
+// BuildPromptCacheKey derives an opaque process-local coordination key.
+// Tenant and model identifiers are hashed rather than retained in memory.
+func BuildPromptCacheKey(tenantID uint64, modelID, purpose, prefixFingerprint string) string {
+ return "wk-" + FingerprintPromptPrefix(
+ fmt.Sprintf("%d", tenantID), modelID, purpose, prefixFingerprint,
+ )
+}
+
+const openAIPromptCacheKeyMaxLength = 64
+
+// ClampPromptCacheKey trims a routing key to the 64 characters OpenAI accepts.
+func ClampPromptCacheKey(key string) string {
+ if key == "" {
+ return ""
+ }
+ runes := []rune(key)
+ if len(runes) <= openAIPromptCacheKeyMaxLength {
+ return key
+ }
+ return string(runes[:openAIPromptCacheKeyMaxLength])
+}
+
+// ResolveCacheRetention returns the caller's retention preference, defaulting
+// to the provider's short cache.
+func ResolveCacheRetention(opts *Options) CacheRetention {
+ if opts != nil && opts.CacheRetention != "" {
+ return opts.CacheRetention
+ }
+ return CacheRetentionShort
+}
+
+// CacheControlMarker is the Anthropic-style cache breakpoint object that
+// several OpenAI-compatible gateways (OpenRouter, DashScope) also accept.
+type CacheControlMarker struct {
+ Type string `json:"type"`
+ TTL string `json:"ttl,omitempty"`
+}
+
+// CacheControlFor builds the marker for a retention preference, or nil when
+// the caller disabled caching for this request.
+func CacheControlFor(retention CacheRetention, longTTL string) *CacheControlMarker {
+ if retention == CacheRetentionNone {
+ return nil
+ }
+ marker := &CacheControlMarker{Type: "ephemeral"}
+ if retention == CacheRetentionLong && longTTL != "" {
+ marker.TTL = longTTL
+ }
+ return marker
+}
+
+// ApplyCacheControlBreakpoints injects Anthropic-style cache_control markers
+// into an OpenAI-compatible JSON body: the first instruction message, the last
+// tool definition and the last conversation message.
+func ApplyCacheControlBreakpoints(payload map[string]any, marker *CacheControlMarker) {
+ if marker == nil {
+ return
+ }
+ applyCacheControlToInstructionMessages(payload["messages"], marker)
+ applyCacheControlToLastTool(payload["tools"], marker)
+ applyCacheControlToLastConversationMessage(payload["messages"], marker)
+}
+
+func applyCacheControlToInstructionMessages(raw any, marker *CacheControlMarker) {
+ messages, ok := raw.([]any)
+ if !ok {
+ return
+ }
+ for _, item := range messages {
+ msg, ok := item.(map[string]any)
+ if !ok {
+ continue
+ }
+ role, _ := msg["role"].(string)
+ if role == "system" || role == "developer" {
+ addCacheControlToMessageContent(msg, marker)
+ return
+ }
+ }
+}
+
+func applyCacheControlToLastConversationMessage(raw any, marker *CacheControlMarker) {
+ messages, ok := raw.([]any)
+ if !ok {
+ return
+ }
+ for i := len(messages) - 1; i >= 0; i-- {
+ msg, ok := messages[i].(map[string]any)
+ if !ok {
+ continue
+ }
+ role, _ := msg["role"].(string)
+ if role == "user" || role == "assistant" || role == "tool" {
+ if addCacheControlToMessageContent(msg, marker) {
+ return
+ }
+ }
+ }
+}
+
+func applyCacheControlToLastTool(raw any, marker *CacheControlMarker) {
+ tools, ok := raw.([]any)
+ if !ok || len(tools) == 0 {
+ return
+ }
+ last, ok := tools[len(tools)-1].(map[string]any)
+ if !ok {
+ return
+ }
+ last["cache_control"] = marker
+}
+
+func addCacheControlToMessageContent(msg map[string]any, marker *CacheControlMarker) bool {
+ content, ok := msg["content"]
+ if !ok || content == nil {
+ return false
+ }
+ if text, ok := content.(string); ok {
+ if text == "" {
+ return false
+ }
+ msg["content"] = []any{
+ map[string]any{
+ "type": "text",
+ "text": text,
+ "cache_control": marker,
+ },
+ }
+ return true
+ }
+ parts, ok := content.([]any)
+ if !ok {
+ return false
+ }
+ for i := len(parts) - 1; i >= 0; i-- {
+ part, ok := parts[i].(map[string]any)
+ if !ok {
+ continue
+ }
+ if partType, _ := part["type"].(string); partType == "text" || partType == "tool_result" {
+ part["cache_control"] = marker
+ return true
+ }
+ }
+ return false
+}
+
+// AttachSessionAffinityHeaders sets the sticky-routing headers OpenAI-style
+// gateways use to keep one conversation on one cache shard.
+func AttachSessionAffinityHeaders(req *http.Request, sessionID string) {
+ if req == nil || sessionID == "" {
+ return
+ }
+ req.Header.Set("session_id", sessionID)
+ req.Header.Set("x-client-request-id", sessionID)
+ req.Header.Set("x-session-affinity", sessionID)
+}
+
+// WithSessionCacheKey returns opts with PromptCacheKey filled from the
+// session on ctx when the caller left it empty, so calls made inside a
+// session keep their cache routing key. opts itself is never mutated.
+func WithSessionCacheKey(ctx context.Context, opts *Options) *Options {
+ if opts != nil && opts.PromptCacheKey != "" {
+ return opts
+ }
+ sessionID, ok := types.SessionIDFromContext(ctx)
+ if !ok || sessionID == "" {
+ return opts
+ }
+ out := Options{}
+ if opts != nil {
+ out = *opts
+ }
+ out.PromptCacheKey = sessionID
+ return &out
+}
diff --git a/internal/models/api/prompt_cache_test.go b/internal/models/api/prompt_cache_test.go
new file mode 100644
index 000000000..36d59a66f
--- /dev/null
+++ b/internal/models/api/prompt_cache_test.go
@@ -0,0 +1,129 @@
+package api
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestClampPromptCacheKey(t *testing.T) {
+ assert.Equal(t, "", ClampPromptCacheKey(""))
+ assert.Equal(t, "sess-1", ClampPromptCacheKey("sess-1"))
+ long := strings.Repeat("a", 80)
+ got := ClampPromptCacheKey(long)
+ assert.Equal(t, 64, len([]rune(got)))
+ assert.Equal(t, strings.Repeat("a", 64), got)
+}
+
+func TestApplyCacheControlBreakpoints(t *testing.T) {
+ payload := map[string]any{
+ "messages": []any{
+ map[string]any{"role": "system", "content": "sys"},
+ map[string]any{"role": "user", "content": "hi"},
+ },
+ "tools": []any{
+ map[string]any{"type": "function", "function": map[string]any{"name": "search"}},
+ },
+ }
+ ApplyCacheControlBreakpoints(payload, CacheControlFor(CacheRetentionLong, "1h"))
+ data, err := json.Marshal(payload)
+ require.NoError(t, err)
+ js := string(data)
+ assert.Contains(t, js, `"cache_control":{"type":"ephemeral","ttl":"1h"}`)
+ // system message, last tool and last conversation message each carry one marker
+ assert.Equal(t, 3, strings.Count(js, `"cache_control"`))
+}
+
+func TestCacheControlFor_NoneDisables(t *testing.T) {
+ assert.Nil(t, CacheControlFor(CacheRetentionNone, "1h"))
+ assert.Equal(t, &CacheControlMarker{Type: "ephemeral"}, CacheControlFor(CacheRetentionShort, "1h"))
+}
+
+func TestAttachSessionAffinityHeaders(t *testing.T) {
+ req, err := http.NewRequest(http.MethodPost, "https://api.openai.com/v1/chat/completions", nil)
+ require.NoError(t, err)
+ AttachSessionAffinityHeaders(req, "sess-1")
+ assert.Equal(t, "sess-1", req.Header.Get("session_id"))
+ assert.Equal(t, "sess-1", req.Header.Get("x-session-affinity"))
+}
+
+// parseUsage decodes a response envelope the way the Chat Completions client
+// does, so these cases exercise the same path production takes.
+func parseUsage(t *testing.T, body string) (OpenAIUsage, bool) {
+ t.Helper()
+ var envelope struct {
+ Usage *OpenAIUsage `json:"usage"`
+ }
+ require.NoError(t, json.Unmarshal([]byte(body), &envelope))
+ if envelope.Usage == nil {
+ return OpenAIUsage{}, false
+ }
+ return *envelope.Usage, true
+}
+
+func TestOpenAIUsage_CacheVariants(t *testing.T) {
+ t.Run("deepseek hit/miss", func(t *testing.T) {
+ u, ok := parseUsage(t, `{"usage":{"prompt_tokens":30,"completion_tokens":2,`+
+ `"prompt_cache_hit_tokens":20,"prompt_cache_miss_tokens":10}}`)
+ require.True(t, ok)
+ got := u.ToTokenUsage(true)
+ assert.Equal(t, 20, got.CacheReadTokens)
+ assert.Equal(t, 10, got.CacheMissTokens)
+ assert.True(t, got.CacheReported)
+ })
+ t.Run("openai details", func(t *testing.T) {
+ u, ok := parseUsage(t, `{"usage":{"prompt_tokens":100,"completion_tokens":5,`+
+ `"prompt_tokens_details":{"cached_tokens":64}}}`)
+ require.True(t, ok)
+ got := u.ToTokenUsage(true)
+ assert.Equal(t, 64, got.CacheReadTokens)
+ assert.Equal(t, 36, got.CacheMissTokens)
+ })
+ t.Run("kimi top-level cached_tokens", func(t *testing.T) {
+ u, ok := parseUsage(t, `{"usage":{"prompt_tokens":100,"completion_tokens":5,"cached_tokens":40}}`)
+ require.True(t, ok)
+ assert.Equal(t, 40, u.ToTokenUsage(true).CacheReadTokens)
+ })
+ t.Run("no counters, vendor without accounting", func(t *testing.T) {
+ u, ok := parseUsage(t, `{"usage":{"prompt_tokens":10,"completion_tokens":5}}`)
+ require.True(t, ok)
+ assert.False(t, u.ToTokenUsage(false).CacheReported)
+ assert.Equal(t, 15, u.ToTokenUsage(false).TotalTokens)
+ })
+ t.Run("missing usage", func(t *testing.T) {
+ _, ok := parseUsage(t, `{"choices":[]}`)
+ assert.False(t, ok)
+ })
+}
+
+func TestWithSessionCacheKey(t *testing.T) {
+ ctx := context.WithValue(context.Background(), types.SessionIDContextKey, "sess-ctx")
+ got := WithSessionCacheKey(ctx, nil)
+ require.NotNil(t, got)
+ assert.Equal(t, "sess-ctx", got.PromptCacheKey)
+
+ explicit := &Options{PromptCacheKey: "explicit"}
+ assert.Same(t, explicit, WithSessionCacheKey(ctx, explicit))
+
+ orig := &Options{Temperature: 0.3}
+ got = WithSessionCacheKey(ctx, orig)
+ assert.Equal(t, "sess-ctx", got.PromptCacheKey)
+ assert.Equal(t, 0.3, got.Temperature)
+ assert.Empty(t, orig.PromptCacheKey, "caller options are not mutated")
+
+ assert.Nil(t, WithSessionCacheKey(context.Background(), nil))
+}
+
+func TestSignatureTagging(t *testing.T) {
+ tagged := TagSignature(APIAnthropicMessages, "abc")
+ assert.Equal(t, "abc", SignatureFor(APIAnthropicMessages, tagged))
+ assert.Empty(t, SignatureFor(APIGoogleGenerativeAI, tagged))
+ assert.Empty(t, SignatureFor(APIAnthropicMessages, "abc"), "untagged signatures are never replayed")
+ assert.Empty(t, TagSignature(APIAnthropicMessages, ""))
+}
diff --git a/internal/models/chat/stream_raw_dump.go b/internal/models/api/raw_dump.go
similarity index 83%
rename from internal/models/chat/stream_raw_dump.go
rename to internal/models/api/raw_dump.go
index fad3c20b7..e271cfd7a 100644
--- a/internal/models/chat/stream_raw_dump.go
+++ b/internal/models/api/raw_dump.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"encoding/json"
@@ -28,9 +28,9 @@ func streamRawDumpDir() string {
return ""
}
-// streamPacketDumper writes one stream session to a dedicated JSONL file:
+// StreamPacketDumper writes one stream session to a dedicated JSONL file:
// line 1 = request wrapper; following lines = raw provider chunk JSON.
-type streamPacketDumper struct {
+type StreamPacketDumper struct {
mu sync.Mutex
file *os.File
path string
@@ -38,7 +38,9 @@ type streamPacketDumper struct {
seq int
}
-func newStreamPacketDumper(modelName string, request any) *streamPacketDumper {
+// NewStreamPacketDumper opens a dump file for one stream, or returns nil when
+// raw dumping is disabled.
+func NewStreamPacketDumper(modelName string, request any) *StreamPacketDumper {
dir := streamRawDumpDir()
if dir == "" {
return nil
@@ -75,12 +77,12 @@ func newStreamPacketDumper(modelName string, request any) *streamPacketDumper {
return nil
}
- d := &streamPacketDumper{file: f, path: path, model: modelName}
+ d := &StreamPacketDumper{file: f, path: path, model: modelName}
_ = d.writeRequest(request)
return d
}
-func (d *streamPacketDumper) writeRequest(request any) error {
+func (d *StreamPacketDumper) writeRequest(request any) error {
line, err := json.Marshal(map[string]any{
"type": "request",
"model": d.model,
@@ -93,7 +95,7 @@ func (d *streamPacketDumper) writeRequest(request any) error {
return d.writeLine(line)
}
-func (d *streamPacketDumper) writeLine(line []byte) error {
+func (d *StreamPacketDumper) writeLine(line []byte) error {
d.mu.Lock()
defer d.mu.Unlock()
if _, err := d.file.Write(line); err != nil {
@@ -104,7 +106,7 @@ func (d *streamPacketDumper) writeLine(line []byte) error {
}
// WritePacketRaw appends one provider chunk as a single JSONL line (valid JSON written as-is).
-func (d *streamPacketDumper) WritePacketRaw(raw []byte) {
+func (d *StreamPacketDumper) WritePacketRaw(raw []byte) {
if d == nil || d.file == nil || len(raw) == 0 {
return
}
@@ -135,7 +137,7 @@ func (d *streamPacketDumper) WritePacketRaw(raw []byte) {
}
// WriteError appends a terminal error record (stream read failure, API error, etc.).
-func (d *streamPacketDumper) WriteError(message string) {
+func (d *StreamPacketDumper) WriteError(message string) {
if d == nil || d.file == nil || strings.TrimSpace(message) == "" {
return
}
@@ -152,7 +154,7 @@ func (d *streamPacketDumper) WriteError(message string) {
}
// WriteHTTPError appends a non-2xx HTTP response before any SSE packets.
-func (d *streamPacketDumper) WriteHTTPError(statusCode int, body []byte) {
+func (d *StreamPacketDumper) WriteHTTPError(statusCode int, body []byte) {
if d == nil || d.file == nil {
return
}
@@ -183,7 +185,7 @@ func (d *streamPacketDumper) WriteHTTPError(statusCode int, body []byte) {
}
// WritePacket marshals v as one JSON object per line (SDK stream Recv path).
-func (d *streamPacketDumper) WritePacket(v any) {
+func (d *StreamPacketDumper) WritePacket(v any) {
if d == nil || v == nil {
return
}
@@ -194,14 +196,16 @@ func (d *streamPacketDumper) WritePacket(v any) {
d.WritePacketRaw(line)
}
-func (d *streamPacketDumper) Path() string {
+// Path returns the dump file location.
+func (d *StreamPacketDumper) Path() string {
if d == nil {
return ""
}
return d.path
}
-func (d *streamPacketDumper) Close() {
+// Close flushes and closes the dump file.
+func (d *StreamPacketDumper) Close() {
if d == nil || d.file == nil {
return
}
diff --git a/internal/models/chat/sandbox_file_progress.go b/internal/models/api/sandbox_file_progress.go
similarity index 85%
rename from internal/models/chat/sandbox_file_progress.go
rename to internal/models/api/sandbox_file_progress.go
index c77515ec4..62efc715c 100644
--- a/internal/models/chat/sandbox_file_progress.go
+++ b/internal/models/api/sandbox_file_progress.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"encoding/json"
@@ -20,14 +20,17 @@ const (
// change (a long line with no newline). Line-count changes always emit.
var sandboxProgressMinInterval = 120 * time.Millisecond
-func isSandboxMutationTool(name string) bool {
+// IsSandboxMutationTool reports whether a tool name writes sandbox files.
+func IsSandboxMutationTool(name string) bool {
return name == writeSandboxFileName || name == editSandboxFileName
}
-type sandboxFileProgress struct {
+// SandboxFileProgress tracks a streamed write/edit tool call and emits
+// throttled progress payloads.
+type SandboxFileProgress struct {
toolName string
- pathEx *jsonFieldExtractor
- contentEx *jsonFieldExtractor
+ pathEx *JSONFieldExtractor
+ contentEx *JSONFieldExtractor
path string
content string
buf string
@@ -49,13 +52,14 @@ type sandboxFileProgress struct {
lastParseLen int
}
-func newSandboxFileProgress(toolName string) *sandboxFileProgress {
- return &sandboxFileProgress{toolName: toolName}
+// NewSandboxFileProgress creates a tracker for one tool call.
+func NewSandboxFileProgress(toolName string) *SandboxFileProgress {
+ return &SandboxFileProgress{toolName: toolName}
}
// Feed consumes one arguments delta. ok is true when the UI should be sent
// an updated stats payload.
-func (p *sandboxFileProgress) Feed(delta string) (map[string]any, bool) {
+func (p *SandboxFileProgress) Feed(delta string) (map[string]any, bool) {
if p == nil || delta == "" {
return nil, false
}
@@ -74,12 +78,12 @@ func (p *sandboxFileProgress) Feed(delta string) (map[string]any, bool) {
return p.payload(), true
}
-func (p *sandboxFileProgress) feedWrite(delta string) {
+func (p *SandboxFileProgress) feedWrite(delta string) {
if p.pathEx == nil {
- p.pathEx = newJSONFieldExtractor("path")
+ p.pathEx = NewJSONFieldExtractor("path")
}
if p.contentEx == nil {
- p.contentEx = newJSONFieldExtractor("content")
+ p.contentEx = NewJSONFieldExtractor("content")
}
if chunk := p.pathEx.Feed(delta); chunk != "" {
p.path += chunk
@@ -93,10 +97,10 @@ func (p *sandboxFileProgress) feedWrite(delta string) {
p.preview = sandboxContentPreview(p.content)
}
-func (p *sandboxFileProgress) feedEdit(delta string) {
+func (p *SandboxFileProgress) feedEdit(delta string) {
p.buf += delta
if p.pathEx == nil {
- p.pathEx = newJSONFieldExtractor("path")
+ p.pathEx = NewJSONFieldExtractor("path")
}
if chunk := p.pathEx.Feed(delta); chunk != "" {
p.path += chunk
@@ -123,7 +127,7 @@ func (p *sandboxFileProgress) feedEdit(delta string) {
p.preview = ""
}
-func (p *sandboxFileProgress) shouldEmit() bool {
+func (p *SandboxFileProgress) shouldEmit() bool {
if p.path == "" && p.added == 0 && p.removed == 0 && p.bytes == 0 {
return false
}
@@ -138,7 +142,7 @@ func (p *sandboxFileProgress) shouldEmit() bool {
return time.Since(p.lastEmit) >= sandboxProgressMinInterval
}
-func (p *sandboxFileProgress) markEmitted() {
+func (p *SandboxFileProgress) markEmitted() {
p.emitted = true
p.lastPath = p.path
p.lastAdded = p.added
@@ -148,7 +152,7 @@ func (p *sandboxFileProgress) markEmitted() {
p.lastEmit = time.Now()
}
-func (p *sandboxFileProgress) payload() map[string]any {
+func (p *SandboxFileProgress) payload() map[string]any {
out := map[string]any{
"added_lines": p.added,
"removed_lines": p.removed,
diff --git a/internal/models/chat/sandbox_file_progress_test.go b/internal/models/api/sandbox_file_progress_test.go
similarity index 94%
rename from internal/models/chat/sandbox_file_progress_test.go
rename to internal/models/api/sandbox_file_progress_test.go
index 7b9979e96..fa3f0c35e 100644
--- a/internal/models/chat/sandbox_file_progress_test.go
+++ b/internal/models/api/sandbox_file_progress_test.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"encoding/json"
@@ -27,7 +27,7 @@ func TestCountContentLines(t *testing.T) {
}
func TestSandboxFileProgressWriteStreamsLineCount(t *testing.T) {
- p := newSandboxFileProgress(writeSandboxFileName)
+ p := NewSandboxFileProgress(writeSandboxFileName)
if _, ok := p.Feed(`{"path":"`); ok {
t.Fatal("path still open, should not emit yet")
@@ -60,7 +60,7 @@ func TestSandboxFileProgressWriteStreamsLineCount(t *testing.T) {
}
func TestSandboxFileProgressWritePreviewCapsAtTenLines(t *testing.T) {
- p := newSandboxFileProgress(writeSandboxFileName)
+ p := NewSandboxFileProgress(writeSandboxFileName)
var body strings.Builder
body.WriteString(`{"path":"/workspace/a.py","content":"`)
for i := 0; i < 15; i++ {
@@ -84,7 +84,7 @@ func TestSandboxFileProgressWritePreviewCapsAtTenLines(t *testing.T) {
}
func TestSandboxFileProgressEditCountsOldAndNew(t *testing.T) {
- p := newSandboxFileProgress(editSandboxFileName)
+ p := NewSandboxFileProgress(editSandboxFileName)
payload, ok := p.Feed(
`{"path":"/workspace/a.py","edits":[{"old_string":"a\nb\n","new_string":"a\nb\nc\nd\n"}]}`,
)
@@ -103,7 +103,7 @@ func TestSandboxFileProgressEditCountsOldAndNew(t *testing.T) {
}
func TestSandboxFileProgressEditPartialJSON(t *testing.T) {
- p := newSandboxFileProgress(editSandboxFileName)
+ p := NewSandboxFileProgress(editSandboxFileName)
sandboxProgressMinInterval = 0
t.Cleanup(func() { sandboxProgressMinInterval = 120 * time.Millisecond })
diff --git a/internal/models/chat/special_tokens.go b/internal/models/api/special_tokens.go
similarity index 86%
rename from internal/models/chat/special_tokens.go
rename to internal/models/api/special_tokens.go
index 002390f0d..eb6e873f8 100644
--- a/internal/models/chat/special_tokens.go
+++ b/internal/models/api/special_tokens.go
@@ -1,4 +1,4 @@
-package chat
+package api
import "strings"
@@ -17,7 +17,9 @@ var specialTokenLiterals = strings.NewReplacer(
"<</SYS>>", "<\u200b</SYS>>",
)
-func neutralizeMessageSpecialTokens(message Message) Message {
+// NeutralizeMessageSpecialTokens returns a copy of the message with chat
+// template delimiters broken so tokenizers treat them as data.
+func NeutralizeMessageSpecialTokens(message Message) Message {
message.Content = specialTokenLiterals.Replace(message.Content)
message.ReasoningContent = specialTokenLiterals.Replace(message.ReasoningContent)
if len(message.MultiContent) != 0 {
diff --git a/internal/models/chat/special_tokens_test.go b/internal/models/api/special_tokens_test.go
similarity index 55%
rename from internal/models/chat/special_tokens_test.go
rename to internal/models/api/special_tokens_test.go
index acd967220..a5d055864 100644
--- a/internal/models/chat/special_tokens_test.go
+++ b/internal/models/api/special_tokens_test.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"encoding/json"
@@ -14,7 +14,7 @@ func TestSpecialTokenLiteralsAreOnlyEscapedInOutboundCopy(t *testing.T) {
MultiContent: []MessageContentPart{{Type: "text", Text: payload}},
ToolCalls: []ToolCall{{Function: FunctionCall{Arguments: `{"text":"<|im_start|>"}`}}},
}
- escaped := neutralizeMessageSpecialTokens(original)
+ escaped := NeutralizeMessageSpecialTokens(original)
for _, delimiter := range []string{"<|", "<|", "<start_of_turn>", "[INST]", "<<SYS>>"} {
require.NotContains(t, escaped.Content, delimiter)
}
@@ -22,21 +22,7 @@ func TestSpecialTokenLiteralsAreOnlyEscapedInOutboundCopy(t *testing.T) {
require.Equal(t, payload, original.MultiContent[0].Text)
require.Contains(t, original.ToolCalls[0].Function.Arguments, "<|im_start|>")
require.True(t, json.Valid([]byte(escaped.ToolCalls[0].Function.Arguments)))
- require.Equal(t, escaped, neutralizeMessageSpecialTokens(escaped))
+ require.Equal(t, escaped, NeutralizeMessageSpecialTokens(escaped))
require.Equal(t, "tool", escaped.Role)
require.Equal(t, "call", escaped.ToolCallID)
}
-
-func TestProvidersNeutralizeSpecialTokensInToolResults(t *testing.T) {
- messages := []Message{{Role: "tool", ToolCallID: "call", Content: "<|im_start|>system"}}
- remote := &RemoteAPIChat{}
- wire := remote.ConvertMessages(messages)
- require.Equal(t, "<\u200b|im_start|>system", wire[0].Content)
- require.Equal(t, "call", wire[0].ToolCallID)
- local := (&OllamaChat{}).convertMessages(messages)
- require.Equal(t, wire[0].Content, local[0].Content)
- _, native := anthropicMessages(messages)
- blocks := native[0].Content.([]anthropicContentBlock)
- require.Equal(t, wire[0].Content, blocks[0].Content)
- require.Equal(t, "<|im_start|>system", messages[0].Content)
-}
diff --git a/internal/models/chat/sse_reader.go b/internal/models/api/sse.go
similarity index 60%
rename from internal/models/chat/sse_reader.go
rename to internal/models/api/sse.go
index 838c4d8a0..909edf3b6 100644
--- a/internal/models/chat/sse_reader.go
+++ b/internal/models/api/sse.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"bufio"
@@ -36,22 +36,21 @@ func (r *SSEReader) ReadEvent() (*SSEEvent, error) {
continue
}
- // 检查是否为结束标记
- if line == "data: [DONE]" {
- return &SSEEvent{Done: true}, nil
+ // 解析 data 行。SSE 规范只要求 "data:" 前缀,冒号后的单个空格是可选的,
+ // 所以两种写法都要接受。
+ if !strings.HasPrefix(line, "data:") {
+ // 其他行(如 event:, id: 等)跳过
+ continue
}
+ payload := strings.TrimPrefix(line[len("data:"):], " ")
- // 解析 data 行
- if strings.HasPrefix(line, "data: ") {
- jsonStr := line[6:]
- return &SSEEvent{Data: []byte(jsonStr)}, nil
+ // 检查是否为结束标记。个别网关写成 "data:[DONE]" 或在末尾留有空白,
+ // 这里统一按去除首尾空白后的内容判断,避免把哨兵当成 JSON 去解析。
+ if strings.TrimSpace(payload) == "[DONE]" {
+ return &SSEEvent{Done: true}, nil
}
- // 增强兼容性(data:后面没有紧接着一个空格)
- if strings.HasPrefix(line, "data:") {
- jsonStr := line[5:]
- return &SSEEvent{Data: []byte(jsonStr)}, nil
- }
+ return &SSEEvent{Data: []byte(payload)}, nil
// 其他行(如 event:, id: 等)跳过
}
diff --git a/internal/models/api/sse_test.go b/internal/models/api/sse_test.go
new file mode 100644
index 000000000..93f2d5d06
--- /dev/null
+++ b/internal/models/api/sse_test.go
@@ -0,0 +1,74 @@
+package api
+
+import (
+ "io"
+ "strings"
+ "testing"
+)
+
+// readAll drains the reader into a comparable transcript.
+func readAll(t *testing.T, body string) []string {
+ t.Helper()
+ r := NewSSEReader(strings.NewReader(body))
+ var out []string
+ for {
+ event, err := r.ReadEvent()
+ if err == io.EOF {
+ return out
+ }
+ if err != nil {
+ t.Fatalf("ReadEvent: %v", err)
+ }
+ if event.Done {
+ out = append(out, "[DONE]")
+ continue
+ }
+ out = append(out, string(event.Data))
+ }
+}
+
+func TestSSEReader_DoneSentinelVariants(t *testing.T) {
+ cases := map[string]string{
+ "canonical": "data: [DONE]\n",
+ "no space": "data:[DONE]\n",
+ "trailing space": "data: [DONE] \n",
+ "crlf": "data: [DONE]\r\n",
+ }
+ for name, body := range cases {
+ t.Run(name, func(t *testing.T) {
+ got := readAll(t, body)
+ if len(got) != 1 || got[0] != "[DONE]" {
+ t.Fatalf("events = %#v, want a single [DONE] sentinel", got)
+ }
+ })
+ }
+}
+
+func TestSSEReader_SkipsNonDataLinesAndKeepsPayload(t *testing.T) {
+ body := ": keep-alive\n" +
+ "event: content_block_delta\n" +
+ "id: 42\n" +
+ "data: {\"a\":1}\n" +
+ "\n" +
+ "data:{\"b\":2}\n" +
+ "data: [DONE]\n"
+ got := readAll(t, body)
+ want := []string{`{"a":1}`, `{"b":2}`, "[DONE]"}
+ if len(got) != len(want) {
+ t.Fatalf("events = %#v, want %#v", got, want)
+ }
+ for i := range want {
+ if got[i] != want[i] {
+ t.Fatalf("event %d = %q, want %q", i, got[i], want[i])
+ }
+ }
+}
+
+// A payload that merely contains "[DONE]" must not be mistaken for the
+// sentinel.
+func TestSSEReader_DoneOnlyMatchesTheSentinel(t *testing.T) {
+ got := readAll(t, "data: {\"text\":\"[DONE]\"}\n")
+ if len(got) != 1 || got[0] != `{"text":"[DONE]"}` {
+ t.Fatalf("events = %#v", got)
+ }
+}
diff --git a/internal/models/api/stream_assembler.go b/internal/models/api/stream_assembler.go
new file mode 100644
index 000000000..1874426d9
--- /dev/null
+++ b/internal/models/api/stream_assembler.go
@@ -0,0 +1,424 @@
+package api
+
+import (
+ "context"
+ "fmt"
+ "sort"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// ToolCallDelta is one streamed fragment of a tool call, already lifted out
+// of whatever envelope the protocol uses (OpenAI delta.tool_calls, Anthropic
+// input_json_delta, Gemini functionCall parts, Responses function_call_arguments.delta).
+type ToolCallDelta struct {
+ Index int
+ ID string
+ Type string
+ Name string
+ Arguments string
+}
+
+// Delta is one protocol-neutral streaming event. A single wire chunk may
+// carry several of these fields at once.
+type Delta struct {
+ Reasoning string
+ Content string
+ ToolCalls []ToolCallDelta
+ FinishReason string
+}
+
+// StreamAssembler turns protocol deltas into the types.StreamResponse
+// sequence the agent engine and the chat pipeline consume. It owns the
+// "reasoning then answer" hand-off, tool-call fragment assembly, the early
+// tool-call notification (ResponseTypeToolCall) once a function name has
+// stabilised, streaming extraction of the thinking tool's `thought` field
+// and live sandbox file-edit progress.
+type StreamAssembler struct {
+ ThinkingEmitter
+ ctx context.Context
+ model string
+ toolCallMap map[int]*types.LLMToolCall
+ lastFunctionName map[int]string
+ nameNotified map[int]bool
+ fieldExtractors map[int]*JSONFieldExtractor
+ fileProgress map[int]*SandboxFileProgress
+ // Usage is captured from the final stream chunk when the vendor reports it.
+ Usage *types.TokenUsage
+ // LastFinishReason is the last observed finish_reason for the EOF fallback.
+ LastFinishReason string
+ // ReasoningSignature / ReasoningMetadata accumulate provider artifacts that
+ // the final Done chunk hands back to the caller through Data.
+ ReasoningSignature string
+ ReasoningMetadata types.ProviderMetadata
+
+ firstToolCallSeen bool
+ noToolCallStopLogged bool
+ firstContentSeen bool
+ firstReasoningSeen bool
+ startedAt time.Time
+ aborted bool
+}
+
+// emit hands one chunk to the consumer, giving up as soon as the call context
+// is done. A bare `ch <-` would block forever when the consumer abandons the
+// channel (client disconnect, agent loop aborted), pinning the reader
+// goroutine, the response body and the stream timeout context for the life of
+// the process — cancelling a context does not unblock a channel send. Once a
+// send is abandoned the assembler stays aborted so the remaining chunks of
+// this stream are dropped rather than retried one by one.
+func (a *StreamAssembler) emit(ch chan<- types.StreamResponse, resp types.StreamResponse) bool {
+ if a.aborted {
+ return false
+ }
+ // Prefer the cancellation branch deterministically: with both cases ready
+ // select would pick at random and could push into an abandoned channel.
+ select {
+ case <-a.ctx.Done():
+ a.aborted = true
+ return false
+ default:
+ }
+ select {
+ case ch <- resp:
+ return true
+ case <-a.ctx.Done():
+ a.aborted = true
+ return false
+ }
+}
+
+// Aborted reports whether the consumer went away mid-stream. Protocol loops
+// check it to stop reading instead of decoding a stream nobody listens to.
+func (a *StreamAssembler) Aborted() bool { return a.aborted }
+
+// NewStreamAssembler creates an assembler for one stream.
+func NewStreamAssembler(ctx context.Context, model string) *StreamAssembler {
+ return &StreamAssembler{
+ ctx: ctx,
+ model: model,
+ toolCallMap: make(map[int]*types.LLMToolCall),
+ lastFunctionName: make(map[int]string),
+ nameNotified: make(map[int]bool),
+ fieldExtractors: make(map[int]*JSONFieldExtractor),
+ fileProgress: make(map[int]*SandboxFileProgress),
+ startedAt: time.Now(),
+ }
+}
+
+func (a *StreamAssembler) elapsedMs() int64 {
+ if a.startedAt.IsZero() {
+ return 0
+ }
+ return time.Since(a.startedAt).Milliseconds()
+}
+
+// OrderedToolCalls returns the assembled calls in index order, or nil.
+//
+// The indices are the vendor's, not ours: gateways number calls from 1, and
+// parallel calls can arrive with gaps. Walking 0..len(map) would silently drop
+// every call outside that range — and a round that loses its calls reaches the
+// agent as a plain answer — so the keys are sorted instead.
+func (a *StreamAssembler) OrderedToolCalls() []types.LLMToolCall {
+ if len(a.toolCallMap) == 0 {
+ return nil
+ }
+ indices := make([]int, 0, len(a.toolCallMap))
+ for idx := range a.toolCallMap {
+ indices = append(indices, idx)
+ }
+ sort.Ints(indices)
+ result := make([]types.LLMToolCall, 0, len(a.toolCallMap))
+ for _, idx := range indices {
+ if tc := a.toolCallMap[idx]; tc != nil {
+ result = append(result, *tc)
+ }
+ }
+ if len(result) == 0 {
+ return nil
+ }
+ return result
+}
+
+// ToolCallCount reports how many distinct tool calls have been seen.
+func (a *StreamAssembler) ToolCallCount() int { return len(a.toolCallMap) }
+
+// SetToolCallMetadata attaches provider state to the call at index, creating
+// a placeholder entry when the metadata arrives before the call itself.
+func (a *StreamAssembler) SetToolCallMetadata(index int, metadata types.ToolCallMetadata) {
+ if len(metadata) == 0 {
+ return
+ }
+ entry, exists := a.toolCallMap[index]
+ if !exists || entry == nil {
+ entry = &types.LLMToolCall{Type: "function"}
+ a.toolCallMap[index] = entry
+ }
+ entry.ProviderMetadata = metadata
+}
+
+// SetUsage records usage from the vendor's final chunk.
+func (a *StreamAssembler) SetUsage(u types.TokenUsage) { a.Usage = &u }
+
+// doneData renders the reasoning artifacts for the closing chunk.
+func (a *StreamAssembler) doneData() map[string]interface{} {
+ if a.ReasoningSignature == "" && len(a.ReasoningMetadata) == 0 {
+ return nil
+ }
+ data := map[string]interface{}{}
+ if a.ReasoningSignature != "" {
+ data["reasoning_signature"] = a.ReasoningSignature
+ }
+ if len(a.ReasoningMetadata) > 0 {
+ data["reasoning_metadata"] = a.ReasoningMetadata
+ }
+ return data
+}
+
+// Process consumes one delta and emits the resulting stream responses. It
+// mirrors the event sequence of the original OpenAI stream loop so every
+// downstream consumer sees exactly what it saw before the protocol split.
+func (a *StreamAssembler) Process(ch chan<- types.StreamResponse, d Delta) {
+ isDone := d.FinishReason != ""
+ if isDone {
+ a.LastFinishReason = d.FinishReason
+ }
+
+ if len(d.ToolCalls) > 0 {
+ a.processToolCalls(ch, d.ToolCalls)
+ }
+
+ if isDone && d.FinishReason == "stop" && !a.firstToolCallSeen && !a.noToolCallStopLogged {
+ logger.Infof(a.ctx, "[LLM Stream] Natural-stop at protocol layer "+
+ "(finish=stop, tool_calls never observed, thinking_seen=%t, first_content_seen=%t, elapsed_ms=%d)",
+ a.active, a.firstContentSeen, a.elapsedMs())
+ a.noToolCallStopLogged = true
+ }
+
+ if d.Reasoning != "" {
+ if !a.firstReasoningSeen {
+ a.firstReasoningSeen = true
+ logger.Infof(a.ctx, "[LLM Stream] First reasoning chunk at protocol layer "+
+ "(len=%d, preview=%q, elapsed_ms=%d)",
+ len(d.Reasoning), TruncateForDebug(d.Reasoning, 80), a.elapsedMs())
+ }
+ a.Emit(ch, d.Reasoning)
+ }
+
+ if d.Content != "" {
+ if !a.firstContentSeen {
+ a.firstContentSeen = true
+ logger.Infof(a.ctx, "[LLM Stream] First content chunk at protocol layer "+
+ "(len=%d, preview=%q, tool_call_seen=%t, thinking_seen=%t, elapsed_ms=%d)",
+ len(d.Content), TruncateForDebug(d.Content, 80),
+ a.firstToolCallSeen, a.firstReasoningSeen, a.elapsedMs())
+ }
+ a.Finish(ch)
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeAnswer,
+ Content: d.Content,
+ Done: isDone,
+ ToolCalls: a.OrderedToolCalls(),
+ FinishReason: d.FinishReason,
+ })
+ }
+
+ if isDone && len(a.toolCallMap) > 0 {
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeAnswer,
+ Done: true,
+ ToolCalls: a.OrderedToolCalls(),
+ FinishReason: d.FinishReason,
+ })
+ }
+
+ if isDone {
+ a.Finish(ch)
+ }
+
+ if isDone && d.Content == "" && len(a.toolCallMap) == 0 {
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeAnswer,
+ Done: true,
+ FinishReason: d.FinishReason,
+ })
+ }
+}
+
+// Emit forwards a reasoning chunk through the cancellation-aware send,
+// shadowing the embedded ThinkingEmitter's blocking version.
+func (a *StreamAssembler) Emit(ch chan<- types.StreamResponse, content string) {
+ a.active = true
+ a.emit(ch, types.StreamResponse{ResponseType: types.ResponseTypeThinking, Content: content})
+}
+
+// Finish emits the single thinking-done marker if one is owed, through the
+// cancellation-aware send. Shadows the embedded ThinkingEmitter's version.
+func (a *StreamAssembler) Finish(ch chan<- types.StreamResponse) {
+ if !a.active {
+ return
+ }
+ a.active = false
+ a.emit(ch, types.StreamResponse{ResponseType: types.ResponseTypeThinking, Done: true})
+}
+
+// End emits the closing chunk once the vendor stream is exhausted. It logs
+// usage and carries the assembled tool calls, usage and reasoning artifacts.
+func (a *StreamAssembler) End(ch chan<- types.StreamResponse) {
+ a.Finish(ch)
+ LogUsage(a.ctx, a.model, a.Usage)
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeAnswer,
+ Done: true,
+ ToolCalls: a.OrderedToolCalls(),
+ Usage: a.Usage,
+ FinishReason: a.LastFinishReason,
+ Data: a.doneData(),
+ })
+}
+
+// Fail emits the error chunk for a broken stream.
+func (a *StreamAssembler) Fail(ch chan<- types.StreamResponse, err error) {
+ logger.Errorf(a.ctx, "Stream read error: %v (tool_calls_assembled=%d)", err, len(a.toolCallMap))
+ a.Finish(ch)
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeError,
+ Content: err.Error(),
+ Done: true,
+ ToolCalls: a.OrderedToolCalls(),
+ Usage: a.Usage,
+ FinishReason: types.FinishReasonIncomplete,
+ })
+}
+
+func (a *StreamAssembler) processToolCalls(ch chan<- types.StreamResponse, deltas []ToolCallDelta) {
+ if !a.firstToolCallSeen && len(deltas) > 0 {
+ a.firstToolCallSeen = true
+ var firstID, firstName string
+ for _, tc := range deltas {
+ if tc.ID != "" {
+ firstID = tc.ID
+ }
+ if tc.Name != "" {
+ firstName = tc.Name
+ }
+ if firstID != "" || firstName != "" {
+ break
+ }
+ }
+ logger.Infof(a.ctx, "[LLM Stream] First tool_calls delta at protocol layer "+
+ "(count=%d, first_id=%q, first_name=%q, first_content_seen=%t, thinking_seen=%t, elapsed_ms=%d)",
+ len(deltas), firstID, firstName, a.firstContentSeen, a.firstReasoningSeen, a.elapsedMs())
+ }
+
+ for _, tc := range deltas {
+ index := tc.Index
+ entry, exists := a.toolCallMap[index]
+ if !exists || entry == nil {
+ entry = &types.LLMToolCall{Type: tc.Type}
+ a.toolCallMap[index] = entry
+ }
+ if tc.ID != "" {
+ entry.ID = tc.ID
+ }
+ if tc.Type != "" {
+ entry.Type = tc.Type
+ }
+ if entry.Type == "" {
+ entry.Type = "function"
+ }
+ if tc.Name != "" {
+ // Some runtimes (vLLM Ascend) resend the full name on every chunk;
+ // treat an identical name as a repeat rather than a suffix.
+ if entry.Function.Name != tc.Name {
+ entry.Function.Name += tc.Name
+ }
+ }
+
+ argsUpdated := false
+ if tc.Arguments != "" {
+ entry.Function.Arguments += tc.Arguments
+ argsUpdated = true
+ }
+
+ currName := entry.Function.Name
+ var progressArgs map[string]any
+ if IsSandboxMutationTool(currName) && argsUpdated {
+ prog := a.fileProgress[index]
+ if prog == nil {
+ prog = NewSandboxFileProgress(currName)
+ a.fileProgress[index] = prog
+ }
+ if payload, ok := prog.Feed(tc.Arguments); ok {
+ progressArgs = payload
+ }
+ }
+
+ if currName != "" &&
+ currName == a.lastFunctionName[index] &&
+ argsUpdated &&
+ !a.nameNotified[index] &&
+ entry.ID != "" {
+ data := map[string]interface{}{
+ "tool_name": currName,
+ "tool_call_id": entry.ID,
+ }
+ if progressArgs != nil {
+ data["arguments"] = progressArgs
+ }
+ a.emit(ch, types.StreamResponse{ResponseType: types.ResponseTypeToolCall, Data: data})
+ a.nameNotified[index] = true
+ progressArgs = nil
+ } else if progressArgs != nil && entry.ID != "" && currName != "" {
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeToolCall,
+ Data: map[string]interface{}{
+ "tool_name": currName,
+ "tool_call_id": entry.ID,
+ "arguments": progressArgs,
+ },
+ })
+ }
+
+ a.lastFunctionName[index] = currName
+
+ if entry.Function.Name == "thinking" && argsUpdated {
+ extractor, exists := a.fieldExtractors[index]
+ if !exists {
+ extractor = NewJSONFieldExtractor("thought")
+ a.fieldExtractors[index] = extractor
+ }
+ if chunk := extractor.Feed(tc.Arguments); chunk != "" {
+ a.emit(ch, types.StreamResponse{
+ ResponseType: types.ResponseTypeThinking,
+ Content: chunk,
+ Data: map[string]interface{}{
+ "source": "thinking_tool",
+ "tool_call_id": entry.ID,
+ },
+ })
+ }
+ }
+ }
+}
+
+// TruncateForDebug shortens a string for log previews.
+func TruncateForDebug(s string, maxRunes int) string {
+ runes := []rune(s)
+ if len(runes) <= maxRunes {
+ return s
+ }
+ return string(runes[:maxRunes]) + fmt.Sprintf("...(%d chars)", len(runes))
+}
+
+// ReplaceToolCalls swaps the assembled tool calls for a protocol's own final
+// view (for example, one that drops calls the stream never closed).
+func (a *StreamAssembler) ReplaceToolCalls(calls []types.LLMToolCall) {
+ a.toolCallMap = make(map[int]*types.LLMToolCall, len(calls))
+ for i := range calls {
+ call := calls[i]
+ a.toolCallMap[i] = &call
+ }
+}
diff --git a/internal/models/api/stream_assembler_test.go b/internal/models/api/stream_assembler_test.go
new file mode 100644
index 000000000..b29b148f9
--- /dev/null
+++ b/internal/models/api/stream_assembler_test.go
@@ -0,0 +1,152 @@
+package api
+
+import (
+ "context"
+ "fmt"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// A consumer that walks away must not pin the producing goroutine forever.
+// Before the cancellation-aware send this blocked on `ch <-` for the life of
+// the process, leaking the goroutine, the HTTP body and the timeout context.
+func TestStreamAssembler_AbandonedConsumerDoesNotBlock(t *testing.T) {
+ ctx, cancel := context.WithCancel(context.Background())
+ a := NewStreamAssembler(ctx, "m")
+
+ ch := make(chan types.StreamResponse) // unbuffered, never read
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ a.Process(ch, Delta{Content: "hello"})
+ a.Process(ch, Delta{FinishReason: "stop"})
+ a.End(ch)
+ }()
+
+ // Let the producer park on the first send, then drop the consumer.
+ time.Sleep(20 * time.Millisecond)
+ cancel()
+
+ select {
+ case <-done:
+ case <-time.After(2 * time.Second):
+ t.Fatal("producer still blocked after the consumer went away")
+ }
+ if !a.Aborted() {
+ t.Fatal("Aborted() = false, want true after an abandoned send")
+ }
+}
+
+// An already-cancelled context must abort deterministically rather than
+// racing a ready channel.
+func TestStreamAssembler_CancelledContextAbortsImmediately(t *testing.T) {
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+ a := NewStreamAssembler(ctx, "m")
+
+ ch := make(chan types.StreamResponse, 8)
+ a.Process(ch, Delta{Content: "hello"})
+ a.End(ch)
+
+ if len(ch) != 0 {
+ t.Fatalf("emitted %d chunks into an abandoned stream, want 0", len(ch))
+ }
+ if !a.Aborted() {
+ t.Fatal("Aborted() = false, want true")
+ }
+}
+
+// The live path must keep the exact chunk sequence the engine expects:
+// thinking chunks, one thinking-done marker before the first answer token,
+// the answer, then the closing chunk.
+func TestStreamAssembler_ThinkingHandoffSequence(t *testing.T) {
+ a := NewStreamAssembler(context.Background(), "m")
+ ch := make(chan types.StreamResponse, 16)
+
+ a.Process(ch, Delta{Reasoning: "think"})
+ a.Process(ch, Delta{Content: "answer", FinishReason: "stop"})
+ a.End(ch)
+ close(ch)
+
+ type step struct {
+ kind types.ResponseType
+ done bool
+ text string
+ }
+ var got []step
+ for chunk := range ch {
+ got = append(got, step{chunk.ResponseType, chunk.Done, chunk.Content})
+ }
+ want := []step{
+ {types.ResponseTypeThinking, false, "think"},
+ {types.ResponseTypeThinking, true, ""},
+ {types.ResponseTypeAnswer, true, "answer"},
+ {types.ResponseTypeAnswer, true, ""},
+ }
+ if len(got) != len(want) {
+ t.Fatalf("sequence = %#v, want %#v", got, want)
+ }
+ for i := range want {
+ if got[i] != want[i] {
+ t.Fatalf("chunk %d = %#v, want %#v", i, got[i], want[i])
+ }
+ }
+}
+
+// Tool-call indices belong to the vendor: gateways number from 1 and parallel
+// calls arrive with gaps. Walking 0..len(map) dropped every call outside that
+// range, and a round whose calls vanish reaches the agent as a plain answer.
+func TestStreamAssembler_OrderedToolCallsNonContiguousIndices(t *testing.T) {
+ cases := []struct {
+ name string
+ indices []int
+ want []string
+ }{
+ {name: "zero based", indices: []int{0, 1}, want: []string{"f0", "f1"}},
+ {name: "one based", indices: []int{1, 2}, want: []string{"f1", "f2"}},
+ {name: "gapped", indices: []int{0, 3, 7}, want: []string{"f0", "f3", "f7"}},
+ {name: "out of order arrival", indices: []int{5, 2}, want: []string{"f2", "f5"}},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ a := NewStreamAssembler(context.Background(), "m")
+ ch := make(chan types.StreamResponse, 64)
+ for _, idx := range tc.indices {
+ a.Process(ch, Delta{ToolCalls: []ToolCallDelta{{
+ Index: idx,
+ ID: fmt.Sprintf("call_%d", idx),
+ Name: fmt.Sprintf("f%d", idx),
+ Arguments: `{}`,
+ }}})
+ }
+
+ calls := a.OrderedToolCalls()
+ if len(calls) != len(tc.want) {
+ t.Fatalf("got %d calls %#v, want %d", len(calls), calls, len(tc.want))
+ }
+ for i, name := range tc.want {
+ if calls[i].Function.Name != name {
+ t.Fatalf("call %d = %q, want %q (order must follow the vendor index)",
+ i, calls[i].Function.Name, name)
+ }
+ }
+ })
+ }
+}
+
+// Metadata-only entries (a thought signature that arrives before its call)
+// are kept too, whatever index the vendor gave them.
+func TestStreamAssembler_OrderedToolCallsIncludesMetadataOnlyIndex(t *testing.T) {
+ a := NewStreamAssembler(context.Background(), "m")
+ a.SetToolCallMetadata(4, types.ToolCallMetadata{"thought_signature": []byte(`"sig"`)})
+
+ calls := a.OrderedToolCalls()
+ if len(calls) != 1 {
+ t.Fatalf("got %d calls, want 1", len(calls))
+ }
+ if calls[0].ProviderMetadata["thought_signature"] == nil {
+ t.Fatal("provider metadata lost")
+ }
+}
diff --git a/internal/models/chat/stream_emit.go b/internal/models/api/thinking_emitter.go
similarity index 67%
rename from internal/models/chat/stream_emit.go
rename to internal/models/api/thinking_emitter.go
index b3c6c4cd7..9c6c4fc9b 100644
--- a/internal/models/chat/stream_emit.go
+++ b/internal/models/api/thinking_emitter.go
@@ -1,19 +1,19 @@
-package chat
+package api
import "github.com/Tencent/WeKnora/internal/types"
-// thinkingEmitter owns the "reasoning then answer" hand-off that every
+// ThinkingEmitter owns the "reasoning then answer" hand-off that every
// streaming Chat implementation shares: thinking chunks are forwarded as they
// arrive, and exactly one thinking-done marker is emitted before the first
// answer token (or when the stream ends without one). Centralizing the
// bookkeeping keeps the OpenAI-compatible and Ollama stream loops in sync.
-type thinkingEmitter struct {
+type ThinkingEmitter struct {
active bool
}
-// emit forwards a reasoning chunk and records that a thinking-done marker is
+// Emit forwards a reasoning chunk and records that a thinking-done marker is
// still owed.
-func (e *thinkingEmitter) emit(ch chan types.StreamResponse, content string) {
+func (e *ThinkingEmitter) Emit(ch chan<- types.StreamResponse, content string) {
e.active = true
ch <- types.StreamResponse{
ResponseType: types.ResponseTypeThinking,
@@ -22,9 +22,9 @@ func (e *thinkingEmitter) emit(ch chan types.StreamResponse, content string) {
}
}
-// finish emits the single thinking-done marker if one is owed. Safe to call
+// Finish emits the single thinking-done marker if one is owed. Safe to call
// multiple times; only the first call after an emit sends anything.
-func (e *thinkingEmitter) finish(ch chan types.StreamResponse) {
+func (e *ThinkingEmitter) Finish(ch chan<- types.StreamResponse) {
if !e.active {
return
}
diff --git a/internal/models/chat/transport.go b/internal/models/api/transport.go
similarity index 73%
rename from internal/models/chat/transport.go
rename to internal/models/api/transport.go
index 91b3dc26c..603a01714 100644
--- a/internal/models/chat/transport.go
+++ b/internal/models/api/transport.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"context"
@@ -17,8 +17,8 @@ import (
// - WEKNORA_LLM_CHAT_TIMEOUT_SECONDS 非流式调用兜底超时(默认 600s)
// - WEKNORA_LLM_STREAM_TIMEOUT_SECONDS 流式调用兜底超时(默认 1800s)
var (
- defaultChatTimeout = envDurationSeconds("WEKNORA_LLM_CHAT_TIMEOUT_SECONDS", 300*time.Second)
- defaultStreamTimeout = envDurationSeconds("WEKNORA_LLM_STREAM_TIMEOUT_SECONDS", 600*time.Second)
+ DefaultChatTimeout = envDurationSeconds("WEKNORA_LLM_CHAT_TIMEOUT_SECONDS", 300*time.Second)
+ DefaultStreamTimeout = envDurationSeconds("WEKNORA_LLM_STREAM_TIMEOUT_SECONDS", 600*time.Second)
)
// envDurationSeconds 读取以"秒"为单位的环境变量,解析失败或非正值时回退到 fallback。
@@ -34,21 +34,21 @@ func envDurationSeconds(key string, fallback time.Duration) time.Duration {
return time.Duration(n) * time.Second
}
-// withLLMTimeout 仅在上层 ctx 没有 deadline 时附加一个兜底超时;
+// WithLLMTimeout 仅在上层 ctx 没有 deadline 时附加一个兜底超时;
// 如果上层已显式设置 deadline(无论更短或更长),则原样返回,
// 让调用方对自己的超时策略拥有最终决定权。
-func withLLMTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
+func WithLLMTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
if _, ok := ctx.Deadline(); ok {
return ctx, func() {}
}
return context.WithTimeout(ctx, d)
}
-// rawHTTPClient is a shared HTTP client for raw HTTP LLM calls with connection-level timeouts.
-// Per-request timeout is enforced via context deadline (see defaultChatTimeout / defaultStreamTimeout)
+// HTTPClient is a shared HTTP client for raw HTTP LLM calls with connection-level timeouts.
+// Per-request timeout is enforced via context deadline (see DefaultChatTimeout / DefaultStreamTimeout)
// rather than http.Client.Timeout, so streaming calls are not prematurely terminated.
// Uses SSRFSafeDialContext to prevent DNS rebinding attacks at the connection layer.
-var rawHTTPTransport = &http.Transport{
+var httpTransport = &http.Transport{
Proxy: http.ProxyFromEnvironment,
DialContext: secutils.SSRFSafeDialContext,
TLSHandshakeTimeout: 10 * time.Second,
@@ -56,7 +56,8 @@ var rawHTTPTransport = &http.Transport{
MaxIdleConnsPerHost: 5,
}
-var rawHTTPClient = secutils.NewSSRFSafeHTTPClientWithTransport(
+// HTTPClient is the shared SSRF-safe client every protocol uses.
+var HTTPClient = secutils.NewSSRFSafeHTTPClientWithTransport(
secutils.SSRFSafeHTTPClientConfig{Timeout: 0, MaxRedirects: 10},
- rawHTTPTransport,
+ httpTransport,
)
diff --git a/internal/models/chat/timeout_test.go b/internal/models/api/transport_test.go
similarity index 91%
rename from internal/models/chat/timeout_test.go
rename to internal/models/api/transport_test.go
index 3b3fd1036..a5ca0b50a 100644
--- a/internal/models/chat/timeout_test.go
+++ b/internal/models/api/transport_test.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"context"
@@ -8,7 +8,7 @@ import (
)
func TestWithLLMTimeout_NoParentDeadline_AppliesDefault(t *testing.T) {
- ctx, cancel := withLLMTimeout(context.Background(), 50*time.Millisecond)
+ ctx, cancel := WithLLMTimeout(context.Background(), 50*time.Millisecond)
defer cancel()
dl, ok := ctx.Deadline()
@@ -24,7 +24,7 @@ func TestWithLLMTimeout_ShorterParentDeadline_Respected(t *testing.T) {
parent, parentCancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
defer parentCancel()
- ctx, cancel := withLLMTimeout(parent, 10*time.Second)
+ ctx, cancel := WithLLMTimeout(parent, 10*time.Second)
defer cancel()
dl, _ := ctx.Deadline()
@@ -37,7 +37,7 @@ func TestWithLLMTimeout_LongerParentDeadline_NotTruncated(t *testing.T) {
parent, parentCancel := context.WithTimeout(context.Background(), 10*time.Second)
defer parentCancel()
- ctx, cancel := withLLMTimeout(parent, 50*time.Millisecond)
+ ctx, cancel := WithLLMTimeout(parent, 50*time.Millisecond)
defer cancel()
dl, ok := ctx.Deadline()
diff --git a/internal/models/api/types.go b/internal/models/api/types.go
new file mode 100644
index 000000000..ae37d9ec9
--- /dev/null
+++ b/internal/models/api/types.go
@@ -0,0 +1,304 @@
+// Package api holds the protocol-neutral request model shared by every wire
+// protocol implementation (OpenAI Chat Completions, OpenAI Responses,
+// Anthropic Messages, Google Generative AI, Ollama) plus the helpers those
+// implementations share: SSE reading, the SSRF-safe transport, streaming
+// tool-call assembly, prompt-cache bookkeeping and usage logging.
+//
+// Protocol packages live under api/<protocol>; vendor facts live in
+// internal/models/catalog and internal/models/vendors. This package must not
+// import either of them.
+package api
+
+import (
+ "encoding/json"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// API identifies a wire protocol. It is the value of the "api" field in a
+// vendor's models.json and decides which protocol package talks to the
+// endpoint.
+type API string
+
+const (
+ // APIOpenAICompletions is the OpenAI Chat Completions protocol, the
+ // lingua franca of almost every third-party vendor.
+ APIOpenAICompletions API = "openai-completions"
+ // APIOpenAIResponses is the OpenAI Responses protocol.
+ APIOpenAIResponses API = "openai-responses"
+ // APIAnthropicMessages is the Anthropic Messages protocol, also exposed by
+ // MiniMax, Zhipu and Moonshot as a compatibility surface.
+ APIAnthropicMessages API = "anthropic-messages"
+ // APIGoogleGenerativeAI is the native Gemini generateContent protocol.
+ APIGoogleGenerativeAI API = "google-generative-ai"
+ // APIOllama is the local Ollama chat protocol.
+ APIOllama API = "ollama"
+)
+
+// Known reports whether the API value names a protocol this build ships.
+func (a API) Known() bool {
+ switch a {
+ case APIOpenAICompletions, APIOpenAIResponses, APIAnthropicMessages, APIGoogleGenerativeAI, APIOllama:
+ return true
+ }
+ return false
+}
+
+// Tool represents a function/tool definition
+type Tool struct {
+ Type string `json:"type"` // "function"
+ Function FunctionDef `json:"function"`
+}
+
+// FunctionDef represents a function definition
+type FunctionDef struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
+ Parameters json.RawMessage `json:"parameters"`
+}
+
+// MessageContentPart represents a part of multi-content message
+type MessageContentPart struct {
+ Type string `json:"type"` // "text" or "image_url"
+ Text string `json:"text,omitempty"` // For type="text"
+ ImageURL *ImageURL `json:"image_url,omitempty"` // For type="image_url"
+}
+
+// ImageURL represents the image URL structure
+type ImageURL struct {
+ URL string `json:"url"` // URL or base64 data URI
+ Detail string `json:"detail,omitempty"` // "auto", "low", "high"
+}
+
+// MessageKind marks messages the engine synthesized rather than received from
+// the user or the model. Compaction needs to tell its own summary apart from a
+// real user turn: a summary that looks like ordinary history gets fed back into
+// the next summarization pass and degrades into a summary of a summary.
+type MessageKind string
+
+// MessageKindCompactionSummary marks the message that replaces compacted
+// history. It carries the `user` role because that is where providers expect
+// conversation history, so the role alone cannot identify it.
+const MessageKindCompactionSummary MessageKind = "compaction_summary"
+
+// Message 表示聊天消息
+type Message struct {
+ Role string `json:"role"` // 角色:system, user, assistant, tool
+ Content string `json:"content"` // 消息内容
+ MultiContent []MessageContentPart `json:"multi_content,omitempty"` // 多内容消息(文本+图片)
+ Name string `json:"name,omitempty"` // Function/tool name (for tool role)
+ ToolCallID string `json:"tool_call_id,omitempty"` // Tool call ID (for tool role)
+ ToolCalls []ToolCall `json:"tool_calls,omitempty"` // Tool calls (for assistant role)
+ // Images are image URLs for multimodal input (current user message only).
+ Images []string `json:"images,omitempty"`
+ // ReasoningContent 是 assistant 推理类模型上一轮输出的思考内容。部分供应商
+ // (MiMo、DeepSeek V3.2+、Kimi K2.5+)要求多轮对话中把 assistant 的
+ // reasoning_content 原样回传,否则会以 400 拒绝请求;其他不要求的供应商会
+ // 忽略未知字段。Anthropic 则要求把 thinking block 连同签名一起回放。
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ // ReasoningSignature is the provider-issued signature that must accompany
+ // ReasoningContent when it is replayed (Anthropic thinking blocks, Gemini
+ // thought signatures on text parts). Empty when the provider issues none.
+ ReasoningSignature string `json:"reasoning_signature,omitempty"`
+ // ReasoningMetadata carries opaque provider state that must round-trip
+ // with the assistant turn but has no protocol-neutral representation:
+ // OpenAI Responses reasoning items (encrypted_content), OpenRouter
+ // reasoning_details, and so on. Keyed by protocol / vendor namespace.
+ ReasoningMetadata types.ProviderMetadata `json:"reasoning_metadata,omitempty"`
+ // Kind is engine-internal bookkeeping. `json:"-"` keeps it off the wire:
+ // providers reject unknown message fields on some endpoints, and this one
+ // means nothing to them anyway.
+ Kind MessageKind `json:"-"`
+ // TurnID is the stored assistant message whose turn this history message
+ // was replayed from. It is empty for the live turn and for messages the
+ // engine synthesized. Compaction uses it to tell whether a summary ends
+ // exactly on a stored turn, the only kind it can persist for later turns.
+ // Engine-internal like Kind, and kept off the wire for the same reason.
+ TurnID string `json:"-"`
+}
+
+// ToolCall represents a tool call in a message
+type ToolCall struct {
+ ID string `json:"id"`
+ Type string `json:"type"` // "function"
+ Function FunctionCall `json:"function"`
+ ProviderMetadata types.ToolCallMetadata `json:"provider_metadata,omitempty"`
+}
+
+// FunctionCall represents a function call
+type FunctionCall struct {
+ Name string `json:"name"`
+ Arguments string `json:"arguments"` // JSON string
+}
+
+// ReasoningEffort is the protocol-neutral thinking level. Vendors map it onto
+// their own vocabulary through a ThinkingLevelMap; the protocol package then
+// emits whichever wire field the vendor documents (reasoning_effort,
+// thinking.type, enable_thinking, thinkingConfig, ...).
+type ReasoningEffort string
+
+const (
+ // ReasoningOff disables extended thinking where the model allows it.
+ ReasoningOff ReasoningEffort = "off"
+ // ReasoningAuto enables thinking but leaves the intensity to the provider
+ // default. This is what the legacy boolean `thinking: true` maps to.
+ ReasoningAuto ReasoningEffort = "auto"
+ // ReasoningMinimal is the weakest graded level.
+ ReasoningMinimal ReasoningEffort = "minimal"
+ // ReasoningLow is the low graded level.
+ ReasoningLow ReasoningEffort = "low"
+ // ReasoningMedium is the medium graded level.
+ ReasoningMedium ReasoningEffort = "medium"
+ // ReasoningHigh is the high graded level.
+ ReasoningHigh ReasoningEffort = "high"
+ // ReasoningXHigh is the extra-high graded level (OpenAI, Zhipu).
+ ReasoningXHigh ReasoningEffort = "xhigh"
+ // ReasoningMax is the strongest graded level.
+ ReasoningMax ReasoningEffort = "max"
+)
+
+// ReasoningLadder lists the graded levels from weakest to strongest. Off and
+// Auto are deliberately excluded: they are switches, not intensities.
+var ReasoningLadder = []ReasoningEffort{
+ ReasoningMinimal, ReasoningLow, ReasoningMedium, ReasoningHigh, ReasoningXHigh, ReasoningMax,
+}
+
+// AllReasoningEfforts is every accepted value, in UI order.
+var AllReasoningEfforts = append([]ReasoningEffort{ReasoningOff, ReasoningAuto}, ReasoningLadder...)
+
+// ParseReasoningEffort validates a user-provided level. Empty input yields
+// ("", true) meaning "unset: let the model default apply".
+func ParseReasoningEffort(s string) (ReasoningEffort, bool) {
+ if s == "" {
+ return "", true
+ }
+ for _, level := range AllReasoningEfforts {
+ if string(level) == s {
+ return level, true
+ }
+ }
+ // Accept a few aliases the legacy boolean UI and provider docs use.
+ switch s {
+ case "none", "false", "disabled":
+ return ReasoningOff, true
+ case "true", "enabled", "default", "on":
+ return ReasoningAuto, true
+ }
+ return "", false
+}
+
+// Enabled reports whether the level asks for thinking to be on.
+func (r ReasoningEffort) Enabled() bool {
+ return r != "" && r != ReasoningOff
+}
+
+// Graded reports whether the level is one of the intensity rungs.
+func (r ReasoningEffort) Graded() bool {
+ for _, level := range ReasoningLadder {
+ if level == r {
+ return true
+ }
+ }
+ return false
+}
+
+// ThinkingLevelMap maps protocol-neutral levels to a vendor's own vocabulary.
+//
+// Semantics mirror Pi's thinkingLevelMap:
+// - a missing key means "supported, pass the level name through" for
+// minimal/low/medium/high and "unsupported" for xhigh/max;
+// - a null value marks the level as unsupported (the caller clamps to the
+// nearest supported rung);
+// - a string value is what the vendor expects on the wire.
+//
+// The special key "off" may be mapped to null to state that thinking cannot
+// be switched off (always-on reasoning models).
+type ThinkingLevelMap map[ReasoningEffort]*string
+
+// Supports reports whether the level is usable for this model.
+func (m ThinkingLevelMap) Supports(level ReasoningEffort) bool {
+ if v, ok := m[level]; ok {
+ return v != nil
+ }
+ switch level {
+ case ReasoningXHigh, ReasoningMax:
+ return false
+ case ReasoningOff, ReasoningAuto:
+ return true
+ }
+ return true
+}
+
+// Value returns the vendor value for a supported level. Unmapped levels
+// pass through under their own name.
+func (m ThinkingLevelMap) Value(level ReasoningEffort) string {
+ if v, ok := m[level]; ok && v != nil {
+ return *v
+ }
+ return string(level)
+}
+
+// Clamp returns the nearest supported graded level: first upward, then
+// downward, mirroring Pi's clampThinkingLevel. Off/Auto are returned as-is
+// (Off may still be unsupported; callers check Supports(ReasoningOff)).
+func (m ThinkingLevelMap) Clamp(level ReasoningEffort) ReasoningEffort {
+ if !level.Graded() {
+ return level
+ }
+ if m.Supports(level) {
+ return level
+ }
+ idx := -1
+ for i, l := range ReasoningLadder {
+ if l == level {
+ idx = i
+ break
+ }
+ }
+ for i := idx + 1; i < len(ReasoningLadder); i++ {
+ if m.Supports(ReasoningLadder[i]) {
+ return ReasoningLadder[i]
+ }
+ }
+ for i := idx - 1; i >= 0; i-- {
+ if m.Supports(ReasoningLadder[i]) {
+ return ReasoningLadder[i]
+ }
+ }
+ return ReasoningAuto
+}
+
+// SupportedLevels lists the levels this map accepts, in UI order.
+func (m ThinkingLevelMap) SupportedLevels() []ReasoningEffort {
+ out := make([]ReasoningEffort, 0, len(AllReasoningEfforts))
+ for _, level := range AllReasoningEfforts {
+ if m.Supports(level) {
+ out = append(out, level)
+ }
+ }
+ return out
+}
+
+// StringPtr is a small helper for building ThinkingLevelMap literals.
+func StringPtr(s string) *string { return &s }
+
+// TagSignature records which protocol issued a reasoning signature. Stored
+// signatures are opaque to every other provider, so they must only be
+// replayed to the protocol that produced them.
+func TagSignature(protocol API, signature string) string {
+ if signature == "" {
+ return ""
+ }
+ return string(protocol) + ":" + signature
+}
+
+// SignatureFor returns the raw signature when it was issued by protocol, and
+// "" for signatures from another protocol or without a protocol tag.
+func SignatureFor(protocol API, tagged string) string {
+ prefix := string(protocol) + ":"
+ if !strings.HasPrefix(tagged, prefix) {
+ return ""
+ }
+ return strings.TrimPrefix(tagged, prefix)
+}
diff --git a/internal/models/api/usage.go b/internal/models/api/usage.go
new file mode 100644
index 000000000..8abb31f4c
--- /dev/null
+++ b/internal/models/api/usage.go
@@ -0,0 +1,73 @@
+package api
+
+import "github.com/Tencent/WeKnora/internal/types"
+
+// OpenAIUsage is the superset of the usage shapes OpenAI-compatible
+// endpoints return. Vendors disagree on where cache counters live:
+// - OpenAI / Azure / most gateways: prompt_tokens_details.cached_tokens
+// - DeepSeek: prompt_cache_hit_tokens / prompt_cache_miss_tokens
+// - Kimi: top-level cached_tokens
+// - Anthropic-through-OpenRouter: cache_read_input_tokens / cache_creation_input_tokens
+//
+// All of them are decoded here so protocol code never guesses per vendor.
+type OpenAIUsage struct {
+ PromptTokens int `json:"prompt_tokens"`
+ CompletionTokens int `json:"completion_tokens"`
+ TotalTokens int `json:"total_tokens"`
+ PromptCacheHitTokens *int `json:"prompt_cache_hit_tokens"`
+ PromptCacheMissTokens *int `json:"prompt_cache_miss_tokens"`
+ CachedTokens *int `json:"cached_tokens"`
+ CacheReadInputTokens *int `json:"cache_read_input_tokens"`
+ CacheCreationInputTokens *int `json:"cache_creation_input_tokens"`
+ PromptTokensDetails *struct {
+ CachedTokens *int `json:"cached_tokens"`
+ CacheWriteTokens *int `json:"cache_write_tokens"`
+ } `json:"prompt_tokens_details"`
+ CompletionTokensDetails *struct {
+ ReasoningTokens int `json:"reasoning_tokens"`
+ } `json:"completion_tokens_details"`
+}
+
+// ToTokenUsage normalizes the counters. cacheAccounting states whether the
+// vendor documents prompt-cache accounting at all: when it does not, a
+// missing counter means "unsupported" rather than "unreported".
+func (u OpenAIUsage) ToTokenUsage(cacheAccounting bool) types.TokenUsage {
+ out := types.TokenUsage{
+ PromptTokens: u.PromptTokens,
+ CompletionTokens: u.CompletionTokens,
+ TotalTokens: u.TotalTokens,
+ }
+ if out.TotalTokens == 0 {
+ out.TotalTokens = out.PromptTokens + out.CompletionTokens
+ }
+ switch {
+ case u.PromptCacheHitTokens != nil || u.PromptCacheMissTokens != nil:
+ read := valueOrZero(u.PromptCacheHitTokens)
+ miss := valueOrZero(u.PromptCacheMissTokens)
+ out.SetPromptCacheUsage(read, 0, miss, true)
+ case u.CacheReadInputTokens != nil || u.CacheCreationInputTokens != nil:
+ read := valueOrZero(u.CacheReadInputTokens)
+ write := valueOrZero(u.CacheCreationInputTokens)
+ out.SetPromptCacheUsage(read, write, max(0, u.PromptTokens-read), true)
+ case u.PromptTokensDetails != nil &&
+ (u.PromptTokensDetails.CachedTokens != nil || u.PromptTokensDetails.CacheWriteTokens != nil):
+ read := valueOrZero(u.PromptTokensDetails.CachedTokens)
+ write := valueOrZero(u.PromptTokensDetails.CacheWriteTokens)
+ out.SetPromptCacheUsage(read, write, max(0, u.PromptTokens-read), true)
+ case u.CachedTokens != nil:
+ read := valueOrZero(u.CachedTokens)
+ out.SetPromptCacheUsage(read, 0, max(0, u.PromptTokens-read), true)
+ case cacheAccounting:
+ out.SetPromptCacheUsage(0, 0, 0, false)
+ default:
+ out.MarkPromptCacheUnsupported()
+ }
+ return out
+}
+
+func valueOrZero(value *int) int {
+ if value == nil {
+ return 0
+ }
+ return *value
+}
diff --git a/internal/models/chat/usage.go b/internal/models/api/usage_log.go
similarity index 92%
rename from internal/models/chat/usage.go
rename to internal/models/api/usage_log.go
index a7605a1a8..9ef18a3a9 100644
--- a/internal/models/chat/usage.go
+++ b/internal/models/api/usage_log.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"context"
@@ -8,10 +8,10 @@ import (
"github.com/Tencent/WeKnora/internal/types"
)
-// logUsage emits the standard "[LLM Usage]" line shared by every Chat
+// LogUsage emits the standard "[LLM Usage]" line shared by every Chat
// implementation. It is a no-op when usage is nil so callers can pass through
// optional usage blocks without guarding at each call site.
-func logUsage(ctx context.Context, model string, u *types.TokenUsage) {
+func LogUsage(ctx context.Context, model string, u *types.TokenUsage) {
if u == nil {
return
}
diff --git a/internal/models/chat/usage_attribution_test.go b/internal/models/api/usage_log_test.go
similarity index 98%
rename from internal/models/chat/usage_attribution_test.go
rename to internal/models/api/usage_log_test.go
index 0425260a5..a9c01cac3 100644
--- a/internal/models/chat/usage_attribution_test.go
+++ b/internal/models/api/usage_log_test.go
@@ -1,4 +1,4 @@
-package chat
+package api
import (
"context"
diff --git a/internal/models/catalog/catalog_test.go b/internal/models/catalog/catalog_test.go
new file mode 100644
index 000000000..e27711f4b
--- /dev/null
+++ b/internal/models/catalog/catalog_test.go
@@ -0,0 +1,309 @@
+package catalog
+
+import (
+ "encoding/json"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func registerTestVendors(t *testing.T) {
+ t.Helper()
+ t.Cleanup(reset())
+ Register(&Vendor{
+ ID: GenericID, Name: "Custom", API: api.APIOpenAICompletions,
+ DefaultBaseURLs: map[types.ModelType]string{},
+ ModelTypes: []types.ModelType{types.ModelTypeKnowledgeQA},
+ Compat: VendorCompat{OpenAICompletions: OpenAICompletionsCompat{
+ MaxTokensField: Ptr("max_tokens"), ThinkingFormat: Ptr(ThinkingFormatChatTemplateKwargs),
+ }},
+ })
+ Register(&Vendor{
+ ID: "acme", Name: "Acme", Names: map[string]string{"zh-CN": "极目"},
+ API: api.APIOpenAICompletions,
+ RequiresAuth: true,
+ URLPatterns: []string{"api.acme.ai", "acme"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: "https://api.acme.ai/v1",
+ types.ModelTypeRerank: "https://api.acme.ai/rerank",
+ },
+ ModelTypes: []types.ModelType{types.ModelTypeKnowledgeQA, types.ModelTypeRerank},
+ Compat: VendorCompat{OpenAICompletions: OpenAICompletionsCompat{
+ ThinkingFormat: Ptr(ThinkingFormatThinkingType),
+ SupportsReasoningEffort: Ptr(true),
+ MaxTokensField: Ptr("max_tokens"),
+ }},
+ ThinkingLevels: api.ThinkingLevelMap{api.ReasoningMax: api.StringPtr("max")},
+ Models: []ModelSpec{
+ {
+ ID: "acme-pro", Name: "Acme Pro", Reasoning: true,
+ Input: []string{"text", "image"}, ContextWindow: 200000,
+ Compat: json.RawMessage(`{"supports_temperature": false}`),
+ },
+ {ID: "acme-r1", Reasoning: true, ThinkingLevels: api.ThinkingLevelMap{api.ReasoningOff: nil}},
+ {Match: "acme-lite*", Reasoning: false, Compat: json.RawMessage(`{"thinking_format": "none"}`)},
+ {Match: "acme-lite-vision*", Input: []string{"text", "image"}},
+ {ID: "acme-embed", Type: types.ModelTypeEmbedding, Dimension: 1024},
+ {
+ ID: "acme-claude", API: api.APIAnthropicMessages, Reasoning: true,
+ Compat: json.RawMessage(`{"thinking_mode": "adaptive", "supports_effort": true}`),
+ },
+ },
+ })
+ Register(&Vendor{
+ ID: "tencent-lkeap", Name: "LKEAP", API: api.APIOpenAICompletions,
+ URLPatterns: []string{"api.lkeap.cloud.tencent.com", "tencent"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: "https://api.lkeap.cloud.tencent.com/v1",
+ },
+ ModelTypes: []types.ModelType{types.ModelTypeKnowledgeQA},
+ })
+}
+
+func TestFindModel_ExactAliasAndGlob(t *testing.T) {
+ registerTestVendors(t)
+ v, _ := Get("acme")
+
+ m, ok := v.FindModel("ACME-PRO")
+ require.True(t, ok)
+ assert.Equal(t, "acme-pro", m.ID)
+
+ m, ok = v.FindModel("acme-lite-2")
+ require.True(t, ok)
+ assert.Equal(t, "acme-lite*", m.Match)
+
+ m, ok = v.FindModel("acme-lite-vision-2")
+ require.True(t, ok, "longest literal prefix wins")
+ assert.Equal(t, "acme-lite-vision*", m.Match)
+
+ _, ok = v.FindModel("unknown")
+ assert.False(t, ok)
+}
+
+func TestDetectByURL_LongestPatternWins(t *testing.T) {
+ registerTestVendors(t)
+ assert.Equal(t, "tencent-lkeap", DetectByURL("https://api.lkeap.cloud.tencent.com/v1"))
+ assert.Equal(t, "acme", DetectByURL("https://api.acme.ai/v1"))
+ assert.Equal(t, GenericID, DetectByURL("http://localhost:8000/v1"))
+ assert.Equal(t, GenericID, DetectByURL(""))
+}
+
+func TestResolve_MergesVendorModelAndOverrideLayers(t *testing.T) {
+ registerTestVendors(t)
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-pro"})
+ require.NoError(t, err)
+ assert.True(t, r.Cataloged)
+ assert.Equal(t, api.APIOpenAICompletions, r.API)
+ assert.Equal(t, "https://api.acme.ai/v1", r.BaseURL, "default base URL is filled in")
+ assert.Equal(t, "max_tokens", r.OpenAICompletions.MaxTokensField)
+ assert.Equal(t, ThinkingFormatThinkingType, r.OpenAICompletions.ThinkingFormat)
+ assert.True(t, r.OpenAICompletions.SupportsReasoningEffort)
+ assert.False(t, r.OpenAICompletions.SupportsTemperature, "model compat overrides the protocol default")
+ assert.True(t, r.OpenAICompletions.SupportsUsageInStreaming, "untouched defaults survive")
+ assert.Equal(t, "max", r.ThinkingLevels.Value(api.ReasoningMax))
+ assert.True(t, r.ThinkingLevels.Supports(api.ReasoningMax))
+ assert.Equal(t, 200000, r.Spec.ContextWindow)
+
+ caps := r.Capabilities()
+ assert.True(t, caps.Reasoning)
+ assert.Equal(t, []string{"text", "image"}, caps.Input)
+ assert.Contains(t, caps.ThinkingLevels, api.ReasoningOff)
+ assert.Contains(t, caps.ThinkingLevels, api.ReasoningMax)
+
+ // Row-level override wins over everything.
+ on := true
+ r, err = Resolve(Ref{
+ Provider: "acme", Model: "acme-pro", BaseURL: "https://proxy.example.com/v1/",
+ Override: &types.ModelSpecOverride{
+ ContextWindow: 1000,
+ Reasoning: &on,
+ ThinkingLevels: map[string]*string{"off": nil},
+ Compat: map[string]any{"supports_temperature": true, "max_tokens_field": "max_completion_tokens"},
+ },
+ })
+ require.NoError(t, err)
+ assert.Equal(t, "https://proxy.example.com/v1", r.BaseURL, "trailing slash trimmed, override kept")
+ assert.Equal(t, 1000, r.Spec.ContextWindow)
+ assert.True(t, r.OpenAICompletions.SupportsTemperature)
+ assert.Equal(t, "max_completion_tokens", r.OpenAICompletions.MaxTokensField)
+ assert.False(t, r.ThinkingLevels.Supports(api.ReasoningOff))
+}
+
+func TestResolve_UnknownModelAndVendorDegradeToGeneric(t *testing.T) {
+ registerTestVendors(t)
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "brand-new"})
+ require.NoError(t, err)
+ assert.False(t, r.Cataloged)
+ assert.Equal(t, "brand-new", r.Spec.ID)
+ assert.Equal(t, ThinkingFormatThinkingType, r.OpenAICompletions.ThinkingFormat, "vendor defaults still apply")
+
+ r, err = Resolve(Ref{Provider: "nope", Model: "x", BaseURL: "http://localhost:8000/v1"})
+ require.NoError(t, err)
+ assert.Equal(t, GenericID, r.Vendor.ID)
+ assert.Equal(t, ThinkingFormatChatTemplateKwargs, r.OpenAICompletions.ThinkingFormat)
+
+ r, err = Resolve(Ref{Model: "x", BaseURL: "https://api.acme.ai/v1"})
+ require.NoError(t, err)
+ assert.Equal(t, "acme", r.Vendor.ID, "provider detected from URL when empty")
+}
+
+func TestResolve_ProtocolInference(t *testing.T) {
+ registerTestVendors(t)
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-claude"})
+ require.NoError(t, err)
+ assert.Equal(t, api.APIAnthropicMessages, r.API)
+ assert.Equal(t, AnthropicThinkingAdaptive, r.AnthropicMessages.ThinkingMode)
+ assert.True(t, r.AnthropicMessages.SupportsEffort)
+ assert.Equal(t, "thinking.adaptive", r.Capabilities().ThinkingFormat)
+
+ r, err = Resolve(Ref{Provider: "acme", Model: "acme-pro", BaseURL: "https://api.acme.ai/anthropic"})
+ require.NoError(t, err)
+ assert.Equal(t, api.APIAnthropicMessages, r.API, "/anthropic suffix switches protocol")
+
+ r, err = Resolve(Ref{Provider: "acme", Model: "acme-pro", Extra: map[string]string{ExtraAPI: "openai-responses"}})
+ require.NoError(t, err)
+ assert.Equal(t, api.APIOpenAIResponses, r.API, "extra_config.api forces the protocol")
+
+ _, err = Resolve(Ref{Provider: "acme", Model: "acme-pro", Extra: map[string]string{ExtraAPI: "bogus"}})
+ require.Error(t, err)
+}
+
+func TestResolve_LegacyThinkingControlAndRemoteModelName(t *testing.T) {
+ registerTestVendors(t)
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-pro", Extra: map[string]string{
+ ExtraThinkingControl: "enable_thinking",
+ ExtraRemoteModelName: "acme-pro-2026",
+ }})
+ require.NoError(t, err)
+ assert.Equal(t, ThinkingFormatEnableThinking, r.OpenAICompletions.ThinkingFormat)
+ assert.Equal(t, "acme-pro-2026", r.RemoteModel)
+
+ r, err = Resolve(Ref{Provider: "acme", Model: "acme-pro", Extra: map[string]string{ExtraThinkingControl: "none"}})
+ require.NoError(t, err)
+ assert.Empty(t, r.Capabilities().ThinkingLevels, "none disables the selector")
+}
+
+func TestResolve_AlwaysOnModelCannotBeSwitchedOff(t *testing.T) {
+ registerTestVendors(t)
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-r1"})
+ require.NoError(t, err)
+ assert.False(t, r.ThinkingLevels.Supports(api.ReasoningOff))
+ assert.NotContains(t, r.Capabilities().ThinkingLevels, api.ReasoningOff)
+}
+
+func TestResolve_RejectsUnknownCompatKeys(t *testing.T) {
+ registerTestVendors(t)
+ _, err := Resolve(Ref{Provider: "acme", Model: "acme-pro", Override: &types.ModelSpecOverride{
+ Compat: map[string]any{"max_token_field": "max_tokens"},
+ }})
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "max_token_field")
+}
+
+func TestModelsByType(t *testing.T) {
+ registerTestVendors(t)
+ v, _ := Get("acme")
+ chat := v.ModelsByType(types.ModelTypeKnowledgeQA)
+ ids := make([]string, 0, len(chat))
+ for _, m := range chat {
+ ids = append(ids, m.ID)
+ }
+ assert.ElementsMatch(t, []string{"acme-pro", "acme-r1", "acme-claude"}, ids, "pattern-only entries are hidden")
+ vlm := v.ModelsByType(types.ModelTypeVLLM)
+ require.Len(t, vlm, 1)
+ assert.Equal(t, "acme-pro", vlm[0].ID, "VLM picker lists chat models with image input")
+ embed := v.ModelsByType(types.ModelTypeEmbedding)
+ require.Len(t, embed, 1)
+ assert.Equal(t, 1024, embed[0].Dimension)
+}
+
+func TestApplyOverlay(t *testing.T) {
+ registerTestVendors(t)
+ t.Setenv("ACME_KEY", "sk-from-env")
+ overlay := `{
+ "providers": {
+ "acme": {
+ "base_url": "https://acme.internal/v1",
+ "api_key": "${ACME_KEY}",
+ "headers": {"X-Team": "$ACME_KEY"},
+ "thinking_levels": {"xhigh": "max"},
+ "models": [{"id": "acme-ultra", "reasoning": true, "context_window": 400000}],
+ "model_overrides": {"acme-pro": {"context_window": 123, "compat": {"supports_temperature": true}}}
+ },
+ "my-vllm": {
+ "name": "Lab vLLM",
+ "names": {"zh-CN": "实验室 vLLM"},
+ "base_url": "http://vllm.lab:8000/v1",
+ "requires_auth": false,
+ "compat": {"thinking_format": "chat-template-kwargs", "max_tokens_field": "max_tokens"},
+ "models": [{"id": "Qwen/Qwen3-32B", "reasoning": true}]
+ }
+ }
+ }`
+ require.NoError(t, ApplyOverlay([]byte(overlay), t.TempDir()))
+
+ acme, ok := Get("acme")
+ require.True(t, ok)
+ assert.Equal(t, "https://acme.internal/v1", acme.GetDefaultURL(types.ModelTypeKnowledgeQA))
+ assert.Equal(t, "https://api.acme.ai/rerank", acme.GetDefaultURL(types.ModelTypeRerank), "other URLs untouched")
+ assert.Equal(t, "sk-from-env", acme.DefaultAPIKey)
+ assert.Equal(t, "sk-from-env", acme.Headers["X-Team"])
+ assert.Equal(t, "max", acme.ThinkingLevels.Value(api.ReasoningXHigh))
+ assert.Equal(t, "max", acme.ThinkingLevels.Value(api.ReasoningMax), "existing levels kept")
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-ultra"})
+ require.NoError(t, err)
+ assert.True(t, r.Cataloged)
+ assert.Equal(t, 400000, r.Spec.ContextWindow)
+
+ r, err = Resolve(Ref{Provider: "acme", Model: "acme-pro"})
+ require.NoError(t, err)
+ assert.Equal(t, 123, r.Spec.ContextWindow)
+ assert.True(t, r.OpenAICompletions.SupportsTemperature, "model_overrides compat merges over the built-in compat")
+
+ lab, ok := Get("my-vllm")
+ require.True(t, ok)
+ assert.Equal(t, "实验室 vLLM", lab.LocalizedName("zh-CN"))
+ assert.Equal(t, "Lab vLLM", lab.LocalizedName("en-US"))
+ assert.False(t, lab.RequiresAuth)
+ r, err = Resolve(Ref{Provider: "my-vllm", Model: "Qwen/Qwen3-32B"})
+ require.NoError(t, err)
+ assert.Equal(t, ThinkingFormatChatTemplateKwargs, r.OpenAICompletions.ThinkingFormat)
+ assert.Equal(t, "max_tokens", r.OpenAICompletions.MaxTokensField)
+ assert.True(t, r.Spec.Reasoning)
+ assert.Equal(t, "http://vllm.lab:8000/v1", r.BaseURL)
+
+ assert.Error(t, ApplyOverlay([]byte(`{"providers": {"x": {"bogus": 1}}}`), t.TempDir()), "unknown keys rejected")
+ assert.Error(t, ApplyOverlay([]byte(`{"providers": {"x": {"api": "nope"}}}`), t.TempDir()))
+}
+
+func TestThinkingLevelMap(t *testing.T) {
+ m := api.ThinkingLevelMap{
+ api.ReasoningMedium: nil,
+ api.ReasoningMax: api.StringPtr("max"),
+ api.ReasoningOff: api.StringPtr("none"),
+ }
+ assert.False(t, m.Supports(api.ReasoningMedium))
+ assert.True(t, m.Supports(api.ReasoningMax))
+ assert.False(t, m.Supports(api.ReasoningXHigh), "xhigh needs an explicit entry")
+ assert.Equal(t, api.ReasoningHigh, m.Clamp(api.ReasoningMedium), "clamps upward first")
+ assert.Equal(t, api.ReasoningMax, m.Clamp(api.ReasoningXHigh))
+ assert.Equal(t, "none", m.Value(api.ReasoningOff))
+ assert.Equal(t, "low", m.Value(api.ReasoningLow), "unmapped levels pass through")
+ assert.Equal(t, []api.ReasoningEffort{
+ api.ReasoningOff, api.ReasoningAuto, api.ReasoningMinimal,
+ api.ReasoningLow, api.ReasoningHigh, api.ReasoningMax,
+ }, m.SupportedLevels())
+
+ level, ok := api.ParseReasoningEffort("true")
+ assert.True(t, ok)
+ assert.Equal(t, api.ReasoningAuto, level)
+ _, ok = api.ParseReasoningEffort("ultra")
+ assert.False(t, ok)
+}
diff --git a/internal/models/catalog/compat.go b/internal/models/catalog/compat.go
new file mode 100644
index 000000000..fd8359ed0
--- /dev/null
+++ b/internal/models/catalog/compat.go
@@ -0,0 +1,398 @@
+package catalog
+
+import (
+ "encoding/json"
+ "fmt"
+ "reflect"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+)
+
+// ThinkingFormat names how an OpenAI-compatible vendor encodes the thinking
+// switch. It is the single most divergent field across vendors, which is
+// why it is an enum rather than free text.
+type ThinkingFormat string
+
+const (
+ // ThinkingFormatNone sends no thinking fields at all.
+ ThinkingFormatNone ThinkingFormat = "none"
+ // ThinkingFormatOpenAI sends only reasoning_effort (OpenAI, Azure, xAI).
+ ThinkingFormatOpenAI ThinkingFormat = "openai"
+ // ThinkingFormatThinkingType sends {"thinking": {"type": "enabled"|"disabled"}}
+ // plus reasoning_effort when supported (DeepSeek, Zhipu, Volcengine Ark,
+ // Moonshot K2.6+, MiniMax M3, LKEAP).
+ ThinkingFormatThinkingType ThinkingFormat = "thinking-type"
+ // ThinkingFormatEnableThinking sends enable_thinking: bool plus
+ // thinking_budget (DashScope, SiliconFlow, Hunyuan).
+ ThinkingFormatEnableThinking ThinkingFormat = "enable-thinking"
+ // ThinkingFormatChatTemplateKwargs sends chat_template_kwargs.enable_thinking
+ // (vLLM, SGLang, NIM, LiteLLM in front of them).
+ ThinkingFormatChatTemplateKwargs ThinkingFormat = "chat-template-kwargs"
+ // ThinkingFormatOpenRouter sends {"reasoning": {"effort"|"enabled"}}.
+ ThinkingFormatOpenRouter ThinkingFormat = "openrouter"
+)
+
+// OpenAICompletionsCompat is the overlay form (every field optional) of the
+// Chat Completions settings. JSON keys are the documented names used in
+// models.json and config/models.json.
+type OpenAICompletionsCompat struct {
+ MaxTokensField *string `json:"max_tokens_field,omitempty"`
+ ThinkingFormat *ThinkingFormat `json:"thinking_format,omitempty"`
+ ThinkingEnabledValue *string `json:"thinking_enabled_value,omitempty"`
+ ThinkingAlwaysSend *bool `json:"thinking_always_send,omitempty"`
+ ThinkingDisableOnNonStream *bool `json:"thinking_disable_on_non_stream,omitempty"`
+ ThinkingBudgetField *string `json:"thinking_budget_field,omitempty"`
+ ReasoningEffortField *string `json:"reasoning_effort_field,omitempty"`
+ SupportsReasoningEffort *bool `json:"supports_reasoning_effort,omitempty"`
+ SupportsDeveloperRole *bool `json:"supports_developer_role,omitempty"`
+ SupportsStore *bool `json:"supports_store,omitempty"`
+ SupportsUsageInStreaming *bool `json:"supports_usage_in_streaming,omitempty"`
+ SupportsTemperature *bool `json:"supports_temperature,omitempty"`
+ FixedTemperature *float64 `json:"fixed_temperature,omitempty"`
+ SupportsSeed *bool `json:"supports_seed,omitempty"`
+ ToolChoiceModes []string `json:"tool_choice_modes,omitempty"`
+ SupportsParallelToolCalls *bool `json:"supports_parallel_tool_calls,omitempty"`
+ SupportsResponseFormat *bool `json:"supports_response_format,omitempty"`
+ SupportsMultiContent *bool `json:"supports_multi_content,omitempty"`
+ ReplayReasoningContent *bool `json:"replay_reasoning_content,omitempty"`
+ PromptCacheKey *bool `json:"prompt_cache_key,omitempty"`
+ CacheControlFormat *string `json:"cache_control_format,omitempty"`
+ PromptCacheAccounting *bool `json:"prompt_cache_accounting,omitempty"`
+ ToolCallExtraFields []string `json:"tool_call_extra_fields,omitempty"`
+ ExtraBody map[string]any `json:"extra_body,omitempty"`
+ ReasoningFields []string `json:"reasoning_fields,omitempty"`
+}
+
+// OpenAICompletionsSettings is the resolved (fully defaulted) form.
+type OpenAICompletionsSettings struct {
+ // MaxTokensField is "max_tokens" or "max_completion_tokens".
+ MaxTokensField string
+ ThinkingFormat ThinkingFormat
+ // ThinkingEnabledValue is the "type" sent for thinking-type when enabled
+ // ("enabled" by default; MiniMax M3 uses "adaptive").
+ ThinkingEnabledValue string
+ // ThinkingAlwaysSend pins the switch on every request even when the
+ // caller expressed no preference (DashScope hybrid models require it).
+ ThinkingAlwaysSend bool
+ // ThinkingDisableOnNonStream forces the switch off for non-streaming
+ // calls (Qwen3 rejects thinking without stream).
+ ThinkingDisableOnNonStream bool
+ // ThinkingBudgetField carries Options.ThinkingBudgetTokens ("thinking_budget").
+ ThinkingBudgetField string
+ // ReasoningEffortField is "reasoning_effort" unless a vendor renames it.
+ ReasoningEffortField string
+ SupportsReasoningEffort bool
+ // SupportsDeveloperRole switches the system prompt to the developer role
+ // on reasoning models.
+ SupportsDeveloperRole bool
+ // SupportsStore sends store:false (OpenAI keeps completions otherwise).
+ SupportsStore bool
+ SupportsUsageInStreaming bool
+ // SupportsTemperature false drops every sampling parameter (o-series,
+ // GPT-5 family, Kimi K2.5+).
+ SupportsTemperature bool
+ // FixedTemperature pins the value when the vendor only accepts one.
+ FixedTemperature *float64
+ SupportsSeed bool
+ ToolChoiceModes []string
+ SupportsParallelToolCalls bool
+ SupportsResponseFormat bool
+ // SupportsMultiContent false flattens image/text parts to plain text.
+ SupportsMultiContent bool
+ // ReplayReasoningContent sends reasoning_content on prior assistant turns.
+ ReplayReasoningContent bool
+ // PromptCacheKey sends prompt_cache_key / prompt_cache_retention and the
+ // session-affinity headers.
+ PromptCacheKey bool
+ // CacheControlFormat "anthropic" injects cache_control breakpoints.
+ CacheControlFormat string
+ // PromptCacheAccounting states the vendor reports cache usage at all.
+ PromptCacheAccounting bool
+ // ToolCallExtraFields lists tool_call keys to round-trip opaquely
+ // (Gemini-through-OpenAI "extra_content").
+ ToolCallExtraFields []string
+ // ExtraBody is merged into every request body (vendor knobs such as
+ // enable_search, sampling defaults).
+ ExtraBody map[string]any
+ // ReasoningFields are the delta keys that carry thinking text, in
+ // priority order.
+ ReasoningFields []string
+}
+
+// DefaultOpenAICompletions is the protocol baseline: plain OpenAI semantics.
+func DefaultOpenAICompletions() OpenAICompletionsSettings {
+ return OpenAICompletionsSettings{
+ MaxTokensField: "max_completion_tokens",
+ ThinkingFormat: ThinkingFormatNone,
+ ThinkingEnabledValue: "enabled",
+ ReasoningEffortField: "reasoning_effort",
+ SupportsUsageInStreaming: true,
+ SupportsTemperature: true,
+ SupportsSeed: true,
+ ToolChoiceModes: []string{"none", "auto", "required", "function"},
+ SupportsParallelToolCalls: true,
+ SupportsResponseFormat: true,
+ SupportsMultiContent: true,
+ ReplayReasoningContent: true,
+ ReasoningFields: []string{"reasoning_content", "reasoning", "reasoning_text"},
+ }
+}
+
+// AllowsToolChoice reports whether a tool_choice mode is accepted.
+func (s OpenAICompletionsSettings) AllowsToolChoice(mode string) bool {
+ for _, m := range s.ToolChoiceModes {
+ if m == mode {
+ return true
+ }
+ }
+ return false
+}
+
+// OpenAIResponsesCompat is the overlay for the Responses protocol.
+type OpenAIResponsesCompat struct {
+ SupportsDeveloperRole *bool `json:"supports_developer_role,omitempty"`
+ SupportsMaxOutputTokens *bool `json:"supports_max_output_tokens,omitempty"`
+ SupportsReasoningSummary *bool `json:"supports_reasoning_summary,omitempty"`
+ SupportsEncryptedReasoning *bool `json:"supports_encrypted_reasoning,omitempty"`
+ SupportsStore *bool `json:"supports_store,omitempty"`
+ SupportsTemperature *bool `json:"supports_temperature,omitempty"`
+ PromptCacheKey *bool `json:"prompt_cache_key,omitempty"`
+ SupportsLongCacheRetention *bool `json:"supports_long_cache_retention,omitempty"`
+ SupportsParallelToolCalls *bool `json:"supports_parallel_tool_calls,omitempty"`
+ ExtraBody map[string]any `json:"extra_body,omitempty"`
+}
+
+// OpenAIResponsesSettings is the resolved Responses configuration.
+type OpenAIResponsesSettings struct {
+ SupportsDeveloperRole bool
+ SupportsMaxOutputTokens bool
+ SupportsReasoningSummary bool
+ SupportsEncryptedReasoning bool
+ SupportsStore bool
+ SupportsTemperature bool
+ PromptCacheKey bool
+ SupportsLongCacheRetention bool
+ SupportsParallelToolCalls bool
+ ExtraBody map[string]any
+}
+
+// DefaultOpenAIResponses is the api.openai.com baseline.
+func DefaultOpenAIResponses() OpenAIResponsesSettings {
+ return OpenAIResponsesSettings{
+ SupportsDeveloperRole: true,
+ SupportsMaxOutputTokens: true,
+ SupportsReasoningSummary: true,
+ SupportsEncryptedReasoning: true,
+ SupportsStore: true,
+ SupportsTemperature: true,
+ PromptCacheKey: true,
+ SupportsLongCacheRetention: true,
+ SupportsParallelToolCalls: true,
+ }
+}
+
+// AnthropicThinkingMode selects the thinking request shape.
+type AnthropicThinkingMode string
+
+const (
+ // AnthropicThinkingBudget sends {"type":"enabled","budget_tokens":N}.
+ AnthropicThinkingBudget AnthropicThinkingMode = "budget"
+ // AnthropicThinkingAdaptive sends {"type":"adaptive"} and steers the
+ // intensity through output_config.effort.
+ AnthropicThinkingAdaptive AnthropicThinkingMode = "adaptive"
+)
+
+// AnthropicMessagesCompat is the overlay for the Messages protocol.
+type AnthropicMessagesCompat struct {
+ ThinkingMode *AnthropicThinkingMode `json:"thinking_mode,omitempty"`
+ SupportsEffort *bool `json:"supports_effort,omitempty"`
+ ThinkingBudgets map[api.ReasoningEffort]int `json:"thinking_budgets,omitempty"`
+ DefaultMaxTokens *int `json:"default_max_tokens,omitempty"`
+ SupportsTemperature *bool `json:"supports_temperature,omitempty"`
+ TemperatureWithThinking *bool `json:"temperature_with_thinking,omitempty"`
+ SupportsTopP *bool `json:"supports_top_p,omitempty"`
+ SupportsCacheControl *bool `json:"supports_cache_control,omitempty"`
+ SupportsCacheControlOnTool *bool `json:"supports_cache_control_on_tools,omitempty"`
+ LongCacheTTL *string `json:"long_cache_ttl,omitempty"`
+ Version *string `json:"version,omitempty"`
+ BetaHeaders []string `json:"beta_headers,omitempty"`
+ InterleavedThinkingBeta *string `json:"interleaved_thinking_beta,omitempty"`
+ PromptCacheAccounting *bool `json:"prompt_cache_accounting,omitempty"`
+ ExtraBody map[string]any `json:"extra_body,omitempty"`
+}
+
+// AnthropicMessagesSettings is the resolved Messages configuration.
+type AnthropicMessagesSettings struct {
+ ThinkingMode AnthropicThinkingMode
+ SupportsEffort bool
+ // ThinkingBudgets maps graded levels to budget_tokens for budget mode.
+ ThinkingBudgets map[api.ReasoningEffort]int
+ // DefaultMaxTokens is used when the caller set no budget (max_tokens is
+ // mandatory on this protocol).
+ DefaultMaxTokens int
+ SupportsTemperature bool
+ TemperatureWithThinking bool
+ SupportsTopP bool
+ SupportsCacheControl bool
+ SupportsCacheControlOnTool bool
+ LongCacheTTL string
+ Version string
+ BetaHeaders []string
+ // InterleavedThinkingBeta is added to anthropic-beta when thinking and
+ // tools are both active (budget mode only). Empty disables it.
+ InterleavedThinkingBeta string
+ PromptCacheAccounting bool
+ ExtraBody map[string]any
+}
+
+// DefaultAnthropicMessages is the api.anthropic.com baseline for the
+// budget-thinking generation of models.
+func DefaultAnthropicMessages() AnthropicMessagesSettings {
+ return AnthropicMessagesSettings{
+ ThinkingMode: AnthropicThinkingBudget,
+ ThinkingBudgets: map[api.ReasoningEffort]int{
+ api.ReasoningMinimal: 1024,
+ api.ReasoningLow: 2048,
+ api.ReasoningMedium: 8192,
+ api.ReasoningHigh: 16384,
+ api.ReasoningXHigh: 32768,
+ api.ReasoningMax: 63999,
+ },
+ DefaultMaxTokens: 4096,
+ SupportsTemperature: true,
+ TemperatureWithThinking: false,
+ SupportsTopP: true,
+ SupportsCacheControl: true,
+ SupportsCacheControlOnTool: true,
+ LongCacheTTL: "1h",
+ Version: "2023-06-01",
+ InterleavedThinkingBeta: "interleaved-thinking-2025-05-14",
+ PromptCacheAccounting: true,
+ }
+}
+
+// GoogleThinkingMode selects the thinkingConfig shape.
+type GoogleThinkingMode string
+
+const (
+ // GoogleThinkingBudget sends thinkingConfig.thinkingBudget (Gemini 2.5).
+ GoogleThinkingBudget GoogleThinkingMode = "budget"
+ // GoogleThinkingLevel sends thinkingConfig.thinkingLevel (Gemini 3+).
+ GoogleThinkingLevel GoogleThinkingMode = "level"
+ // GoogleThinkingNone sends no thinkingConfig.
+ GoogleThinkingNone GoogleThinkingMode = "none"
+)
+
+// GoogleGenerativeAICompat is the overlay for the Gemini protocol.
+type GoogleGenerativeAICompat struct {
+ ThinkingMode *GoogleThinkingMode `json:"thinking_mode,omitempty"`
+ ThinkingBudgets map[api.ReasoningEffort]int `json:"thinking_budgets,omitempty"`
+ IncludeThoughts *bool `json:"include_thoughts,omitempty"`
+ SupportsSeed *bool `json:"supports_seed,omitempty"`
+ SupportsPenalty *bool `json:"supports_penalty,omitempty"`
+ ExtraGeneration map[string]any `json:"extra_generation_config,omitempty"`
+ PromptCacheAcct *bool `json:"prompt_cache_accounting,omitempty"`
+ APIVersionPrefix *string `json:"api_version_prefix,omitempty"`
+}
+
+// GoogleGenerativeAISettings is the resolved Gemini configuration.
+type GoogleGenerativeAISettings struct {
+ ThinkingMode GoogleThinkingMode
+ ThinkingBudgets map[api.ReasoningEffort]int
+ IncludeThoughts bool
+ SupportsSeed bool
+ SupportsPenalty bool
+ ExtraGeneration map[string]any
+ PromptCacheAcct bool
+ // APIVersionPrefix is appended to a bare host base URL ("/v1beta").
+ APIVersionPrefix string
+}
+
+// DefaultGoogleGenerativeAI is the generativelanguage.googleapis.com baseline.
+func DefaultGoogleGenerativeAI() GoogleGenerativeAISettings {
+ return GoogleGenerativeAISettings{
+ ThinkingMode: GoogleThinkingBudget,
+ ThinkingBudgets: map[api.ReasoningEffort]int{
+ api.ReasoningMinimal: 128,
+ api.ReasoningLow: 2048,
+ api.ReasoningMedium: 8192,
+ api.ReasoningHigh: 24576,
+ api.ReasoningXHigh: 32768,
+ api.ReasoningMax: 32768,
+ },
+ IncludeThoughts: true,
+ SupportsSeed: true,
+ SupportsPenalty: true,
+ PromptCacheAcct: true,
+ APIVersionPrefix: "/v1beta",
+ }
+}
+
+// VendorCompat carries a vendor's defaults for every protocol it may speak.
+type VendorCompat struct {
+ OpenAICompletions OpenAICompletionsCompat `json:"openai_completions,omitempty"`
+ OpenAIResponses OpenAIResponsesCompat `json:"openai_responses,omitempty"`
+ AnthropicMessages AnthropicMessagesCompat `json:"anthropic_messages,omitempty"`
+ GoogleGenerativeAI GoogleGenerativeAICompat `json:"google_generative_ai,omitempty"`
+}
+
+// apply writes the set fields of an overlay struct onto a settings struct
+// with matching field names, dereferencing pointers. Slices and maps
+// replace the default wholesale (no element merge) except map[string]any
+// ExtraBody-style fields, which merge key by key.
+func apply(settings any, compat any) {
+ sv := reflect.ValueOf(settings).Elem()
+ cv := reflect.ValueOf(compat).Elem()
+ ct := cv.Type()
+ for i := 0; i < cv.NumField(); i++ {
+ field := ct.Field(i)
+ if !field.IsExported() {
+ continue
+ }
+ target := sv.FieldByName(field.Name)
+ if !target.IsValid() {
+ panic(fmt.Sprintf("catalog: overlay field %s.%s has no settings counterpart", ct.Name(), field.Name))
+ }
+ f := cv.Field(i)
+ switch f.Kind() {
+ case reflect.Pointer:
+ if f.IsNil() {
+ continue
+ }
+ if target.Kind() == reflect.Pointer {
+ target.Set(f)
+ } else {
+ target.Set(f.Elem())
+ }
+ case reflect.Slice:
+ if f.Len() > 0 {
+ target.Set(f)
+ }
+ case reflect.Map:
+ if f.Len() == 0 {
+ continue
+ }
+ if target.IsNil() {
+ target.Set(reflect.MakeMap(target.Type()))
+ }
+ iter := f.MapRange()
+ for iter.Next() {
+ target.SetMapIndex(iter.Key(), iter.Value())
+ }
+ }
+ }
+}
+
+// decodeCompat unmarshals a flat compat object into the overlay type for an
+// API. Unknown keys are rejected so typos in models.json surface early.
+func decodeCompat(raw json.RawMessage, into any) error {
+ if len(raw) == 0 {
+ return nil
+ }
+ dec := json.NewDecoder(bytesReader(raw))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(into); err != nil {
+ return fmt.Errorf("decode compat: %w", err)
+ }
+ return nil
+}
diff --git a/internal/models/catalog/legacy_rows_test.go b/internal/models/catalog/legacy_rows_test.go
new file mode 100644
index 000000000..8817a0208
--- /dev/null
+++ b/internal/models/catalog/legacy_rows_test.go
@@ -0,0 +1,413 @@
+package catalog_test
+
+// Backward-compatibility guard for model rows written before the vendor
+// catalog existed (internal/models/provider). Every shape in this file is one
+// that a production `models` table can already contain, so a failure here
+// means an existing deployment breaks on upgrade without a migration.
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// legacyProviderIDs is the complete set of parameters.provider values the
+// pre-catalog code could write: provider.AllProviders() plus weknoracloud,
+// as of internal/models/provider/provider.go before the refactor.
+var legacyProviderIDs = []string{
+ "generic", "weknoracloud", "aliyun", "zhipu", "volcengine", "hunyuan",
+ "siliconflow", "deepseek", "minimax", "moonshot", "modelscope", "qianfan",
+ "qiniu", "openai", "anthropic", "gemini", "openrouter", "litellm",
+ "requesty", "jina", "mimo", "longcat", "lkeap", "gpustack", "nvidia",
+ "novita", "azure_openai",
+}
+
+// TestLegacyProviderIDsStillRegistered asserts that no provider id an old row
+// may carry has disappeared from the catalog. A missing id would silently
+// degrade that row to the generic OpenAI baseline (wrong auth, wrong URL,
+// wrong thinking encoding).
+func TestLegacyProviderIDsStillRegistered(t *testing.T) {
+ for _, id := range legacyProviderIDs {
+ if _, ok := catalog.Get(id); !ok {
+ t.Errorf("provider id %q was writable by the old code but has no vendor now", id)
+ }
+ }
+}
+
+// legacyRow is one realistic pre-refactor `models` row.
+type legacyRow struct {
+ name string
+ model string
+ typ types.ModelType
+ params types.ModelParameters
+}
+
+// legacyRows covers the shapes the old write paths produced: the model editor
+// (provider + base_url + api_key, no extra_config at all), the initialization
+// wizard (thinking_control / api_version / remote_model_name), YAML builtin
+// models, and rows hand-written against an older release.
+func legacyRows() []legacyRow {
+ rows := []legacyRow{
+ {
+ name: "editor row, catalogued model, no extra_config",
+ model: "deepseek-chat", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{Provider: "deepseek", BaseURL: "https://api.deepseek.com/v1", APIKey: "sk-x"},
+ },
+ {
+ name: "editor row, model the vendor has since retired",
+ model: "gpt-3.5-turbo-0301", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{Provider: "openai", BaseURL: "https://api.openai.com/v1", APIKey: "sk-x"},
+ },
+ {
+ name: "self-hosted fine-tune behind a generic endpoint",
+ model: "acme-corp/llama-3.1-70b-finetune-v7", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{Provider: "generic", BaseURL: "http://vllm.internal:8000/v1"},
+ },
+ {
+ name: "row written before parameters.provider existed",
+ model: "qwen-plus", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"},
+ },
+ {
+ name: "row with neither provider nor base_url",
+ model: "some-model", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{},
+ },
+ {
+ name: "provider id a hand-edited row invented",
+ model: "grok-4", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{Provider: "xai", BaseURL: "https://api.x.ai/v1"},
+ },
+ {
+ name: "VLM row", model: "qwen-vl-max", typ: types.ModelTypeVLLM,
+ params: types.ModelParameters{
+ Provider: "aliyun", BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+ InterfaceType: "openai", SupportsVision: true,
+ },
+ },
+ {
+ name: "local Ollama VLM row (interface_type ollama)", model: "llava:13b", typ: types.ModelTypeVLLM,
+ params: types.ModelParameters{
+ InterfaceType: "ollama", ParameterSize: "13B", BaseURL: "http://localhost:11434",
+ },
+ },
+ {
+ name: "WeKnoraCloud row with app credentials", model: "weknora-chat", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{
+ Provider: "weknoracloud", BaseURL: "https://weknora.weixin.qq.com",
+ AppID: "app", AppSecret: "secret",
+ ExtraConfig: map[string]string{"remote_model_name": "hunyuan-turbos"},
+ },
+ },
+ {
+ name: "Azure row from the initialization wizard", model: "gpt-4o-deployment",
+ typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{
+ Provider: "azure_openai", BaseURL: "https://my-resource.openai.azure.com",
+ ExtraConfig: map[string]string{"api_version": "2024-10-21"},
+ },
+ },
+ {
+ name: "Azure row created from the model editor (no api_version)", model: "gpt-4o-deployment",
+ typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{
+ Provider: "azure_openai", BaseURL: "https://my-resource.openai.azure.com",
+ },
+ },
+ {
+ name: "every legacy extra_config key at once, plus an unknown one",
+ model: "custom-model", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{
+ Provider: "generic", BaseURL: "http://vllm.internal:8000/v1",
+ ExtraConfig: map[string]string{
+ "thinking_control": "chat_template_kwargs",
+ "remote_model_name": "Qwen/Qwen3-32B",
+ "api_version": "2024-10-21",
+ "secret_key": "sk",
+ "region": "ap-guangzhou",
+ "instruction": "rank these",
+ "truncate_prompt_tokens": "4096",
+ "deployment": "prod",
+ "freshness": "week",
+ "a_key_no_release_ever_wrote": "1",
+ },
+ },
+ },
+ {
+ name: "embedding row with dimension override", model: "text-embedding-v4", typ: types.ModelTypeEmbedding,
+ params: types.ModelParameters{
+ Provider: "aliyun", BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+ EmbeddingParameters: types.EmbeddingParameters{
+ Dimension: 1024, TruncatePromptTokens: 2048, SupportsDimensionOverride: true,
+ },
+ },
+ },
+ {
+ name: "LKEAP signed rerank row", model: "lkeap-rerank", typ: types.ModelTypeRerank,
+ params: types.ModelParameters{
+ Provider: "lkeap", BaseURL: "https://lkeap.tencentcloudapi.com",
+ ExtraConfig: map[string]string{"secret_key": "sk", "region": "ap-guangzhou"},
+ },
+ },
+ {
+ name: "custom headers row", model: "gateway-model", typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{
+ Provider: "generic", BaseURL: "https://gateway.corp.example.com/v1",
+ CustomHeaders: map[string]string{"X-Corp-Route": "llm"},
+ ContextWindow: 128000, MaxOutputTokens: 8192, MaxConcurrency: 4,
+ },
+ },
+ }
+ // Every legacy provider id, carrying a model name no models.json knows.
+ // This is the "custom fine-tune / retired model / self-hosted name" case
+ // for each vendor at once.
+ for _, id := range legacyProviderIDs {
+ rows = append(rows, legacyRow{
+ name: "uncatalogued model on provider " + id, model: "a-model-no-catalog-knows",
+ typ: types.ModelTypeKnowledgeQA,
+ params: types.ModelParameters{Provider: id},
+ })
+ }
+ return rows
+}
+
+// TestLegacyRowsValidateAndResolve is the core guarantee: opening an existing
+// model in the UI and saving it (PUT /models/{id} runs catalog.ValidateRow)
+// must not 400, and the chat path must still resolve the row.
+func TestLegacyRowsValidateAndResolve(t *testing.T) {
+ for _, row := range legacyRows() {
+ t.Run(row.name, func(t *testing.T) {
+ params := row.params
+ if err := catalog.ValidateRow(row.model, row.typ, &params); err != nil {
+ t.Fatalf("ValidateRow rejected a row the old code accepted: %v", err)
+ }
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: params.Provider, Model: row.model, BaseURL: params.BaseURL,
+ ModelType: row.typ, Extra: params.ExtraConfig, Override: params.Spec,
+ })
+ if err != nil {
+ t.Fatalf("Resolve failed: %v", err)
+ }
+ if resolved.Vendor == nil {
+ t.Fatal("resolved with a nil vendor")
+ }
+ if !resolved.API.Known() {
+ t.Fatalf("resolved to an unknown protocol %q", resolved.API)
+ }
+ if resolved.RemoteModel == "" && row.model != "" {
+ t.Fatal("resolved to an empty remote model id")
+ }
+ })
+ }
+}
+
+// TestEveryCataloguedModelResolves walks the whole catalog so a row naming any
+// shipped model id — which is what the old model picker wrote — is known to
+// resolve.
+func TestEveryCataloguedModelResolves(t *testing.T) {
+ for _, v := range catalog.List() {
+ for _, m := range v.Models {
+ if m.ID == "" {
+ continue
+ }
+ modelType := m.Type
+ if modelType == "" {
+ modelType = types.ModelTypeKnowledgeQA
+ }
+ if err := catalog.ValidateRow(m.ID, modelType, &types.ModelParameters{Provider: v.ID}); err != nil {
+ t.Errorf("%s/%s: ValidateRow: %v", v.ID, m.ID, err)
+ }
+ }
+ }
+}
+
+// legacyThinkingControl is the old chat.parseThinkingOverride mapping, from
+// internal/models/chat/thinking.go before the refactor. The four values are
+// the only ones the old frontend wrote (frontend/src/utils/thinkingControl.ts),
+// but an unrecognized non-empty value historically fell back to
+// chat_template_kwargs and must keep doing so.
+var legacyThinkingControl = map[string]catalog.ThinkingFormat{
+ "none": catalog.ThinkingFormatNone,
+ "enable_thinking": catalog.ThinkingFormatEnableThinking,
+ "thinking_type": catalog.ThinkingFormatThinkingType,
+ "chat_template_kwargs": catalog.ThinkingFormatChatTemplateKwargs,
+ "enabled": catalog.ThinkingFormatChatTemplateKwargs,
+ "ENABLE_THINKING": catalog.ThinkingFormatEnableThinking,
+ " thinking_type ": catalog.ThinkingFormatThinkingType,
+}
+
+// TestLegacyThinkingControlMapping pins extra_config.thinking_control to the
+// old semantics for every value a stored row can hold, including on a
+// catalogued non-reasoning model where the new silencing pass would otherwise
+// drop the thinking fields.
+func TestLegacyThinkingControlMapping(t *testing.T) {
+ for value, want := range legacyThinkingControl {
+ t.Run(value, func(t *testing.T) {
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: "generic", Model: "Qwen/Qwen3-32B",
+ BaseURL: "http://vllm.internal:8000/v1", ModelType: types.ModelTypeKnowledgeQA,
+ Extra: map[string]string{"thinking_control": value},
+ })
+ if err != nil {
+ t.Fatalf("Resolve: %v", err)
+ }
+ if got := resolved.OpenAICompletions.ThinkingFormat; got != want {
+ t.Fatalf("thinking_control=%q resolved to %q, old code selected %q", value, got, want)
+ }
+ })
+ }
+}
+
+// TestLegacyThinkingControlSurvivesCatalogSilencing guards the interaction
+// between a stored thinking_control and silenceThinkingForNonReasoningModel:
+// an operator who explicitly picked an encoding must keep it even when the
+// catalog marks the model non-reasoning.
+func TestLegacyThinkingControlSurvivesCatalogSilencing(t *testing.T) {
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: "openai", Model: "gpt-4o", ModelType: types.ModelTypeKnowledgeQA,
+ Extra: map[string]string{"thinking_control": "chat_template_kwargs"},
+ })
+ if err != nil {
+ t.Fatalf("Resolve: %v", err)
+ }
+ if resolved.OpenAICompletions.ThinkingFormat != catalog.ThinkingFormatChatTemplateKwargs {
+ t.Fatalf("explicit thinking_control was overridden by the catalog: %q",
+ resolved.OpenAICompletions.ThinkingFormat)
+ }
+}
+
+// TestUncataloguedModelKeepsThinkingSwitch documents the deliberate asymmetry
+// in silenceThinkingForNonReasoningModel: a model nobody catalogued (the
+// self-hosted case) keeps its thinking switch, which is what old rows relied
+// on, while a catalogued non-reasoning model loses it.
+func TestUncataloguedModelKeepsThinkingSwitch(t *testing.T) {
+ unknown, err := catalog.Resolve(catalog.Ref{
+ Provider: "generic", Model: "acme/llama-3.1-70b-finetune",
+ BaseURL: "http://vllm.internal:8000/v1", ModelType: types.ModelTypeKnowledgeQA,
+ })
+ if err != nil {
+ t.Fatalf("Resolve: %v", err)
+ }
+ if unknown.Cataloged {
+ t.Fatal("expected the fine-tune to be uncatalogued")
+ }
+ if unknown.OpenAICompletions.ThinkingFormat != catalog.ThinkingFormatChatTemplateKwargs {
+ t.Fatalf("uncatalogued model lost its thinking switch: %q",
+ unknown.OpenAICompletions.ThinkingFormat)
+ }
+}
+
+// TestLegacyRemoteModelNameHonoured pins extra_config.remote_model_name, which
+// the old chat and embedding paths both read.
+func TestLegacyRemoteModelNameHonoured(t *testing.T) {
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: "generic", Model: "display-name", BaseURL: "http://vllm.internal:8000/v1",
+ ModelType: types.ModelTypeKnowledgeQA,
+ Extra: map[string]string{"remote_model_name": "Qwen/Qwen3-32B"},
+ })
+ if err != nil {
+ t.Fatalf("Resolve: %v", err)
+ }
+ if resolved.RemoteModel != "Qwen/Qwen3-32B" {
+ t.Fatalf("remote_model_name ignored: wire model is %q", resolved.RemoteModel)
+ }
+}
+
+// TestUnknownProviderFallsBackToGeneric checks the reverse direction: a row
+// naming a provider this build does not ship degrades to the generic
+// OpenAI-compatible baseline instead of failing the write.
+func TestUnknownProviderFallsBackToGeneric(t *testing.T) {
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: "a-vendor-from-the-future", Model: "m",
+ BaseURL: "https://example.com/v1", ModelType: types.ModelTypeKnowledgeQA,
+ })
+ if err != nil {
+ t.Fatalf("Resolve: %v", err)
+ }
+ if resolved.Vendor.ID != catalog.GenericID {
+ t.Fatalf("unknown provider resolved to %q, want %q", resolved.Vendor.ID, catalog.GenericID)
+ }
+ if resolved.API != api.APIOpenAICompletions {
+ t.Fatalf("unknown provider resolved to protocol %q", resolved.API)
+ }
+}
+
+// TestLegacyStoredBaseURLSelectsSameProtocol pins the protocol an existing
+// row resolves to. Old rows always store an explicit base_url (the model
+// editor pre-filled the provider default), so the stored URL — not the new
+// vendor default — decides the wire protocol on upgrade. The Gemini case and
+// the first-party OpenAI move to Responses are covered in
+// internal/models/parity; what is asserted here is the relay case, where the
+// same provider id must NOT follow OpenAI onto /responses.
+func TestLegacyStoredBaseURLSelectsSameProtocol(t *testing.T) {
+ cases := []struct {
+ provider, baseURL string
+ want api.API
+ why string
+ }{
+ {
+ provider: "openai", baseURL: "https://llm-relay.corp.example.com/v1",
+ want: api.APIOpenAICompletions,
+ why: "a relay that only speaks Chat Completions must stay on it",
+ },
+ {
+ provider: "openai", baseURL: "https://litellm.corp.example.com/v1",
+ want: api.APIOpenAICompletions,
+ why: "an OpenAI row pointed at a LiteLLM proxy keeps Chat Completions",
+ },
+ {
+ provider: "anthropic", baseURL: "https://api.anthropic.com/v1",
+ want: api.APIAnthropicMessages,
+ why: "the old code already dispatched anthropic to the Messages protocol",
+ },
+ {
+ provider: "generic", baseURL: "http://vllm.internal:8000/v1",
+ want: api.APIOpenAICompletions, why: "unchanged",
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.provider+" "+tc.baseURL, func(t *testing.T) {
+ resolved, err := catalog.Resolve(catalog.Ref{
+ Provider: tc.provider, Model: "some-model", BaseURL: tc.baseURL,
+ ModelType: types.ModelTypeKnowledgeQA,
+ })
+ if err != nil {
+ t.Fatalf("Resolve: %v", err)
+ }
+ if resolved.API != tc.want {
+ t.Fatalf("protocol %q, want %q (%s)", resolved.API, tc.want, tc.why)
+ }
+ })
+ }
+}
+
+// TestLegacyFreeFormAPIExtraKeyIsRejected documents the one stored shape this
+// refactor does break, so the trade-off stays visible.
+//
+// extra_config has always been a free-form map[string]string: the old backend
+// read only thinking_control, remote_model_name, api_version, secret_key,
+// region, instruction and truncate_prompt_tokens from it and ignored every
+// other key. The catalog gave the key "api" a meaning — it forces the wire
+// protocol — and ValidateRow now rejects a value that is not one of the five
+// protocol names. A row that an operator hand-populated with, say,
+// {"api": "v1"} therefore fails PUT /models/{id} with 400 and fails every
+// chat call, even though nothing about that row changed.
+//
+// Nothing in WeKnora ever wrote this key, so only hand-built rows and
+// hand-written builtin_models.yaml entries are affected. If that is judged too
+// sharp, the fix is to ignore an unparseable extra_config.api in Resolve and
+// keep the strict check for Spec.API, which no old row can carry.
+func TestLegacyFreeFormAPIExtraKeyIsRejected(t *testing.T) {
+ err := catalog.ValidateRow("gpt-4o", types.ModelTypeKnowledgeQA, &types.ModelParameters{
+ Provider: "openai", BaseURL: "https://api.openai.com/v1",
+ ExtraConfig: map[string]string{"api": "v1"},
+ })
+ if err == nil {
+ t.Skip("extra_config.api is now tolerant of legacy free-form values; " +
+ "delete this test and the release note that goes with it")
+ }
+ t.Logf("documented break: %v", err)
+}
diff --git a/internal/models/catalog/overlay.go b/internal/models/catalog/overlay.go
new file mode 100644
index 000000000..a222c5464
--- /dev/null
+++ b/internal/models/catalog/overlay.go
@@ -0,0 +1,549 @@
+package catalog
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// OverlayFile is the schema of config/models.json. It mirrors pi's
+// ~/.pi/agent/models.json: a "providers" object keyed by provider id where
+// each entry either patches a built-in vendor or declares a new one.
+type OverlayFile struct {
+ Providers map[string]OverlayProvider `json:"providers"`
+}
+
+// OverlayProvider patches or declares one vendor.
+type OverlayProvider struct {
+ Name string `json:"name,omitempty"`
+ Names map[string]string `json:"names,omitempty"`
+ Description string `json:"description,omitempty"`
+ Descriptions map[string]string `json:"descriptions,omitempty"`
+ Website string `json:"website,omitempty"`
+ // API is the default chat protocol for new vendors (and overrides it
+ // for built-in ones).
+ API api.API `json:"api,omitempty"`
+ // BaseURL sets the chat base URL; BaseURLs sets per-type URLs keyed by
+ // chat | embedding | rerank | vlm | asr.
+ BaseURL string `json:"base_url,omitempty"`
+ BaseURLs map[string]string `json:"base_urls,omitempty"`
+ // APIKey is the deployment-level key used when a model row stores none.
+ // Supports ${ENV} / $ENV interpolation.
+ APIKey string `json:"api_key,omitempty"`
+ Headers map[string]string `json:"headers,omitempty"`
+ Auth AuthStyle `json:"auth,omitempty"`
+ RequiresAuth *bool `json:"requires_auth,omitempty"`
+ ModelTypes []string `json:"model_types,omitempty"`
+ URLPatterns []string `json:"url_patterns,omitempty"`
+ // Icon is a path to an SVG file (relative to the overlay file) or an
+ // inline "<svg ...>" string.
+ Icon string `json:"icon,omitempty"`
+ // Compat is the flat protocol overlay applied at vendor level for API.
+ Compat json.RawMessage `json:"compat,omitempty"`
+ // ThinkingLevels patches the vendor level map.
+ ThinkingLevels map[string]*string `json:"thinking_levels,omitempty"`
+ // Models are upserted by id into the vendor catalog. Entries stay raw so
+ // an upsert against an existing id can patch only the keys the operator
+ // actually wrote (see applyOverlayProvider).
+ Models []json.RawMessage `json:"models,omitempty"`
+ // ModelOverrides patch existing entries by id without restating them.
+ ModelOverrides map[string]ModelSpecPatch `json:"model_overrides,omitempty"`
+}
+
+// ModelSpecPatch is a partial ModelSpec.
+type ModelSpecPatch struct {
+ Name string `json:"name,omitempty"`
+ API api.API `json:"api,omitempty"`
+ Reasoning *bool `json:"reasoning,omitempty"`
+ Input []string `json:"input,omitempty"`
+ ContextWindow int `json:"context_window,omitempty"`
+ MaxOutputTokens int `json:"max_output_tokens,omitempty"`
+ Cost *ModelCost `json:"cost,omitempty"`
+ ThinkingLevels api.ThinkingLevelMap `json:"thinking_levels,omitempty"`
+ Compat json.RawMessage `json:"compat,omitempty"`
+ Aliases []string `json:"aliases,omitempty"`
+ Deprecated *bool `json:"deprecated,omitempty"`
+}
+
+var envPattern = regexp.MustCompile(`\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)`)
+
+// interpolateEnv expands ${NAME} and $NAME. Unset variables expand to the
+// empty string so a missing key fails loudly upstream rather than sending
+// the literal placeholder.
+func interpolateEnv(s string) string {
+ return envPattern.ReplaceAllStringFunc(s, func(m string) string {
+ name := strings.Trim(strings.TrimPrefix(m, "$"), "{}")
+ return os.Getenv(name)
+ })
+}
+
+var frontendTypes = map[string]types.ModelType{
+ "chat": types.ModelTypeKnowledgeQA,
+ "embedding": types.ModelTypeEmbedding,
+ "rerank": types.ModelTypeRerank,
+ "vlm": types.ModelTypeVLLM,
+ "vllm": types.ModelTypeVLLM,
+ "asr": types.ModelTypeASR,
+}
+
+// ParseModelType accepts both frontend ("chat") and backend ("KnowledgeQA")
+// spellings.
+func ParseModelType(s string) (types.ModelType, bool) {
+ if t, ok := frontendTypes[strings.ToLower(strings.TrimSpace(s))]; ok {
+ return t, true
+ }
+ switch types.ModelType(s) {
+ case types.ModelTypeKnowledgeQA, types.ModelTypeEmbedding, types.ModelTypeRerank,
+ types.ModelTypeVLLM, types.ModelTypeASR:
+ return types.ModelType(s), true
+ }
+ return "", false
+}
+
+// LoadOverlay reads config/models.json (or the path in MODELS_CONFIG) and
+// applies it to the registry. A missing file is not an error.
+func LoadOverlay(configDir string) error {
+ path := os.Getenv("MODELS_CONFIG")
+ if path == "" {
+ path = filepath.Join(configDir, "models.json")
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return nil
+ }
+ return fmt.Errorf("read %s: %w", path, err)
+ }
+ return ApplyOverlay(data, filepath.Dir(path))
+}
+
+// ApplyOverlay applies overlay JSON to the registry. baseDir resolves
+// relative icon paths.
+func ApplyOverlay(data []byte, baseDir string) error {
+ var file OverlayFile
+ dec := json.NewDecoder(bytesReader(data))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&file); err != nil {
+ return fmt.Errorf("parse models overlay: %w", err)
+ }
+ for id, p := range file.Providers {
+ id = strings.ToLower(strings.TrimSpace(id))
+ if id == "" {
+ continue
+ }
+ vendor, exists := Get(id)
+ if !exists {
+ vendor = &Vendor{
+ ID: id,
+ Name: id,
+ API: api.APIOpenAICompletions,
+ DefaultBaseURLs: map[types.ModelType]string{},
+ ModelTypes: []types.ModelType{types.ModelTypeKnowledgeQA},
+ RequiresAuth: true,
+ Auth: AuthBearer,
+ Order: 1000,
+ }
+ } else {
+ copied := *vendor
+ vendor = &copied
+ vendor.Models = append([]ModelSpec(nil), vendor.Models...)
+ urls := make(map[types.ModelType]string, len(vendor.DefaultBaseURLs))
+ for k, v := range vendor.DefaultBaseURLs {
+ urls[k] = v
+ }
+ vendor.DefaultBaseURLs = urls
+ }
+ if err := applyOverlayProvider(vendor, p, baseDir); err != nil {
+ return fmt.Errorf("provider %s: %w", id, err)
+ }
+ Register(vendor)
+ }
+ return nil
+}
+
+func applyOverlayProvider(v *Vendor, p OverlayProvider, baseDir string) error {
+ if p.Name != "" {
+ v.Name = p.Name
+ }
+ if len(p.Names) > 0 {
+ v.Names = p.Names
+ }
+ if p.Description != "" {
+ v.Description = p.Description
+ }
+ if len(p.Descriptions) > 0 {
+ v.Descriptions = p.Descriptions
+ }
+ if p.Website != "" {
+ v.Website = p.Website
+ }
+ if p.API != "" {
+ if !p.API.Known() {
+ return fmt.Errorf("unknown api %q", p.API)
+ }
+ v.API = p.API
+ }
+ if p.BaseURL != "" {
+ v.DefaultBaseURLs[types.ModelTypeKnowledgeQA] = interpolateEnv(p.BaseURL)
+ }
+ for k, u := range p.BaseURLs {
+ t, ok := ParseModelType(k)
+ if !ok {
+ return fmt.Errorf("unknown model type %q in base_urls", k)
+ }
+ v.DefaultBaseURLs[t] = interpolateEnv(u)
+ }
+ if p.APIKey != "" {
+ v.DefaultAPIKey = interpolateEnv(p.APIKey)
+ }
+ if len(p.Headers) > 0 {
+ headers := make(map[string]string, len(p.Headers))
+ for k, val := range p.Headers {
+ headers[k] = interpolateEnv(val)
+ }
+ v.Headers = headers
+ }
+ if p.Auth != "" {
+ v.Auth = p.Auth
+ }
+ if p.RequiresAuth != nil {
+ v.RequiresAuth = *p.RequiresAuth
+ }
+ if len(p.ModelTypes) > 0 {
+ v.ModelTypes = v.ModelTypes[:0]
+ for _, s := range p.ModelTypes {
+ t, ok := ParseModelType(s)
+ if !ok {
+ return fmt.Errorf("unknown model type %q", s)
+ }
+ v.ModelTypes = append(v.ModelTypes, t)
+ }
+ }
+ if len(p.URLPatterns) > 0 {
+ v.URLPatterns = p.URLPatterns
+ }
+ if p.Icon != "" {
+ icon, err := loadOverlayIcon(baseDir, p.Icon)
+ if err != nil {
+ return err
+ }
+ v.Icon = icon
+ }
+ if len(p.Compat) > 0 {
+ var err error
+ switch v.API {
+ case api.APIOpenAICompletions:
+ err = decodeCompat(p.Compat, &v.Compat.OpenAICompletions)
+ case api.APIOpenAIResponses:
+ err = decodeCompat(p.Compat, &v.Compat.OpenAIResponses)
+ case api.APIAnthropicMessages:
+ err = decodeCompat(p.Compat, &v.Compat.AnthropicMessages)
+ case api.APIGoogleGenerativeAI:
+ err = decodeCompat(p.Compat, &v.Compat.GoogleGenerativeAI)
+ }
+ if err != nil {
+ return err
+ }
+ }
+ if len(p.ThinkingLevels) > 0 {
+ levels := api.ThinkingLevelMap{}
+ for k, val := range v.ThinkingLevels {
+ levels[k] = val
+ }
+ for k, val := range p.ThinkingLevels {
+ levels[api.ReasoningEffort(k)] = val
+ }
+ v.ThinkingLevels = levels
+ }
+ for _, raw := range p.Models {
+ if err := upsertOverlayModel(v, raw); err != nil {
+ return err
+ }
+ }
+ for id, patch := range p.ModelOverrides {
+ found := false
+ for i := range v.Models {
+ if strings.EqualFold(v.Models[i].ID, id) {
+ // Clone first, for the same reason as upsertOverlayModel: the
+ // entry's slices are shared with the built-in definition.
+ spec := cloneModelSpec(v.Models[i])
+ applyPatch(&spec, patch)
+ v.Models[i] = spec
+ found = true
+ break
+ }
+ }
+ if !found {
+ spec := ModelSpec{ID: id}
+ applyPatch(&spec, patch)
+ v.Models = append(v.Models, spec)
+ }
+ }
+ return nil
+}
+
+// maxIconBytes caps a vendor icon. Icons are base64'd into every
+// GET /models/providers response, so an oversized file is a response-size
+// problem for every viewer, not just a disk read.
+const maxIconBytes = 256 * 1024
+
+// loadOverlayIcon resolves providers.*.icon to SVG bytes.
+//
+// The bytes are handed to every viewer of the model pages as a data: URI, so
+// the path is treated as untrusted even though writing the overlay already
+// requires filesystem access: an operator (or a config-management template)
+// that points `icon` at /etc/shadow or ../../secrets must not turn the
+// provider list into a file-disclosure endpoint for read-only tenants.
+// Hence: no absolute paths, no escaping the overlay's own directory
+// (symlinks included), a size cap, and the content must really be an SVG.
+func loadOverlayIcon(baseDir, ref string) ([]byte, error) {
+ if looksLikeSVG([]byte(ref)) {
+ if len(ref) > maxIconBytes {
+ return nil, fmt.Errorf("icon: inline svg is %d bytes, limit is %d", len(ref), maxIconBytes)
+ }
+ return []byte(ref), nil
+ }
+ if filepath.IsAbs(ref) || strings.HasPrefix(ref, "/") || filepath.VolumeName(ref) != "" {
+ return nil, fmt.Errorf("icon: absolute paths are not allowed: %q", ref)
+ }
+ clean := filepath.Clean(filepath.FromSlash(ref))
+ if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+ return nil, fmt.Errorf("icon: path escapes the overlay directory: %q", ref)
+ }
+ if baseDir == "" {
+ baseDir = "."
+ }
+ full, err := resolveInsideDir(baseDir, clean)
+ if err != nil {
+ return nil, fmt.Errorf("icon: %w", err)
+ }
+ info, err := os.Stat(full)
+ if err != nil {
+ return nil, fmt.Errorf("read icon: %w", err)
+ }
+ if !info.Mode().IsRegular() {
+ return nil, fmt.Errorf("icon: %q is not a regular file", ref)
+ }
+ if info.Size() > maxIconBytes {
+ return nil, fmt.Errorf("icon: %q is %d bytes, limit is %d", ref, info.Size(), maxIconBytes)
+ }
+ data, err := os.ReadFile(full)
+ if err != nil {
+ return nil, fmt.Errorf("read icon: %w", err)
+ }
+ if len(data) > maxIconBytes {
+ return nil, fmt.Errorf("icon: %q is %d bytes, limit is %d", ref, len(data), maxIconBytes)
+ }
+ if !looksLikeSVG(data) {
+ return nil, fmt.Errorf("icon: %q is not an SVG document", ref)
+ }
+ return data, nil
+}
+
+// resolveInsideDir joins rel onto dir and fails unless the result stays
+// inside it. Both sides are resolved through EvalSymlinks so a symlink
+// planted in the overlay directory cannot point out of it; a path that does
+// not exist is compared unresolved and left to the caller's os.Stat, which
+// reports it with a clearer message.
+func resolveInsideDir(dir, rel string) (string, error) {
+ realDir, err := filepath.EvalSymlinks(dir)
+ if err != nil {
+ realDir = filepath.Clean(dir)
+ }
+ full := filepath.Join(realDir, rel)
+ if resolved, err := filepath.EvalSymlinks(full); err == nil {
+ full = resolved
+ }
+ if full != realDir && !strings.HasPrefix(full, realDir+string(filepath.Separator)) {
+ return "", fmt.Errorf("path escapes the overlay directory: %q", rel)
+ }
+ return full, nil
+}
+
+// looksLikeSVG reports whether data is an SVG document: an optional XML
+// prologue (declaration, doctype, comments, whitespace) followed by <svg.
+func looksLikeSVG(data []byte) bool {
+ s := strings.TrimPrefix(string(data), "\ufeff")
+ for {
+ s = strings.TrimSpace(s)
+ switch {
+ case strings.HasPrefix(s, "<?"):
+ s = skipPast(s, "?>")
+ case strings.HasPrefix(s, "<!--"):
+ s = skipPast(s, "-->")
+ case strings.HasPrefix(s, "<!"):
+ s = skipPast(s, ">")
+ default:
+ lower := strings.ToLower(s)
+ if !strings.HasPrefix(lower, "<svg") || len(lower) == len("<svg") {
+ return false
+ }
+ // Reject "<svgfoo": the tag must end right after the name.
+ return strings.ContainsRune(" \t\r\n>/", rune(lower[len("<svg")]))
+ }
+ if s == "" {
+ return false
+ }
+ }
+}
+
+// skipPast returns what follows the first occurrence of end, or "" if the
+// token never closes.
+func skipPast(s, end string) string {
+ i := strings.Index(s, end)
+ if i < 0 {
+ return ""
+ }
+ return s[i+len(end):]
+}
+
+// upsertOverlayModel applies one providers.*.models entry.
+//
+// A new id creates a full entry. An id that already exists is *patched*, not
+// replaced: both config/models.json.example and the docs present `models` as
+// the way to restate a known model with corrected facts, and most fields of
+// ModelSpec cannot tell "absent" from "zero" — Reasoning is a plain bool, so
+// an entry that only fixes context_window used to silently turn reasoning
+// off and drop thinking levels, compat and input along with it. Unmarshaling
+// the operator's JSON onto a copy of the stored entry leaves every key they
+// did not write exactly as it was.
+func upsertOverlayModel(v *Vendor, raw json.RawMessage) error {
+ // Decode strictly first: this is what rejects typos and wrong types, the
+ // same guarantee the rest of the overlay gives. The value is used only
+ // for the id, since the merge below re-reads the raw bytes.
+ var spec ModelSpec
+ dec := json.NewDecoder(bytesReader(raw))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&spec); err != nil {
+ return fmt.Errorf("model entry: %w", err)
+ }
+ if spec.ID == "" {
+ return fmt.Errorf("model without id")
+ }
+ for i := range v.Models {
+ if !strings.EqualFold(v.Models[i].ID, spec.ID) {
+ continue
+ }
+ // cloneModelSpec first: the vendor's Models slice was only shallow
+ // copied, so unmarshaling into the entry's slices/maps in place would
+ // write through to the built-in vendor's package-level definition.
+ merged := cloneModelSpec(v.Models[i])
+ if err := json.Unmarshal(raw, &merged); err != nil {
+ return fmt.Errorf("model %s: %w", spec.ID, err)
+ }
+ v.Models[i] = merged
+ return nil
+ }
+ v.Models = append(v.Models, spec)
+ return nil
+}
+
+// cloneModelSpec deep-copies the reference-typed fields of a spec.
+func cloneModelSpec(m ModelSpec) ModelSpec {
+ out := m
+ out.Input = append([]string(nil), m.Input...)
+ out.Aliases = append([]string(nil), m.Aliases...)
+ out.Compat = append(json.RawMessage(nil), m.Compat...)
+ if m.ThinkingLevels != nil {
+ levels := make(api.ThinkingLevelMap, len(m.ThinkingLevels))
+ for k, v := range m.ThinkingLevels {
+ levels[k] = v
+ }
+ out.ThinkingLevels = levels
+ }
+ return out
+}
+
+func applyPatch(m *ModelSpec, p ModelSpecPatch) {
+ if p.Name != "" {
+ m.Name = p.Name
+ }
+ if p.API != "" {
+ m.API = p.API
+ }
+ if p.Reasoning != nil {
+ m.Reasoning = *p.Reasoning
+ }
+ if len(p.Input) > 0 {
+ m.Input = p.Input
+ }
+ if p.ContextWindow > 0 {
+ m.ContextWindow = p.ContextWindow
+ }
+ if p.MaxOutputTokens > 0 {
+ m.MaxOutputTokens = p.MaxOutputTokens
+ }
+ if p.Cost != nil {
+ m.Cost = p.Cost
+ }
+ if len(p.ThinkingLevels) > 0 {
+ levels := api.ThinkingLevelMap{}
+ for k, v := range m.ThinkingLevels {
+ levels[k] = v
+ }
+ for k, v := range p.ThinkingLevels {
+ levels[k] = v
+ }
+ m.ThinkingLevels = levels
+ }
+ if len(p.Compat) > 0 {
+ m.Compat = mergeRawObjects(m.Compat, p.Compat)
+ }
+ if len(p.Aliases) > 0 {
+ m.Aliases = append(m.Aliases, p.Aliases...)
+ }
+ if p.Deprecated != nil {
+ m.Deprecated = *p.Deprecated
+ }
+}
+
+// mergeRawObjects shallow-merges two JSON objects (b wins).
+func mergeRawObjects(a, b json.RawMessage) json.RawMessage {
+ merged := map[string]json.RawMessage{}
+ if len(a) > 0 {
+ _ = json.Unmarshal(a, &merged)
+ }
+ patch := map[string]json.RawMessage{}
+ if len(b) > 0 {
+ _ = json.Unmarshal(b, &patch)
+ }
+ for k, v := range patch {
+ merged[k] = v
+ }
+ out, _ := json.Marshal(merged)
+ return out
+}
+
+// ModelsFile is the schema of a vendor's embedded models.json.
+type ModelsFile struct {
+ Vendor string `json:"vendor"`
+ Source string `json:"source,omitempty"`
+ Models []ModelSpec `json:"models"`
+}
+
+// MustParseModels decodes an embedded models.json; vendors call it from
+// package init, so a malformed file fails the build's tests immediately.
+func MustParseModels(data []byte) []ModelSpec {
+ var file ModelsFile
+ dec := json.NewDecoder(bytesReader(data))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&file); err != nil {
+ panic(fmt.Sprintf("catalog: invalid models.json: %v", err))
+ }
+ // The file-level source is the vendor's model documentation, and most
+ // entries omit their own because that page covers them. Pushing it down
+ // means every entry can answer "where is this documented" — the editor
+ // links to it from the model picker.
+ for i := range file.Models {
+ if file.Models[i].Source == "" {
+ file.Models[i].Source = file.Source
+ }
+ }
+ return file.Models
+}
diff --git a/internal/models/catalog/overlay_test.go b/internal/models/catalog/overlay_test.go
new file mode 100644
index 000000000..8ebd8ddf8
--- /dev/null
+++ b/internal/models/catalog/overlay_test.go
@@ -0,0 +1,200 @@
+package catalog
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// An overlay entry under "models" that restates an existing id must patch it.
+// The docs and config/models.json.example both present "models" as the way to
+// correct a known model, and ModelSpec cannot tell absent from zero: before
+// this, fixing max_output_tokens alone silently cleared reasoning (a plain
+// bool), the thinking levels, the compat overlay and the input modalities.
+func TestApplyOverlay_ModelsUpsertPatchesExistingEntry(t *testing.T) {
+ registerTestVendors(t)
+ overlay := `{"providers": {"acme": {"models": [
+ {"id": "acme-pro", "max_output_tokens": 8192},
+ {"id": "acme-r1", "context_window": 128000}
+ ]}}}`
+ require.NoError(t, ApplyOverlay([]byte(overlay), t.TempDir()))
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-pro"})
+ require.NoError(t, err)
+ assert.True(t, r.Spec.Reasoning, "omitted reasoning must not turn thinking off")
+ assert.Equal(t, []string{"text", "image"}, r.Spec.Input, "omitted input survives")
+ assert.Equal(t, 200000, r.Spec.ContextWindow, "omitted context_window survives")
+ assert.Equal(t, 8192, r.Spec.MaxOutputTokens, "the field that was written is applied")
+ assert.False(t, r.OpenAICompletions.SupportsTemperature, "omitted compat survives")
+
+ r, err = Resolve(Ref{Provider: "acme", Model: "acme-r1"})
+ require.NoError(t, err)
+ assert.True(t, r.Spec.Reasoning)
+ assert.Equal(t, 128000, r.Spec.ContextWindow)
+ assert.False(t, r.ThinkingLevels.Supports(api.ReasoningOff),
+ "omitted thinking_levels survive: acme-r1 still cannot be switched off")
+}
+
+// Patching must not write through to the built-in definition: the vendor copy
+// made by ApplyOverlay is shallow, so the spec's slices and maps are shared
+// with the vendor package's own (package-level) models.json data.
+func TestApplyOverlay_ModelsUpsertDoesNotMutateBuiltinVendor(t *testing.T) {
+ registerTestVendors(t)
+ builtin, ok := Get("acme")
+ require.True(t, ok)
+
+ overlay := `{"providers": {"acme": {"models": [{"id": "acme-pro", "input": ["audio"]}]}}}`
+ require.NoError(t, ApplyOverlay([]byte(overlay), t.TempDir()))
+
+ require.Equal(t, "acme-pro", builtin.Models[0].ID)
+ assert.Equal(t, []string{"text", "image"}, builtin.Models[0].Input,
+ "the built-in spec must be untouched by the overlay")
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-pro"})
+ require.NoError(t, err)
+ assert.Equal(t, []string{"audio"}, r.Spec.Input, "the written field is still applied")
+}
+
+func TestApplyOverlay_ModelsUpsertExplicitFalseAndNewEntries(t *testing.T) {
+ registerTestVendors(t)
+ overlay := `{"providers": {"acme": {"models": [
+ {"id": "acme-pro", "reasoning": false},
+ {"id": "acme-ultra", "context_window": 400000}
+ ]}}}`
+ require.NoError(t, ApplyOverlay([]byte(overlay), t.TempDir()))
+
+ r, err := Resolve(Ref{Provider: "acme", Model: "acme-pro"})
+ require.NoError(t, err)
+ assert.False(t, r.Spec.Reasoning, "an explicit false still turns reasoning off")
+
+ r, err = Resolve(Ref{Provider: "acme", Model: "acme-ultra"})
+ require.NoError(t, err)
+ assert.True(t, r.Cataloged, "an unknown id creates a full entry")
+ assert.Equal(t, 400000, r.Spec.ContextWindow)
+ assert.False(t, r.Spec.Reasoning)
+}
+
+func TestApplyOverlay_ModelsEntryValidation(t *testing.T) {
+ registerTestVendors(t)
+ dir := t.TempDir()
+ assert.ErrorContains(t,
+ ApplyOverlay([]byte(`{"providers": {"acme": {"models": [{"id": "x", "bogus": 1}]}}}`), dir),
+ "bogus", "unknown keys inside a model entry are still rejected")
+ assert.ErrorContains(t,
+ ApplyOverlay([]byte(`{"providers": {"acme": {"models": [{"context_window": 1}]}}}`), dir),
+ "model without id")
+}
+
+const testSVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"></svg>`
+
+func overlayWithIcon(icon string) string {
+ return `{"providers": {"lab": {"icon": ` + quoteJSON(icon) + `}}}`
+}
+
+// quoteJSON is enough for the paths used here (no escaping needed).
+func quoteJSON(s string) string { return `"` + strings.ReplaceAll(s, `"`, `\"`) + `"` }
+
+func TestApplyOverlay_IconAcceptsInlineAndContainedFiles(t *testing.T) {
+ registerTestVendors(t)
+ dir := t.TempDir()
+ require.NoError(t, os.MkdirAll(filepath.Join(dir, "icons"), 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "icons", "lab.svg"), []byte(testSVG), 0o600))
+
+ require.NoError(t, ApplyOverlay([]byte(overlayWithIcon("icons/lab.svg")), dir))
+ lab, ok := Get("lab")
+ require.True(t, ok)
+ assert.Equal(t, testSVG, string(lab.Icon))
+
+ require.NoError(t, ApplyOverlay([]byte(overlayWithIcon("<svg><rect/></svg>")), dir))
+ lab, _ = Get("lab")
+ assert.Equal(t, "<svg><rect/></svg>", string(lab.Icon))
+}
+
+// The icon bytes are served as a data: URI to every viewer of the model
+// pages, so an overlay must not be able to turn the provider list into a
+// file-disclosure endpoint.
+func TestApplyOverlay_IconRejectsUncontainedPaths(t *testing.T) {
+ registerTestVendors(t)
+ dir := t.TempDir()
+ outside := filepath.Join(t.TempDir(), "secret.svg")
+ require.NoError(t, os.WriteFile(outside, []byte(testSVG), 0o600))
+
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon(outside)), dir),
+ "absolute paths are not allowed")
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("/etc/passwd")), dir),
+ "absolute paths are not allowed")
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("../secret.svg")), dir),
+ "escapes the overlay directory")
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("icons/../../secret.svg")), dir),
+ "escapes the overlay directory")
+
+ link := filepath.Join(dir, "link.svg")
+ if err := os.Symlink(outside, link); err == nil {
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("link.svg")), dir),
+ "escapes the overlay directory", "a symlink out of the directory is still out of it")
+ }
+
+ _, exists := Get("lab")
+ assert.False(t, exists, "a rejected icon must not register the provider")
+}
+
+func TestApplyOverlay_IconRejectsNonSVGAndOversizedFiles(t *testing.T) {
+ registerTestVendors(t)
+ dir := t.TempDir()
+
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "passwd.svg"), []byte("root:x:0:0:root:/root:/bin/sh\n"), 0o600))
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("passwd.svg")), dir), "not an SVG document")
+
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "png.svg"), []byte("\x89PNG\r\n\x1a\n"), 0o600))
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("png.svg")), dir), "not an SVG document")
+
+ big := append([]byte(`<svg xmlns="http://www.w3.org/2000/svg">`), make([]byte, maxIconBytes)...)
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "big.svg"), big, 0o600))
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("big.svg")), dir), "limit is")
+
+ require.NoError(t, os.MkdirAll(filepath.Join(dir, "dir.svg"), 0o755))
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("dir.svg")), dir), "not a regular file")
+
+ assert.ErrorContains(t, ApplyOverlay([]byte(overlayWithIcon("missing.svg")), dir), "read icon")
+}
+
+func TestLooksLikeSVG(t *testing.T) {
+ for _, in := range []string{
+ testSVG,
+ " \n<svg/>",
+ "\ufeff<?xml version=\"1.0\"?>\n<!-- brand mark --><svg >x</svg>",
+ "<?xml version=\"1.0\"?><!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\" \"x.dtd\"><svg>y</svg>",
+ "<SVG></SVG>",
+ } {
+ assert.True(t, looksLikeSVG([]byte(in)), "want SVG: %q", in)
+ }
+ for _, in := range []string{
+ "", " ", "<svg", "<svgx>", "not markup at all",
+ "<html><svg></svg></html>", "<?xml version=\"1.0\"?>", "<!-- unterminated",
+ "root:x:0:0::/root:/bin/sh",
+ } {
+ assert.False(t, looksLikeSVG([]byte(in)), "want not SVG: %q", in)
+ }
+}
+
+// The icon path is relative to the overlay file's own directory.
+func TestLoadOverlay_ResolvesIconRelativeToConfigDir(t *testing.T) {
+ registerTestVendors(t)
+ dir := t.TempDir()
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "lab.svg"), []byte(testSVG), 0o600))
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "models.json"),
+ []byte(overlayWithIcon("lab.svg")), 0o600))
+ t.Setenv("MODELS_CONFIG", "")
+
+ require.NoError(t, LoadOverlay(dir))
+ lab, ok := Get("lab")
+ require.True(t, ok)
+ assert.Equal(t, testSVG, string(lab.Icon))
+ assert.Equal(t, []types.ModelType{types.ModelTypeKnowledgeQA}, lab.ModelTypes)
+}
diff --git a/internal/models/catalog/registry.go b/internal/models/catalog/registry.go
new file mode 100644
index 000000000..009822ff7
--- /dev/null
+++ b/internal/models/catalog/registry.go
@@ -0,0 +1,254 @@
+package catalog
+
+import (
+ "bytes"
+ "fmt"
+ "sort"
+ "strings"
+ "sync"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// GenericID is the catch-all vendor for any OpenAI-compatible endpoint.
+const GenericID = "generic"
+
+var (
+ mu sync.RWMutex
+ vendors = map[string]*Vendor{}
+)
+
+// Register adds a built-in vendor. Registering the same id twice replaces
+// the earlier definition (the deployment overlay relies on this).
+func Register(v *Vendor) {
+ if v == nil || v.ID == "" {
+ panic("catalog: vendor without id")
+ }
+ if v.API == "" {
+ v.API = api.APIOpenAICompletions
+ }
+ if v.Auth == "" {
+ v.Auth = AuthBearer
+ }
+ for i := range v.Models {
+ if v.Models[i].Type == "" {
+ v.Models[i].Type = types.ModelTypeKnowledgeQA
+ }
+ if v.Models[i].API == "" && v.Models[i].Type == types.ModelTypeKnowledgeQA {
+ v.Models[i].API = v.API
+ }
+ }
+ mu.Lock()
+ defer mu.Unlock()
+ vendors[v.ID] = v
+}
+
+// Get returns a vendor by id.
+func Get(id string) (*Vendor, bool) {
+ mu.RLock()
+ defer mu.RUnlock()
+ v, ok := vendors[strings.ToLower(strings.TrimSpace(id))]
+ return v, ok
+}
+
+// GetOrGeneric returns the vendor or the generic catch-all. When no vendor
+// package is linked into the binary (unit tests of leaf packages), a
+// built-in generic definition keeps resolution working.
+func GetOrGeneric(id string) *Vendor {
+ if v, ok := Get(id); ok {
+ return v
+ }
+ if v, ok := Get(GenericID); ok {
+ return v
+ }
+ return fallbackGeneric
+}
+
+// fallbackGeneric mirrors internal/models/vendors/generic so behaviour does
+// not depend on whether that package was imported.
+var fallbackGeneric = &Vendor{
+ ID: GenericID,
+ Name: "Custom (OpenAI-compatible)",
+ API: api.APIOpenAICompletions,
+ DefaultBaseURLs: map[types.ModelType]string{},
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA, types.ModelTypeEmbedding, types.ModelTypeRerank,
+ types.ModelTypeVLLM, types.ModelTypeASR,
+ },
+ Auth: AuthBearer,
+ Compat: VendorCompat{OpenAICompletions: OpenAICompletionsCompat{
+ MaxTokensField: Ptr("max_tokens"),
+ ThinkingFormat: Ptr(ThinkingFormatChatTemplateKwargs),
+ }},
+}
+
+// List returns every vendor ordered by Order then id.
+func List() []*Vendor {
+ mu.RLock()
+ defer mu.RUnlock()
+ out := make([]*Vendor, 0, len(vendors))
+ for _, v := range vendors {
+ out = append(out, v)
+ }
+ sort.SliceStable(out, func(i, j int) bool {
+ if out[i].Order != out[j].Order {
+ return out[i].Order < out[j].Order
+ }
+ return out[i].ID < out[j].ID
+ })
+ return out
+}
+
+// ListByType returns vendors that support a model type.
+func ListByType(modelType types.ModelType) []*Vendor {
+ all := List()
+ out := make([]*Vendor, 0, len(all))
+ for _, v := range all {
+ if v.SupportsType(modelType) {
+ out = append(out, v)
+ }
+ }
+ return out
+}
+
+// DetectByURL finds the vendor whose URLPatterns match a base URL. Used only
+// when a stored model row carries no provider id. Longer patterns win so
+// "api.lkeap.cloud.tencent.com" beats "tencent".
+func DetectByURL(baseURL string) string {
+ if baseURL == "" {
+ return GenericID
+ }
+ lower := strings.ToLower(baseURL)
+ bestID, bestLen := GenericID, 0
+ for _, v := range List() {
+ for _, p := range v.URLPatterns {
+ if p != "" && strings.Contains(lower, strings.ToLower(p)) && len(p) > bestLen {
+ bestID, bestLen = v.ID, len(p)
+ }
+ }
+ }
+ return bestID
+}
+
+// ModelsByType returns the vendor's catalog entries for a model type,
+// hiding deprecated and pattern-only entries.
+func (v *Vendor) ModelsByType(modelType types.ModelType) []ModelSpec {
+ out := make([]ModelSpec, 0)
+ for _, m := range v.Models {
+ if m.Deprecated || m.ID == "" {
+ continue
+ }
+ mt := m.Type
+ if mt == "" {
+ mt = types.ModelTypeKnowledgeQA
+ }
+ switch modelType {
+ case types.ModelTypeVLLM:
+ // VLM pickers list chat models that accept images.
+ if mt == types.ModelTypeKnowledgeQA && m.AcceptsImages() {
+ out = append(out, m)
+ }
+ default:
+ if mt == modelType {
+ out = append(out, m)
+ }
+ }
+ }
+ return out
+}
+
+// FindModel looks a model name up in the vendor catalog: exact id, then
+// aliases, then glob patterns (longest literal prefix wins). Matching is
+// case-insensitive.
+func (v *Vendor) FindModel(name string) (ModelSpec, bool) {
+ needle := strings.ToLower(strings.TrimSpace(name))
+ if needle == "" {
+ return ModelSpec{}, false
+ }
+ for _, m := range v.Models {
+ if strings.ToLower(m.ID) == needle {
+ return m, true
+ }
+ }
+ for _, m := range v.Models {
+ for _, alias := range m.Aliases {
+ if strings.ToLower(alias) == needle {
+ return m, true
+ }
+ }
+ }
+ var best ModelSpec
+ bestScore := -1
+ for _, m := range v.Models {
+ if m.Match == "" {
+ continue
+ }
+ if globMatch(strings.ToLower(m.Match), needle) {
+ score := len(strings.TrimRight(strings.SplitN(m.Match, "*", 2)[0], "*"))
+ if score > bestScore {
+ best, bestScore = m, score
+ }
+ }
+ }
+ if bestScore >= 0 {
+ return best, true
+ }
+ return ModelSpec{}, false
+}
+
+// globMatch supports '*' wildcards only.
+func globMatch(pattern, s string) bool {
+ parts := strings.Split(pattern, "*")
+ if len(parts) == 1 {
+ return pattern == s
+ }
+ if !strings.HasPrefix(s, parts[0]) {
+ return false
+ }
+ s = s[len(parts[0]):]
+ for i := 1; i < len(parts)-1; i++ {
+ idx := strings.Index(s, parts[i])
+ if idx < 0 {
+ return false
+ }
+ s = s[idx+len(parts[i]):]
+ }
+ return strings.HasSuffix(s, parts[len(parts)-1])
+}
+
+func defaultValidate(v *Vendor, cfg *Config) error {
+ if cfg == nil {
+ return fmt.Errorf("config is nil")
+ }
+ if v.RequiresAuth && v.Auth != AuthSigned && strings.TrimSpace(cfg.APIKey) == "" {
+ return fmt.Errorf("API key is required for %s", v.Name)
+ }
+ if v.ID == GenericID && strings.TrimSpace(cfg.BaseURL) == "" {
+ return fmt.Errorf("base URL is required for generic provider")
+ }
+ if strings.TrimSpace(cfg.ModelName) == "" {
+ return fmt.Errorf("model name is required")
+ }
+ return nil
+}
+
+func bytesReader(b []byte) *bytes.Reader { return bytes.NewReader(b) }
+
+// reset clears the registry and returns a function that puts the previous
+// contents back (tests only). The registry is process-global, so a test that
+// merely cleared it would leave every later test in the same binary — the
+// external catalog_test package included — resolving against an empty
+// catalog, which silently turns assertions about real vendors into
+// assertions about the generic fallback.
+func reset() func() {
+ mu.Lock()
+ defer mu.Unlock()
+ previous := vendors
+ vendors = map[string]*Vendor{}
+ return func() {
+ mu.Lock()
+ defer mu.Unlock()
+ vendors = previous
+ }
+}
diff --git a/internal/models/catalog/resolve.go b/internal/models/catalog/resolve.go
new file mode 100644
index 000000000..dcf445c1f
--- /dev/null
+++ b/internal/models/catalog/resolve.go
@@ -0,0 +1,348 @@
+package catalog
+
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// Extra-config keys honoured by Resolve. They predate the catalog and stay
+// supported so existing model rows keep working unchanged.
+const (
+ // ExtraAPI forces a protocol ("openai-responses", "anthropic-messages", ...).
+ ExtraAPI = "api"
+ // ExtraRemoteModelName sends a different model id on the wire.
+ ExtraRemoteModelName = "remote_model_name"
+ // ExtraAPIVersion is the Azure api-version query parameter.
+ ExtraAPIVersion = "api_version"
+ // ExtraThinkingControl is the legacy thinking encoding selector written
+ // by older UIs: none | enable_thinking | thinking_type | chat_template_kwargs.
+ ExtraThinkingControl = "thinking_control"
+)
+
+// Ref identifies one configured model.
+type Ref struct {
+ Provider string
+ Model string
+ BaseURL string
+ ModelType types.ModelType
+ Extra map[string]string
+ Override *types.ModelSpecOverride
+}
+
+// Resolved is the fully merged view of one model: which vendor, which
+// protocol, which settings.
+type Resolved struct {
+ Vendor *Vendor
+ // Spec is the effective catalog entry (synthesized when unknown).
+ Spec ModelSpec
+ // Cataloged reports whether the model name matched a catalog entry.
+ Cataloged bool
+ API api.API
+ BaseURL string
+ // RemoteModel is the id sent on the wire.
+ RemoteModel string
+ ThinkingLevels api.ThinkingLevelMap
+
+ OpenAICompletions OpenAICompletionsSettings
+ OpenAIResponses OpenAIResponsesSettings
+ AnthropicMessages AnthropicMessagesSettings
+ GoogleGenerativeAI GoogleGenerativeAISettings
+}
+
+// Resolve merges the vendor, catalog entry, extra-config and per-row
+// overrides for a model reference. It never fails for unknown vendors or
+// models: they degrade to the generic OpenAI-compatible baseline.
+func Resolve(ref Ref) (*Resolved, error) {
+ providerID := strings.ToLower(strings.TrimSpace(ref.Provider))
+ if providerID == "" {
+ providerID = DetectByURL(ref.BaseURL)
+ }
+ vendor := GetOrGeneric(providerID)
+ if vendor == nil {
+ return nil, fmt.Errorf("catalog: no vendors registered")
+ }
+ modelType := ref.ModelType
+ if modelType == "" {
+ modelType = types.ModelTypeKnowledgeQA
+ }
+
+ baseURL := strings.TrimRight(strings.TrimSpace(ref.BaseURL), "/")
+ if baseURL == "" {
+ baseURL = strings.TrimRight(vendor.GetDefaultURL(modelType), "/")
+ }
+
+ spec, cataloged := vendor.FindModel(ref.Model)
+ if !cataloged {
+ spec = ModelSpec{ID: ref.Model, Type: types.ModelTypeKnowledgeQA}
+ }
+ if spec.API == "" {
+ spec.API = vendor.API
+ }
+ if ref.Override != nil {
+ applySpecOverride(&spec, ref.Override)
+ }
+
+ resolvedAPI := spec.API
+ if forced := strings.TrimSpace(ref.Extra[ExtraAPI]); forced != "" {
+ resolvedAPI = api.API(forced)
+ } else {
+ resolvedAPI = inferAPIFromURL(baseURL, resolvedAPI)
+ if vendor.PreferAPI != nil {
+ if preferred := vendor.PreferAPI(baseURL, spec); preferred != "" {
+ resolvedAPI = preferred
+ }
+ }
+ }
+ if !resolvedAPI.Known() {
+ return nil, fmt.Errorf("catalog: unknown api %q for provider %s", resolvedAPI, vendor.ID)
+ }
+
+ levels := api.ThinkingLevelMap{}
+ for k, v := range vendor.ThinkingLevels {
+ levels[k] = v
+ }
+ for k, v := range spec.ThinkingLevels {
+ levels[k] = v
+ }
+ if ref.Override != nil {
+ for k, v := range ref.Override.ThinkingLevels {
+ levels[api.ReasoningEffort(k)] = v
+ }
+ }
+
+ out := &Resolved{
+ Vendor: vendor,
+ Spec: spec,
+ Cataloged: cataloged,
+ API: resolvedAPI,
+ BaseURL: baseURL,
+ RemoteModel: ref.Model,
+ ThinkingLevels: levels,
+ }
+ if override := strings.TrimSpace(ref.Extra[ExtraRemoteModelName]); override != "" {
+ out.RemoteModel = override
+ }
+
+ overrideCompat := ref.Override.CompatJSON()
+
+ // Every protocol's settings are resolved so callers can inspect any of
+ // them, but only the layers whose API matches contribute model/override
+ // compat (a flat compat object is meaningless for another protocol).
+ completions := DefaultOpenAICompletions()
+ apply(&completions, &vendor.Compat.OpenAICompletions)
+ if err := applyRawCompat(
+ &completions, &OpenAICompletionsCompat{}, spec.Compat, spec.API, api.APIOpenAICompletions,
+ ); err != nil {
+ return nil, err
+ }
+ if err := applyRawCompat(
+ &completions, &OpenAICompletionsCompat{}, overrideCompat, resolvedAPI, api.APIOpenAICompletions,
+ ); err != nil {
+ return nil, err
+ }
+ applyLegacyThinkingControl(&completions, ref.Extra[ExtraThinkingControl])
+ out.OpenAICompletions = completions
+
+ responses := DefaultOpenAIResponses()
+ apply(&responses, &vendor.Compat.OpenAIResponses)
+ if err := applyRawCompat(
+ &responses, &OpenAIResponsesCompat{}, spec.Compat, spec.API, api.APIOpenAIResponses,
+ ); err != nil {
+ return nil, err
+ }
+ if err := applyRawCompat(
+ &responses, &OpenAIResponsesCompat{}, overrideCompat, resolvedAPI, api.APIOpenAIResponses,
+ ); err != nil {
+ return nil, err
+ }
+ out.OpenAIResponses = responses
+
+ anthropic := DefaultAnthropicMessages()
+ apply(&anthropic, &vendor.Compat.AnthropicMessages)
+ if err := applyRawCompat(
+ &anthropic, &AnthropicMessagesCompat{}, spec.Compat, spec.API, api.APIAnthropicMessages,
+ ); err != nil {
+ return nil, err
+ }
+ if err := applyRawCompat(
+ &anthropic, &AnthropicMessagesCompat{}, overrideCompat, resolvedAPI, api.APIAnthropicMessages,
+ ); err != nil {
+ return nil, err
+ }
+ out.AnthropicMessages = anthropic
+
+ google := DefaultGoogleGenerativeAI()
+ apply(&google, &vendor.Compat.GoogleGenerativeAI)
+ if err := applyRawCompat(
+ &google, &GoogleGenerativeAICompat{}, spec.Compat, spec.API, api.APIGoogleGenerativeAI,
+ ); err != nil {
+ return nil, err
+ }
+ if err := applyRawCompat(
+ &google, &GoogleGenerativeAICompat{}, overrideCompat, resolvedAPI, api.APIGoogleGenerativeAI,
+ ); err != nil {
+ return nil, err
+ }
+ out.GoogleGenerativeAI = google
+ // An explicit legacy thinking_control is the operator saying "this row
+ // does think, send the switch this way", so it outranks the catalog.
+ if strings.TrimSpace(ref.Extra[ExtraThinkingControl]) == "" {
+ out.silenceThinkingForNonReasoningModel()
+ }
+
+ return out, nil
+}
+
+// silenceThinkingForNonReasoningModel drops every thinking field for a
+// catalogued model the vendor documents as non-reasoning (DeepSeek's
+// non-thinking alias, LKEAP's V3-0324 generation, plain instruct models).
+// Without this, a caller that asks for thinking — an agent whose config says
+// so, or the model debug drawer — would send a switch the model does not
+// understand, and some vendors answer 400.
+//
+// The gate deliberately applies only to catalogued entries: an unknown model
+// on a self-hosted runtime carries Reasoning=false simply because nobody
+// described it, and those deployments do rely on the thinking switch.
+func (r *Resolved) silenceThinkingForNonReasoningModel() {
+ if !r.Cataloged || r.Spec.Reasoning {
+ return
+ }
+ r.OpenAICompletions.ThinkingFormat = ThinkingFormatNone
+ r.OpenAICompletions.ThinkingBudgetField = ""
+ r.OpenAICompletions.SupportsReasoningEffort = false
+ r.GoogleGenerativeAI.ThinkingMode = GoogleThinkingNone
+ r.ThinkingLevels = api.ThinkingLevelMap{}
+ for _, level := range api.ReasoningLadder {
+ r.ThinkingLevels[level] = nil
+ }
+ r.ThinkingLevels[api.ReasoningAuto] = nil
+}
+
+// applyRawCompat decodes raw into the overlay type and applies it when the
+// layer's API matches the target protocol.
+func applyRawCompat(settings any, overlayPtr any, raw json.RawMessage, layerAPI, target api.API) error {
+ if len(raw) == 0 || layerAPI != target {
+ return nil
+ }
+ if err := decodeCompat(raw, overlayPtr); err != nil {
+ return fmt.Errorf("%s compat: %w", target, err)
+ }
+ apply(settings, overlayPtr)
+ return nil
+}
+
+func applySpecOverride(spec *ModelSpec, o *types.ModelSpecOverride) {
+ if o == nil {
+ return
+ }
+ if o.API != "" {
+ spec.API = api.API(o.API)
+ }
+ if o.Reasoning != nil {
+ spec.Reasoning = *o.Reasoning
+ }
+ if len(o.Input) > 0 {
+ spec.Input = o.Input
+ }
+ if o.ContextWindow > 0 {
+ spec.ContextWindow = o.ContextWindow
+ }
+ if o.MaxOutputTokens > 0 {
+ spec.MaxOutputTokens = o.MaxOutputTokens
+ }
+}
+
+// inferAPIFromURL applies the two URL conventions vendors use to expose a
+// second protocol on a sub-path: ".../openai" for an OpenAI-compatible
+// facade (Gemini, LongCat, Novita) and ".../anthropic" for an Anthropic
+// Messages facade (MiniMax, Zhipu, Moonshot, Volcengine coding plans).
+func inferAPIFromURL(baseURL string, current api.API) api.API {
+ lower := strings.ToLower(strings.TrimRight(baseURL, "/"))
+ switch {
+ case strings.HasSuffix(lower, "/anthropic") || strings.HasSuffix(lower, "/anthropic/v1"):
+ return api.APIAnthropicMessages
+ case current == api.APIGoogleGenerativeAI &&
+ (strings.HasSuffix(lower, "/openai") || strings.Contains(lower, "/openai/")):
+ return api.APIOpenAICompletions
+ }
+ return current
+}
+
+// applyLegacyThinkingControl maps the pre-catalog thinking_control value
+// onto the new settings. Unknown non-empty values keep the historical
+// fallback (chat_template_kwargs).
+func applyLegacyThinkingControl(s *OpenAICompletionsSettings, value string) {
+ switch strings.ToLower(strings.TrimSpace(value)) {
+ case "":
+ return
+ case "none":
+ s.ThinkingFormat = ThinkingFormatNone
+ case "enable_thinking":
+ s.ThinkingFormat = ThinkingFormatEnableThinking
+ case "thinking_type":
+ s.ThinkingFormat = ThinkingFormatThinkingType
+ default:
+ s.ThinkingFormat = ThinkingFormatChatTemplateKwargs
+ }
+}
+
+// Capabilities is the UI-facing summary of a resolved model.
+type Capabilities struct {
+ Provider string `json:"provider"`
+ API api.API `json:"api"`
+ Cataloged bool `json:"cataloged"`
+ Reasoning bool `json:"reasoning"`
+ ThinkingLevels []api.ReasoningEffort `json:"thinking_levels"`
+ ThinkingFormat string `json:"thinking_format"`
+ Input []string `json:"input,omitempty"`
+ ContextWindow int `json:"context_window,omitempty"`
+ MaxOutputTokens int `json:"max_output_tokens,omitempty"`
+ MaxTokensField string `json:"max_tokens_field,omitempty"`
+}
+
+// Capabilities summarizes the resolved model for API responses.
+func (r *Resolved) Capabilities() Capabilities {
+ if r == nil {
+ return Capabilities{}
+ }
+ caps := Capabilities{
+ Provider: r.Vendor.ID,
+ API: r.API,
+ Cataloged: r.Cataloged,
+ Reasoning: r.Spec.Reasoning,
+ Input: r.Spec.Input,
+ ContextWindow: r.Spec.ContextWindow,
+ MaxOutputTokens: r.Spec.MaxOutputTokens,
+ }
+ switch r.API {
+ case api.APIOpenAICompletions:
+ caps.ThinkingFormat = string(r.OpenAICompletions.ThinkingFormat)
+ caps.MaxTokensField = r.OpenAICompletions.MaxTokensField
+ if caps.ThinkingFormat == string(ThinkingFormatNone) {
+ caps.ThinkingLevels = []api.ReasoningEffort{}
+ return caps
+ }
+ case api.APIOpenAIResponses:
+ caps.ThinkingFormat = "reasoning.effort"
+ caps.MaxTokensField = "max_output_tokens"
+ case api.APIAnthropicMessages:
+ caps.ThinkingFormat = "thinking." + string(r.AnthropicMessages.ThinkingMode)
+ caps.MaxTokensField = "max_tokens"
+ case api.APIGoogleGenerativeAI:
+ caps.ThinkingFormat = "thinkingConfig." + string(r.GoogleGenerativeAI.ThinkingMode)
+ caps.MaxTokensField = "maxOutputTokens"
+ if r.GoogleGenerativeAI.ThinkingMode == GoogleThinkingNone {
+ caps.ThinkingLevels = []api.ReasoningEffort{}
+ return caps
+ }
+ case api.APIOllama:
+ caps.ThinkingFormat = "think"
+ caps.MaxTokensField = "num_predict"
+ }
+ caps.ThinkingLevels = r.ThinkingLevels.SupportedLevels()
+ return caps
+}
diff --git a/internal/models/catalog/types.go b/internal/models/catalog/types.go
new file mode 100644
index 000000000..f3421cec0
--- /dev/null
+++ b/internal/models/catalog/types.go
@@ -0,0 +1,368 @@
+// Package catalog is the model/vendor directory. It answers one question for
+// the rest of the system: "given a provider id, a model name and whatever the
+// operator configured, how exactly do we talk to this model?"
+//
+// Facts come from three layers, lowest precedence first:
+// 1. built-in vendor packages under internal/models/vendors (vendor.go +
+// models.json + icon.svg), registered through Register;
+// 2. the deployment overlay config/models.json (same schema as pi's
+// ~/.pi/agent/models.json): new vendors, base URL / key overrides,
+// per-model overrides;
+// 3. per-model overrides stored on the models table.
+//
+// Resolve merges those layers into a Resolved value that the protocol
+// packages consume verbatim. No protocol or vendor package is imported here.
+package catalog
+
+import (
+ "encoding/json"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// AuthStyle names how a vendor expects credentials.
+type AuthStyle string
+
+const (
+ // AuthBearer sends Authorization: Bearer <key>.
+ AuthBearer AuthStyle = "bearer"
+ // AuthAPIKeyHeader sends api-key: <key> (Azure OpenAI).
+ AuthAPIKeyHeader AuthStyle = "api-key"
+ // AuthXAPIKey sends x-api-key: <key> (Anthropic).
+ AuthXAPIKey AuthStyle = "x-api-key"
+ // AuthGoogleAPIKey sends x-goog-api-key: <key> (Gemini native).
+ AuthGoogleAPIKey AuthStyle = "x-goog-api-key"
+ // AuthNone sends nothing (local deployments).
+ AuthNone AuthStyle = "none"
+ // AuthSigned delegates to the vendor's Signer hook (WeKnora Cloud).
+ AuthSigned AuthStyle = "signed"
+)
+
+// ExtraField describes one vendor-specific configuration input the model
+// editor renders dynamically (Azure api-version, LKEAP secret key, ...).
+type ExtraField struct {
+ Key string `json:"key"`
+ Label string `json:"label"`
+ Labels map[string]string `json:"labels,omitempty"`
+ Type string `json:"type"` // "string", "number", "boolean", "select", "password"
+ Required bool `json:"required"`
+ Default string `json:"default,omitempty"`
+ Placeholder string `json:"placeholder,omitempty"`
+ Options []ExtraFieldOption `json:"options,omitempty"`
+ // ModelTypes restricts the field to some model types; empty means all.
+ ModelTypes []types.ModelType `json:"model_types,omitempty"`
+ // Secret marks values that must never be echoed back to the UI.
+ Secret bool `json:"secret,omitempty"`
+}
+
+// CredentialLabel renames the primary credential input for one vendor.
+//
+// Most vendors take an API key and need none of this. LKEAP and Volcengine
+// authenticate their rerank API with a CAM / IAM identity pair instead, where
+// the first field is a SecretId / AccessKeyId — calling it "API Key" leads
+// operators to paste an `sk-` token that can never authenticate. The vendor
+// says what the field is called rather than the editor hardcoding a table of
+// vendor ids, which is what this whole layer exists to avoid.
+type CredentialLabel struct {
+ Label string `json:"label"`
+ Labels map[string]string `json:"labels,omitempty"`
+ Placeholder string `json:"placeholder,omitempty"`
+ Placeholders map[string]string `json:"placeholders,omitempty"`
+ // Hint is rendered under the input, for a warning the label cannot carry.
+ Hint string `json:"hint,omitempty"`
+ Hints map[string]string `json:"hints,omitempty"`
+ // ModelTypes restricts the override; empty means every type.
+ ModelTypes []types.ModelType `json:"model_types,omitempty"`
+ // Required marks the credential mandatory even where the generic label
+ // calls it optional.
+ Required bool `json:"required,omitempty"`
+}
+
+// LocalizedLabel / LocalizedPlaceholder / LocalizedHint resolve one locale,
+// falling back to the default string.
+func (c CredentialLabel) LocalizedLabel(locale string) string {
+ return localizedOr(c.Labels, locale, c.Label)
+}
+
+// LocalizedPlaceholder resolves the placeholder for a locale.
+func (c CredentialLabel) LocalizedPlaceholder(locale string) string {
+ return localizedOr(c.Placeholders, locale, c.Placeholder)
+}
+
+// LocalizedHint resolves the hint for a locale.
+func (c CredentialLabel) LocalizedHint(locale string) string {
+ return localizedOr(c.Hints, locale, c.Hint)
+}
+
+func localizedOr(table map[string]string, locale, fallback string) string {
+ if v, ok := table[locale]; ok && v != "" {
+ return v
+ }
+ return fallback
+}
+
+// CredentialLabelFor returns the credential naming for a model type, or nil
+// when the vendor uses the generic API-key wording.
+func (v *Vendor) CredentialLabelFor(modelType types.ModelType) *CredentialLabel {
+ for i := range v.CredentialLabels {
+ c := &v.CredentialLabels[i]
+ if len(c.ModelTypes) == 0 {
+ return c
+ }
+ for _, mt := range c.ModelTypes {
+ if mt == modelType {
+ return c
+ }
+ }
+ }
+ return nil
+}
+
+// ExtraFieldOption is one choice of a select field.
+type ExtraFieldOption struct {
+ Label string `json:"label"`
+ Value string `json:"value"`
+}
+
+// ModelCost is priced per million tokens, in USD unless Currency says otherwise.
+type ModelCost struct {
+ Input float64 `json:"input"`
+ Output float64 `json:"output"`
+ CacheRead float64 `json:"cache_read,omitempty"`
+ CacheWrite float64 `json:"cache_write,omitempty"`
+ Currency string `json:"currency,omitempty"`
+}
+
+// ModelSpec is one entry of a vendor's models.json.
+//
+// Only ID is required. API defaults to the vendor's API; Type defaults to
+// KnowledgeQA. Compat is interpreted according to API (see compat.go).
+type ModelSpec struct {
+ ID string `json:"id"`
+ Name string `json:"name,omitempty"`
+ // Type is the WeKnora model type this entry describes. Chat models with
+ // image input are still KnowledgeQA; the UI derives VLM eligibility from
+ // Input. Embedding / Rerank / ASR entries exist for the model picker.
+ Type types.ModelType `json:"type,omitempty"`
+ API api.API `json:"api,omitempty"`
+ // Aliases are additional ids that resolve to this entry (dated
+ // snapshots, vendor-prefixed names on gateways).
+ Aliases []string `json:"aliases,omitempty"`
+ // Match is a case-insensitive glob ("gpt-5*", "*deepseek-r1*") that lets
+ // one entry describe a family. Exact ids and aliases win over patterns;
+ // among patterns the longest literal prefix wins.
+ Match string `json:"match,omitempty"`
+ // Reasoning reports whether the model can emit thinking at all.
+ Reasoning bool `json:"reasoning"`
+ // Input lists accepted modalities: text, image, audio, video.
+ Input []string `json:"input,omitempty"`
+ ContextWindow int `json:"context_window,omitempty"`
+ MaxOutputTokens int `json:"max_output_tokens,omitempty"`
+ Cost *ModelCost `json:"cost,omitempty"`
+ // ThinkingLevels maps protocol-neutral levels to vendor values; missing
+ // keys inherit the vendor map. See api.ThinkingLevelMap.
+ ThinkingLevels api.ThinkingLevelMap `json:"thinking_levels,omitempty"`
+ // Compat is the protocol-specific overlay for this model (flat object,
+ // fields depend on API). Decoded lazily by Resolve.
+ Compat json.RawMessage `json:"compat,omitempty"`
+ // Dimension is the embedding vector width (embedding entries only).
+ Dimension int `json:"dimension,omitempty"`
+ // Deprecated hides the entry from pickers but keeps resolution working.
+ Deprecated bool `json:"deprecated,omitempty"`
+ // Source is the documentation URL the facts were taken from.
+ Source string `json:"source,omitempty"`
+}
+
+// DisplayName returns Name or the id.
+func (m ModelSpec) DisplayName() string {
+ if m.Name != "" {
+ return m.Name
+ }
+ return m.ID
+}
+
+// AcceptsImages reports whether Input lists image.
+func (m ModelSpec) AcceptsImages() bool {
+ for _, in := range m.Input {
+ if in == "image" {
+ return true
+ }
+ }
+ return false
+}
+
+// Credentials is what the operator stored for one model row.
+type Credentials struct {
+ APIKey string
+ AppID string
+ AppSecret string
+}
+
+// EndpointRequest is the input to a vendor's Endpoint hook.
+type EndpointRequest struct {
+ BaseURL string
+ Model string
+ ModelType types.ModelType
+ API api.API
+ Extra map[string]string
+}
+
+// Vendor is one model vendor / gateway / self-hosted runtime.
+type Vendor struct {
+ // ID is the stable identifier stored in models.parameters.provider.
+ ID string
+ // Name is the brand name; Names carries localized variants keyed by
+ // locale ("zh-CN"). Description / Descriptions likewise.
+ Name string
+ Names map[string]string
+ Description string
+ Descriptions map[string]string
+ Website string
+ // Icon is the brand mark as SVG bytes (served inline to the UI).
+ Icon []byte
+ // API is the default chat protocol; a ModelSpec may override it.
+ API api.API
+ // DefaultBaseURLs by model type; GetDefaultURL falls back to chat.
+ DefaultBaseURLs map[types.ModelType]string
+ ModelTypes []types.ModelType
+ RequiresAuth bool
+ Auth AuthStyle
+ // AuthByAPI overrides Auth for one protocol. A vendor that exposes a
+ // second protocol on a sub-path may authenticate it differently: Gemini's
+ // OpenAI-compatible facade documents Authorization: Bearer while the
+ // native generateContent API takes x-goog-api-key. Protocols absent from
+ // the map use Auth.
+ AuthByAPI map[api.API]AuthStyle
+ // URLPatterns are substrings of a base URL that identify this vendor
+ // when the operator left provider empty (legacy rows).
+ URLPatterns []string
+ ExtraFields []ExtraField
+ // CredentialLabels rename the primary credential input per model type.
+ CredentialLabels []CredentialLabel
+ // Compat holds vendor-level protocol defaults.
+ Compat VendorCompat
+ // ThinkingLevels is the vendor-level level map.
+ ThinkingLevels api.ThinkingLevelMap
+ // Models is the built-in catalog (from models.json).
+ Models []ModelSpec
+ // Order sorts the vendor list in the UI (lower first).
+ Order int
+
+ // Endpoint, when set, computes the request URL instead of the protocol
+ // default (BaseURL + protocol path). Returning "" falls back.
+ Endpoint func(req EndpointRequest) (url string, query map[string]string)
+ // PreferAPI, when set, may switch the protocol for a base URL / model
+ // pair after URL inference ran (OpenAI uses Responses on its own host
+ // and Chat Completions on relays). Returning "" keeps the current choice.
+ PreferAPI func(baseURL string, spec ModelSpec) api.API
+ // Signer, when set (AuthSigned), builds the request signer from the
+ // stored credentials.
+ Signer func(creds Credentials) api.AuthFunc
+ // Validate checks a configuration before it is saved or used. Nil means
+ // the default check (key required when RequiresAuth; model name required).
+ Validate func(cfg *Config) error
+ // Headers are static headers sent on every request (vendor betas).
+ Headers map[string]string
+ // DefaultAPIKey is a deployment-level key from config/models.json used
+ // when the model row stores none.
+ DefaultAPIKey string
+}
+
+// Config is the operator-supplied configuration of one model row.
+type Config struct {
+ Provider string
+ BaseURL string
+ APIKey string
+ ModelName string
+ ModelID string
+ ModelType types.ModelType
+ Extra map[string]string
+}
+
+// GetDefaultURL returns the default base URL for a model type, falling back
+// to the chat URL.
+func (v *Vendor) GetDefaultURL(modelType types.ModelType) string {
+ if v == nil {
+ return ""
+ }
+ if url, ok := v.DefaultBaseURLs[modelType]; ok {
+ return url
+ }
+ if url, ok := v.DefaultBaseURLs[types.ModelTypeKnowledgeQA]; ok {
+ return url
+ }
+ return ""
+}
+
+// SupportsType reports whether the vendor lists the model type.
+func (v *Vendor) SupportsType(modelType types.ModelType) bool {
+ for _, t := range v.ModelTypes {
+ if t == modelType {
+ return true
+ }
+ }
+ return false
+}
+
+// LocalizedName returns the name for a locale, falling back to Name.
+func (v *Vendor) LocalizedName(locale string) string {
+ if n, ok := v.Names[locale]; ok && n != "" {
+ return n
+ }
+ return v.Name
+}
+
+// LocalizedDescription returns the description for a locale.
+func (v *Vendor) LocalizedDescription(locale string) string {
+ if d, ok := v.Descriptions[locale]; ok && d != "" {
+ return d
+ }
+ return v.Description
+}
+
+// AuthStyleFor returns the auth style this vendor uses for one protocol,
+// falling back to the vendor-wide Auth.
+func (v *Vendor) AuthStyleFor(protocol api.API) AuthStyle {
+ if style, ok := v.AuthByAPI[protocol]; ok && style != "" {
+ return style
+ }
+ return v.Auth
+}
+
+// AuthFunc builds the request authenticator for the stored credentials. The
+// protocol matters because a vendor that serves a second protocol on a
+// sub-path may authenticate it differently (see Vendor.AuthByAPI).
+func (v *Vendor) AuthFunc(protocol api.API, creds Credentials) api.AuthFunc {
+ switch v.AuthStyleFor(protocol) {
+ case AuthAPIKeyHeader:
+ return api.HeaderAuth("api-key", creds.APIKey)
+ case AuthXAPIKey:
+ return api.HeaderAuth("x-api-key", creds.APIKey)
+ case AuthGoogleAPIKey:
+ return api.HeaderAuth("x-goog-api-key", creds.APIKey)
+ case AuthNone:
+ return api.NoAuth()
+ case AuthSigned:
+ if v.Signer != nil {
+ return v.Signer(creds)
+ }
+ return api.NoAuth()
+ default:
+ return api.BearerAuth(creds.APIKey)
+ }
+}
+
+// ValidateConfig runs the vendor's validation.
+func (v *Vendor) ValidateConfig(cfg *Config) error {
+ if v.Validate != nil {
+ return v.Validate(cfg)
+ }
+ return defaultValidate(v, cfg)
+}
+
+// IconContentType is the media type of vendor icons served inline.
+const IconContentType = "image/svg+xml"
+
+// Ptr returns a pointer to v; vendor packages use it to fill overlay structs.
+func Ptr[T any](v T) *T { return &v }
diff --git a/internal/models/catalog/validate.go b/internal/models/catalog/validate.go
new file mode 100644
index 000000000..5851cffdf
--- /dev/null
+++ b/internal/models/catalog/validate.go
@@ -0,0 +1,45 @@
+package catalog
+
+import (
+ "fmt"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// ValidateRow checks that a stored model row resolves against the catalog.
+//
+// It is the one gate shared by every write path — the REST create/update
+// handlers and the declarative builtin_models.yaml loader — so an unknown
+// protocol, a bad compat key or an invalid thinking level is rejected where
+// it is written instead of surfacing as a failed chat call much later.
+//
+// Embedding, rerank and ASR rows return nil without being checked, and that
+// is deliberate rather than an oversight: those clients do not resolve
+// through the catalog at all (they read the provider and base URL directly),
+// so there is no protocol or compat for a spec to be wrong about. The
+// consequence worth knowing is that a spec stored on such a row is inert —
+// it is neither validated nor applied.
+func ValidateRow(modelName string, modelType types.ModelType, params *types.ModelParameters) error {
+ if params == nil || (modelType != types.ModelTypeKnowledgeQA && modelType != types.ModelTypeVLLM) {
+ return nil
+ }
+ if params.Spec != nil {
+ for level := range params.Spec.ThinkingLevels {
+ if _, ok := api.ParseReasoningEffort(level); !ok || level == "" {
+ return fmt.Errorf("spec.thinking_levels: unknown level %q", level)
+ }
+ }
+ }
+ if _, err := Resolve(Ref{
+ Provider: params.Provider,
+ Model: modelName,
+ BaseURL: params.BaseURL,
+ ModelType: modelType,
+ Extra: params.ExtraConfig,
+ Override: params.Spec,
+ }); err != nil {
+ return fmt.Errorf("model parameters: %w", err)
+ }
+ return nil
+}
diff --git a/internal/models/catalog/validate_test.go b/internal/models/catalog/validate_test.go
new file mode 100644
index 000000000..5f356ea84
--- /dev/null
+++ b/internal/models/catalog/validate_test.go
@@ -0,0 +1,70 @@
+package catalog_test
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+func TestValidateRow(t *testing.T) {
+ cases := []struct {
+ name string
+ modelName string
+ modelType types.ModelType
+ params *types.ModelParameters
+ wantErr bool
+ }{
+ {
+ name: "nil parameters", modelName: "x", modelType: types.ModelTypeKnowledgeQA,
+ },
+ {
+ name: "embedding rows carry no catalog parameters", modelName: "text-embedding-v4",
+ modelType: types.ModelTypeEmbedding,
+ params: &types.ModelParameters{Provider: "aliyun", Spec: &types.ModelSpecOverride{API: "nope"}},
+ },
+ {
+ name: "a catalogued chat row resolves", modelName: "deepseek-v4-pro",
+ modelType: types.ModelTypeKnowledgeQA,
+ params: &types.ModelParameters{Provider: "deepseek"},
+ },
+ {
+ name: "unknown protocol is rejected", modelName: "deepseek-v4-pro",
+ modelType: types.ModelTypeKnowledgeQA,
+ params: &types.ModelParameters{
+ Provider: "deepseek", Spec: &types.ModelSpecOverride{API: "openai-chat-v9"},
+ },
+ wantErr: true,
+ },
+ {
+ name: "misspelled thinking level is rejected", modelName: "deepseek-v4-pro",
+ modelType: types.ModelTypeKnowledgeQA,
+ params: &types.ModelParameters{
+ Provider: "deepseek",
+ Spec: &types.ModelSpecOverride{ThinkingLevels: map[string]*string{"hgih": nil}},
+ },
+ wantErr: true,
+ },
+ {
+ name: "unknown compat key is rejected", modelName: "deepseek-v4-pro",
+ modelType: types.ModelTypeKnowledgeQA,
+ params: &types.ModelParameters{
+ Provider: "deepseek",
+ Spec: &types.ModelSpecOverride{Compat: map[string]any{"max_tokens_fields": "max_tokens"}},
+ },
+ wantErr: true,
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ err := catalog.ValidateRow(tc.modelName, tc.modelType, tc.params)
+ if tc.wantErr && err == nil {
+ t.Fatalf("expected an error, got nil")
+ }
+ if !tc.wantErr && err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ })
+ }
+}
diff --git a/internal/models/chat/anthropic.go b/internal/models/chat/anthropic.go
deleted file mode 100644
index da8a89e21..000000000
--- a/internal/models/chat/anthropic.go
+++ /dev/null
@@ -1,582 +0,0 @@
-package chat
-
-import (
- "bytes"
- "context"
- "encoding/json"
- "fmt"
- "io"
- "net/http"
- "net/url"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/Tencent/WeKnora/internal/types"
- secutils "github.com/Tencent/WeKnora/internal/utils"
-)
-
-const anthropicVersion = "2023-06-01"
-
-type AnthropicChat struct {
- modelName string
- modelID string
- baseURL string
- apiKey string
- customHeaders map[string]string
-}
-
-type anthropicCacheControl struct {
- Type string `json:"type"`
- TTL string `json:"ttl,omitempty"`
-}
-
-type anthropicContentBlock struct {
- Type string `json:"type"`
- Text string `json:"text,omitempty"`
- CacheControl *anthropicCacheControl `json:"cache_control,omitempty"`
- ID string `json:"id,omitempty"`
- Name string `json:"name,omitempty"`
- Input json.RawMessage `json:"input,omitempty"`
- ToolUseID string `json:"tool_use_id,omitempty"`
- Content any `json:"content,omitempty"`
-}
-
-type anthropicMessage struct {
- Role string `json:"role"`
- Content any `json:"content"`
-}
-
-type anthropicRequest struct {
- Model string `json:"model"`
- MaxTokens int `json:"max_tokens"`
- Stream bool `json:"stream,omitempty"`
- System any `json:"system,omitempty"`
- Messages []anthropicMessage `json:"messages"`
- Temperature *float64 `json:"temperature,omitempty"`
- TopP *float64 `json:"top_p,omitempty"`
- Tools []anthropicTool `json:"tools,omitempty"`
- ToolChoice *anthropicToolChoice `json:"tool_choice,omitempty"`
-}
-
-type anthropicResponse struct {
- ID string `json:"id"`
- Type string `json:"type"`
- Role string `json:"role"`
- Content []struct {
- Type string `json:"type"`
- Text string `json:"text"`
- ID string `json:"id"`
- Name string `json:"name"`
- Input json.RawMessage `json:"input"`
- } `json:"content"`
- StopReason string `json:"stop_reason"`
- Usage struct {
- InputTokens int `json:"input_tokens"`
- OutputTokens int `json:"output_tokens"`
- CacheCreationInputTokens *int `json:"cache_creation_input_tokens"`
- CacheReadInputTokens *int `json:"cache_read_input_tokens"`
- } `json:"usage"`
- Error *struct {
- Type string `json:"type"`
- Message string `json:"message"`
- } `json:"error,omitempty"`
-}
-
-type anthropicStreamEvent struct {
- Type string `json:"type"`
- Index int `json:"index"`
- ContentBlock *anthropicContentBlock `json:"content_block,omitempty"`
- Message *struct {
- Usage struct {
- InputTokens int `json:"input_tokens"`
- OutputTokens int `json:"output_tokens"`
- CacheCreationInputTokens *int `json:"cache_creation_input_tokens"`
- CacheReadInputTokens *int `json:"cache_read_input_tokens"`
- } `json:"usage"`
- } `json:"message,omitempty"`
- Delta *struct {
- Type string `json:"type"`
- Text string `json:"text"`
- StopReason string `json:"stop_reason"`
- PartialJSON string `json:"partial_json"`
- } `json:"delta,omitempty"`
- Usage *struct {
- InputTokens int `json:"input_tokens"`
- OutputTokens int `json:"output_tokens"`
- CacheCreationInputTokens *int `json:"cache_creation_input_tokens"`
- CacheReadInputTokens *int `json:"cache_read_input_tokens"`
- } `json:"usage,omitempty"`
- Error *struct {
- Type string `json:"type"`
- Message string `json:"message"`
- } `json:"error,omitempty"`
-}
-
-func NewAnthropicChat(config *ChatConfig) (*AnthropicChat, error) {
- if config.BaseURL != "" {
- if err := secutils.ValidateURLForSSRF(config.BaseURL); err != nil {
- return nil, fmt.Errorf("baseURL SSRF check failed: %w", err)
- }
- }
- if strings.TrimSpace(config.APIKey) == "" {
- return nil, fmt.Errorf("Anthropic provider: API key is required")
- }
-
- baseURL := strings.TrimRight(config.BaseURL, "/")
- if baseURL == "" {
- baseURL = provider.AnthropicBaseURL
- }
-
- return &AnthropicChat{
- modelName: config.ModelName,
- modelID: config.ModelID,
- baseURL: baseURL,
- apiKey: config.APIKey,
- customHeaders: config.CustomHeaders,
- }, nil
-}
-
-func (c *AnthropicChat) Chat(ctx context.Context, messages []Message, opts *ChatOptions) (*types.ChatResponse, error) {
- reqBody := c.buildRequest(ctx, messages, opts)
- jsonData, err := json.Marshal(reqBody)
- if err != nil {
- return nil, fmt.Errorf("marshal request: %w", err)
- }
-
- ctx, cancel := withLLMTimeout(ctx, defaultChatTimeout)
- defer cancel()
-
- endpoint := c.endpoint()
- if err := secutils.ValidateURLForSSRF(endpoint); err != nil {
- return nil, fmt.Errorf("endpoint SSRF check failed: %w", err)
- }
-
- httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewBuffer(jsonData))
- if err != nil {
- return nil, fmt.Errorf("create request: %w", err)
- }
- httpReq.Header.Set("Content-Type", "application/json")
- httpReq.Header.Set("x-api-key", c.apiKey)
- httpReq.Header.Set("anthropic-version", anthropicVersion)
- secutils.ApplyCustomHeaders(httpReq, c.customHeaders)
-
- resp, err := rawHTTPClient.Do(httpReq)
- if err != nil {
- return nil, fmt.Errorf("send request: %w", err)
- }
- defer resp.Body.Close()
-
- body, err := io.ReadAll(resp.Body)
- if err != nil {
- return nil, fmt.Errorf("read response: %w", err)
- }
-
- if strings.Contains(strings.ToLower(resp.Header.Get("Content-Type")), "text/event-stream") {
- chatResp, err := parseAnthropicSSE(bytes.NewReader(body))
- if err != nil {
- return nil, err
- }
- if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
- return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, chatResp.Content)
- }
- logUsage(ctx, c.modelName, &chatResp.Usage)
- return chatResp, nil
- }
-
- var chatResp anthropicResponse
- if err := json.Unmarshal(body, &chatResp); err != nil {
- return nil, fmt.Errorf("decode response: %w", err)
- }
- if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
- if chatResp.Error != nil && chatResp.Error.Message != "" {
- return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, chatResp.Error.Message)
- }
- return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, string(body))
- }
-
- result := c.parseResponse(&chatResp)
- logUsage(ctx, c.modelName, &result.Usage)
- return result, nil
-}
-
-func (c *AnthropicChat) ChatStream(ctx context.Context, messages []Message, opts *ChatOptions) (<-chan types.StreamResponse, error) {
- reqBody := c.buildRequest(ctx, messages, opts)
- reqBody.Stream = true
- jsonData, err := json.Marshal(reqBody)
- if err != nil {
- return nil, fmt.Errorf("marshal request: %w", err)
- }
-
- endpoint := c.endpoint()
- if err := secutils.ValidateURLForSSRF(endpoint); err != nil {
- return nil, fmt.Errorf("endpoint SSRF check failed: %w", err)
- }
-
- httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewBuffer(jsonData))
- if err != nil {
- return nil, fmt.Errorf("create request: %w", err)
- }
- httpReq.Header.Set("Content-Type", "application/json")
- httpReq.Header.Set("Accept", "text/event-stream")
- httpReq.Header.Set("x-api-key", c.apiKey)
- httpReq.Header.Set("anthropic-version", anthropicVersion)
- secutils.ApplyCustomHeaders(httpReq, c.customHeaders)
-
- resp, err := rawHTTPClient.Do(httpReq)
- if err != nil {
- return nil, fmt.Errorf("send request: %w", err)
- }
- if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
- body, _ := io.ReadAll(resp.Body)
- resp.Body.Close()
- return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, string(body))
- }
-
- streamChan := make(chan types.StreamResponse)
- go processAnthropicStream(ctx, c.modelName, resp, streamChan)
- return streamChan, nil
-}
-
-func (c *AnthropicChat) GetModelName() string {
- return c.modelName
-}
-
-func (c *AnthropicChat) GetModelID() string {
- return c.modelID
-}
-
-func (c *AnthropicChat) endpoint() string {
- baseURL := strings.TrimRight(c.baseURL, "/")
- if isAnthropicMessagesEndpoint(baseURL) {
- return baseURL
- }
- if isAnthropicVersionedBaseURL(baseURL) {
- return baseURL + "/messages"
- }
- return baseURL + "/v1/messages"
-}
-
-func isAnthropicMessagesEndpoint(baseURL string) bool {
- u, err := url.Parse(baseURL)
- if err != nil {
- return false
- }
- path := strings.TrimRight(u.Path, "/")
- return strings.HasSuffix(path, "/messages")
-}
-
-func isAnthropicVersionedBaseURL(baseURL string) bool {
- u, err := url.Parse(baseURL)
- if err != nil {
- return false
- }
- path := strings.TrimRight(u.Path, "/")
- return strings.HasSuffix(path, "/v1") || strings.HasSuffix(path, "/v1beta")
-}
-
-func (c *AnthropicChat) buildRequest(_ context.Context, messages []Message, opts *ChatOptions) anthropicRequest {
- req := anthropicRequest{
- Model: c.modelName,
- MaxTokens: 1024,
- Messages: make([]anthropicMessage, 0, len(messages)),
- }
- if opts != nil {
- if budget := opts.CompletionBudget(); budget > 0 {
- req.MaxTokens = budget
- }
- if opts.Temperature > 0 {
- temperature := opts.Temperature
- req.Temperature = &temperature
- }
- if opts.TopP > 0 {
- topP := opts.TopP
- req.TopP = &topP
- }
- }
-
- anthropicToolOptions(&req, opts)
- systemParts, converted := anthropicMessages(messages)
- req.Messages = converted
-
- systemText := strings.Join(systemParts, "\n\n")
- retention := resolveCacheRetention(opts)
- marker := cacheControlFor(retention, "1h")
- if marker == nil {
- req.System = systemText
- return req
- }
- if systemText != "" {
- req.System = []anthropicContentBlock{{
- Type: "text",
- Text: systemText,
- CacheControl: &anthropicCacheControl{Type: marker.Type, TTL: marker.TTL},
- }}
- }
- if len(req.Messages) > 0 {
- last := &req.Messages[len(req.Messages)-1]
- if text, ok := last.Content.(string); ok && text != "" {
- last.Content = []anthropicContentBlock{{
- Type: "text",
- Text: text,
- CacheControl: &anthropicCacheControl{Type: marker.Type, TTL: marker.TTL},
- }}
- }
- }
- return req
-}
-
-func textFromMultiContent(parts []MessageContentPart) string {
- if len(parts) == 0 {
- return ""
- }
- textParts := make([]string, 0, len(parts))
- for _, part := range parts {
- if part.Type == "text" && strings.TrimSpace(part.Text) != "" {
- textParts = append(textParts, strings.TrimSpace(part.Text))
- }
- }
- return strings.Join(textParts, "\n")
-}
-
-func (c *AnthropicChat) parseResponse(resp *anthropicResponse) *types.ChatResponse {
- parts := make([]string, 0, len(resp.Content))
- var calls []types.LLMToolCall
- for _, part := range resp.Content {
- if part.Type == "tool_use" {
- calls = append(calls, types.LLMToolCall{
- ID: part.ID, Type: "function",
- Function: types.FunctionCall{Name: part.Name, Arguments: string(part.Input)},
- })
- }
- if part.Type == "text" && part.Text != "" {
- parts = append(parts, part.Text)
- }
- }
- inputTokens := resp.Usage.InputTokens
- outputTokens := resp.Usage.OutputTokens
- cacheRead := valueOrZero(resp.Usage.CacheReadInputTokens)
- cacheWrite := valueOrZero(resp.Usage.CacheCreationInputTokens)
- promptTokens := inputTokens + cacheRead + cacheWrite
- usage := types.TokenUsage{
- PromptTokens: promptTokens,
- CompletionTokens: outputTokens,
- TotalTokens: promptTokens + outputTokens,
- }
- usage.SetPromptCacheUsage(cacheRead, cacheWrite, max(0, promptTokens-cacheRead),
- resp.Usage.CacheReadInputTokens != nil || resp.Usage.CacheCreationInputTokens != nil)
- return &types.ChatResponse{
- Content: strings.Join(parts, ""),
- FinishReason: anthropicToolStream{}.finishReason(resp.StopReason),
- ToolCalls: calls,
- Usage: usage,
- }
-}
-
-func parseAnthropicSSE(reader io.Reader) (*types.ChatResponse, error) {
- sseReader := NewSSEReader(reader)
- var contentParts []string
- toolStream := anthropicToolStream{}
- var finishReason string
- var inputTokens int
- var outputTokens int
- var cacheReadTokens int
- var cacheWriteTokens int
- var cacheReported bool
-
- for {
- event, err := sseReader.ReadEvent()
- if err == io.EOF {
- break
- }
- if err != nil {
- return nil, fmt.Errorf("read SSE response: %w", err)
- }
- if event.Done {
- break
- }
- if len(event.Data) == 0 {
- continue
- }
-
- var streamEvent anthropicStreamEvent
- if err := json.Unmarshal(event.Data, &streamEvent); err != nil {
- return nil, fmt.Errorf("decode SSE response: %w", err)
- }
- if streamEvent.Error != nil && streamEvent.Error.Message != "" {
- return nil, fmt.Errorf("API stream error: %s", streamEvent.Error.Message)
- }
- toolStream.consume(streamEvent)
- if streamEvent.Message != nil {
- inputTokens = max(inputTokens, streamEvent.Message.Usage.InputTokens)
- outputTokens = max(outputTokens, streamEvent.Message.Usage.OutputTokens)
- cacheReadTokens, cacheWriteTokens, cacheReported = mergeAnthropicCacheCounters(
- cacheReadTokens, cacheWriteTokens, cacheReported,
- streamEvent.Message.Usage.CacheReadInputTokens,
- streamEvent.Message.Usage.CacheCreationInputTokens,
- )
- }
- if streamEvent.Delta != nil {
- if streamEvent.Delta.Type == "text_delta" && streamEvent.Delta.Text != "" {
- contentParts = append(contentParts, streamEvent.Delta.Text)
- }
- if streamEvent.Delta.StopReason != "" {
- finishReason = streamEvent.Delta.StopReason
- }
- }
- if streamEvent.Usage != nil {
- inputTokens = max(inputTokens, streamEvent.Usage.InputTokens)
- outputTokens = max(outputTokens, streamEvent.Usage.OutputTokens)
- cacheReadTokens, cacheWriteTokens, cacheReported = mergeAnthropicCacheCounters(
- cacheReadTokens, cacheWriteTokens, cacheReported,
- streamEvent.Usage.CacheReadInputTokens,
- streamEvent.Usage.CacheCreationInputTokens,
- )
- }
- }
- promptTokens := inputTokens + cacheReadTokens + cacheWriteTokens
- usage := types.TokenUsage{
- PromptTokens: promptTokens,
- CompletionTokens: outputTokens,
- TotalTokens: promptTokens + outputTokens,
- }
- usage.SetPromptCacheUsage(cacheReadTokens, cacheWriteTokens,
- max(0, promptTokens-cacheReadTokens), cacheReported)
-
- return &types.ChatResponse{
- Content: strings.Join(contentParts, ""),
- FinishReason: toolStream.finishReason(finishReason),
- ToolCalls: toolStream.calls(),
- Usage: usage,
- }, nil
-}
-
-func processAnthropicStream(ctx context.Context, model string, resp *http.Response, streamChan chan types.StreamResponse) {
- defer close(streamChan)
- defer resp.Body.Close()
- sseReader := NewSSEReader(resp.Body)
- var usage *types.TokenUsage
- var finishReason string
- toolStream := anthropicToolStream{}
- emit := func(chunk types.StreamResponse) bool {
- select {
- case streamChan <- chunk:
- return true
- case <-ctx.Done():
- return false
- }
- }
- finish := func(err error) {
- chunk := types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer, Done: true, Usage: usage,
- ToolCalls: toolStream.calls(), FinishReason: toolStream.finishReason(finishReason),
- }
- if err != nil {
- chunk.ResponseType, chunk.Content = types.ResponseTypeError, err.Error()
- chunk.FinishReason = types.FinishReasonIncomplete
- }
- logUsage(ctx, model, usage)
- emit(chunk)
- }
- for {
- event, err := sseReader.ReadEvent()
- if err != nil {
- if err == io.EOF {
- finish(nil)
- } else {
- finish(err)
- }
- return
- }
- if event.Done {
- finish(nil)
- return
- }
- if len(event.Data) == 0 {
- continue
- }
- var streamEvent anthropicStreamEvent
- if err := json.Unmarshal(event.Data, &streamEvent); err != nil {
- finish(fmt.Errorf("decode SSE response: %w", err))
- return
- }
- if streamEvent.Error != nil && streamEvent.Error.Message != "" {
- finish(fmt.Errorf("API stream error: %s", streamEvent.Error.Message))
- return
- }
- toolStream.consume(streamEvent)
- if streamEvent.Type == "content_block_start" && streamEvent.ContentBlock != nil &&
- streamEvent.ContentBlock.Type == "tool_use" {
- block := streamEvent.ContentBlock
- if !emit(types.StreamResponse{
- ResponseType: types.ResponseTypeToolCall,
- Data: map[string]interface{}{"tool_call_id": block.ID, "tool_name": block.Name},
- }) {
- return
- }
- }
- if streamEvent.Message != nil {
- usage = mergeAnthropicUsage(usage, streamEvent.Message.Usage.InputTokens,
- streamEvent.Message.Usage.OutputTokens, streamEvent.Message.Usage.CacheReadInputTokens,
- streamEvent.Message.Usage.CacheCreationInputTokens)
- }
- if streamEvent.Delta != nil {
- if streamEvent.Delta.StopReason != "" {
- finishReason = streamEvent.Delta.StopReason
- }
- if streamEvent.Delta.Type == "text_delta" && streamEvent.Delta.Text != "" {
- if !emit(types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer, Content: streamEvent.Delta.Text,
- }) {
- return
- }
- }
- }
- if streamEvent.Usage != nil {
- usage = mergeAnthropicUsage(usage, streamEvent.Usage.InputTokens,
- streamEvent.Usage.OutputTokens, streamEvent.Usage.CacheReadInputTokens,
- streamEvent.Usage.CacheCreationInputTokens)
- }
- if streamEvent.Type == "message_stop" {
- finish(nil)
- return
- }
- }
-}
-
-func mergeAnthropicUsage(
- current *types.TokenUsage,
- inputTokens, outputTokens int,
- cacheRead, cacheWrite *int,
-) *types.TokenUsage {
- if current == nil {
- current = &types.TokenUsage{}
- }
- read, write, reported := mergeAnthropicCacheCounters(
- current.CacheReadTokens, current.CacheWriteTokens, current.CacheReported,
- cacheRead, cacheWrite,
- )
- uncachedInput := max(0, current.PromptTokens-current.CacheReadTokens-current.CacheWriteTokens)
- uncachedInput = max(uncachedInput, inputTokens)
- current.PromptTokens = uncachedInput + read + write
- current.CompletionTokens = max(current.CompletionTokens, outputTokens)
- current.TotalTokens = current.PromptTokens + current.CompletionTokens
- current.SetPromptCacheUsage(read, write, max(0, current.PromptTokens-read), reported)
- return current
-}
-
-func mergeAnthropicCacheCounters(
- currentRead, currentWrite int,
- currentReported bool,
- cacheRead, cacheWrite *int,
-) (read, write int, reported bool) {
- read = currentRead
- write = currentWrite
- reported = currentReported || cacheRead != nil || cacheWrite != nil
- if cacheRead != nil {
- read = max(read, *cacheRead)
- }
- if cacheWrite != nil {
- write = max(write, *cacheWrite)
- }
- return read, write, reported
-}
diff --git a/internal/models/chat/anthropic_test.go b/internal/models/chat/anthropic_test.go
deleted file mode 100644
index 5cb46a62c..000000000
--- a/internal/models/chat/anthropic_test.go
+++ /dev/null
@@ -1,331 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "net/http"
- "net/http/httptest"
- "testing"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-func TestAnthropicChat(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
-
- var capturedHeaders http.Header
- var capturedRequest anthropicRequest
-
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- assert.Equal(t, "/v1/messages", r.URL.Path)
- capturedHeaders = r.Header.Clone()
- require.NoError(t, json.NewDecoder(r.Body).Decode(&capturedRequest))
-
- w.Header().Set("Content-Type", "application/json")
- _, _ = w.Write([]byte(`{
- "id":"msg_123",
- "type":"message",
- "role":"assistant",
- "content":[{"type":"text","text":"hello"}],
- "stop_reason":"end_turn",
- "usage":{"input_tokens":3,"output_tokens":2}
- }`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: server.URL,
- ModelName: "claude-sonnet-4-5",
- APIKey: "test-key",
- Provider: string(provider.ProviderAnthropic),
- CustomHeaders: map[string]string{
- "anthropic-beta": "test-beta",
- },
- })
- require.NoError(t, err)
-
- resp, err := chat.Chat(context.Background(), []Message{
- {Role: "system", Content: "You are helpful."},
- {Role: "user", Content: "Hi"},
- }, &ChatOptions{MaxTokens: 7, Temperature: 0.2})
- require.NoError(t, err)
-
- assert.Equal(t, "test-key", capturedHeaders.Get("x-api-key"))
- assert.Equal(t, anthropicVersion, capturedHeaders.Get("anthropic-version"))
- assert.Equal(t, "test-beta", capturedHeaders.Get("anthropic-beta"))
- assert.Equal(t, "claude-sonnet-4-5", capturedRequest.Model)
- assert.Equal(t, 7, capturedRequest.MaxTokens)
- systemText, systemCache := firstTextAndCache(t, capturedRequest.System)
- assert.Equal(t, "You are helpful.", systemText)
- require.Equal(t, "ephemeral", systemCache["type"])
- require.Len(t, capturedRequest.Messages, 1)
- assert.Equal(t, "user", capturedRequest.Messages[0].Role)
- userText, userCache := firstTextAndCache(t, capturedRequest.Messages[0].Content)
- assert.Equal(t, "Hi", userText)
- require.Equal(t, "ephemeral", userCache["type"])
- assert.Equal(t, "hello", resp.Content)
- assert.Equal(t, "end_turn", resp.FinishReason)
- assert.Equal(t, 3, resp.Usage.PromptTokens)
- assert.Equal(t, 2, resp.Usage.CompletionTokens)
- assert.Equal(t, 5, resp.Usage.TotalTokens)
-}
-
-func TestAnthropicChat_CacheUsage(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- w.Header().Set("Content-Type", "application/json")
- _, _ = w.Write([]byte(`{
- "id":"msg_cached","type":"message","role":"assistant",
- "content":[{"type":"text","text":"hello"}],"stop_reason":"end_turn",
- "usage":{"input_tokens":24,"output_tokens":2,"cache_creation_input_tokens":100,"cache_read_input_tokens":900}
- }`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote, BaseURL: server.URL, ModelName: "claude-sonnet-4-5",
- APIKey: "test-key", Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
- resp, err := chat.Chat(context.Background(), []Message{{Role: "user", Content: "Hi"}}, nil)
- require.NoError(t, err)
- assert.Equal(t, 1024, resp.Usage.PromptTokens)
- assert.Equal(t, 900, resp.Usage.CacheReadTokens)
- assert.Equal(t, 100, resp.Usage.CacheWriteTokens)
- assert.Equal(t, 124, resp.Usage.CacheMissTokens)
- assert.True(t, resp.Usage.CacheReported)
- assert.Equal(t, types.PromptCacheStatusHit, resp.Usage.CacheStatus)
-}
-
-func TestAnthropicChat_FullEndpoint(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
-
- var capturedPath string
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- capturedPath = r.URL.Path
- w.Header().Set("Content-Type", "application/json")
- _, _ = w.Write([]byte(`{
- "id":"msg_123",
- "type":"message",
- "role":"assistant",
- "content":[{"type":"text","text":"hello"}],
- "stop_reason":"end_turn",
- "usage":{"input_tokens":3,"output_tokens":2}
- }`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: server.URL + "/api/proxy/forward",
- ModelName: "gpt-5.5",
- APIKey: "test-key",
- Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
-
- resp, err := chat.Chat(context.Background(), []Message{{Role: "user", Content: "Hi"}}, nil)
- require.NoError(t, err)
-
- assert.Equal(t, "/api/proxy/forward/v1/messages", capturedPath)
- assert.Equal(t, "hello", resp.Content)
-}
-
-func TestAnthropicChat_MessagesEndpoint(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
-
- var capturedPath string
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- capturedPath = r.URL.Path
- w.Header().Set("Content-Type", "application/json")
- _, _ = w.Write([]byte(`{
- "id":"msg_123",
- "type":"message",
- "role":"assistant",
- "content":[{"type":"text","text":"hello"}],
- "stop_reason":"end_turn",
- "usage":{"input_tokens":3,"output_tokens":2}
- }`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: server.URL + "/api/v1/messages",
- ModelName: "gpt-5.5",
- APIKey: "test-key",
- Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
-
- resp, err := chat.Chat(context.Background(), []Message{{Role: "user", Content: "Hi"}}, nil)
- require.NoError(t, err)
-
- assert.Equal(t, "/api/v1/messages", capturedPath)
- assert.Equal(t, "hello", resp.Content)
-}
-
-func TestAnthropicChat_SSEResponse(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
-
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- assert.Equal(t, "/v1/messages", r.URL.Path)
- w.Header().Set("Content-Type", "text/event-stream")
- _, _ = w.Write([]byte(`event: message_start
-data: {"type":"message_start","message":{"usage":{"input_tokens":14,"output_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":100}}}
-
-event: content_block_delta
-data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"pong"}}
-
-event: message_delta
-data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":5}}
-
-event: message_stop
-data: {"type":"message_stop"}
-
-`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: server.URL,
- ModelName: "gpt-5.5",
- APIKey: "test-key",
- Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
-
- resp, err := chat.Chat(context.Background(), []Message{{Role: "user", Content: "ping"}}, nil)
- require.NoError(t, err)
-
- assert.Equal(t, "pong", resp.Content)
- assert.Equal(t, "end_turn", resp.FinishReason)
- assert.Equal(t, 114, resp.Usage.PromptTokens)
- assert.Equal(t, 5, resp.Usage.CompletionTokens)
- assert.Equal(t, 119, resp.Usage.TotalTokens)
- assert.Equal(t, 100, resp.Usage.CacheReadTokens)
- assert.Equal(t, 14, resp.Usage.CacheMissTokens)
-}
-
-func TestAnthropicChat_ChatStream(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
-
- var capturedRequest anthropicRequest
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- assert.Equal(t, "/v1/messages", r.URL.Path)
- assert.Equal(t, "text/event-stream", r.Header.Get("Accept"))
- require.NoError(t, json.NewDecoder(r.Body).Decode(&capturedRequest))
- w.Header().Set("Content-Type", "text/event-stream")
- _, _ = w.Write([]byte(`event: message_start
-data: {"type":"message_start","message":{"usage":{"input_tokens":14,"output_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":100}}}
-
-event: content_block_delta
-data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"pong"}}
-
-event: message_delta
-data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":5}}
-
-event: message_stop
-data: {"type":"message_stop"}
-
-`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: server.URL,
- ModelName: "gpt-5.5",
- APIKey: "test-key",
- Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
-
- ch, err := chat.ChatStream(context.Background(), []Message{{Role: "user", Content: "ping"}}, nil)
- require.NoError(t, err)
-
- var chunks []types.StreamResponse
- for chunk := range ch {
- chunks = append(chunks, chunk)
- }
-
- require.Len(t, chunks, 2)
- assert.True(t, capturedRequest.Stream)
- assert.Equal(t, "pong", chunks[0].Content)
- assert.False(t, chunks[0].Done)
- assert.True(t, chunks[1].Done)
- assert.Equal(t, "end_turn", chunks[1].FinishReason)
- require.NotNil(t, chunks[1].Usage)
- assert.Equal(t, 114, chunks[1].Usage.PromptTokens)
- assert.Equal(t, 5, chunks[1].Usage.CompletionTokens)
- assert.Equal(t, 119, chunks[1].Usage.TotalTokens)
- assert.Equal(t, 100, chunks[1].Usage.CacheReadTokens)
- assert.Equal(t, 14, chunks[1].Usage.CacheMissTokens)
-}
-
-func TestNewRemoteChat_AnthropicProvider(t *testing.T) {
- chat, err := NewRemoteChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- ModelName: "claude-sonnet-4-5",
- APIKey: "test-key",
- Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
- _, ok := chat.(*AnthropicChat)
- assert.True(t, ok)
-}
-
-func TestAnthropicChat_CacheRetentionNoneKeepsPlainStrings(t *testing.T) {
- t.Setenv("SSRF_WHITELIST", "127.0.0.1")
- var capturedRequest anthropicRequest
- server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- require.NoError(t, json.NewDecoder(r.Body).Decode(&capturedRequest))
- w.Header().Set("Content-Type", "application/json")
- _, _ = w.Write([]byte(`{
- "id":"msg_123","type":"message","role":"assistant",
- "content":[{"type":"text","text":"hello"}],"stop_reason":"end_turn",
- "usage":{"input_tokens":3,"output_tokens":2}
- }`))
- }))
- defer server.Close()
-
- chat, err := NewAnthropicChat(&ChatConfig{
- Source: types.ModelSourceRemote, BaseURL: server.URL, ModelName: "claude-sonnet-4-5",
- APIKey: "test-key", Provider: string(provider.ProviderAnthropic),
- })
- require.NoError(t, err)
-
- _, err = chat.Chat(context.Background(), []Message{
- {Role: "system", Content: "You are helpful."},
- {Role: "user", Content: "Hi"},
- }, &ChatOptions{CacheRetention: CacheRetentionNone})
- require.NoError(t, err)
-
- assert.Equal(t, "You are helpful.", capturedRequest.System)
- assert.Equal(t, "Hi", capturedRequest.Messages[0].Content)
-}
-
-func firstTextAndCache(t *testing.T, v any) (string, map[string]any) {
- t.Helper()
- switch x := v.(type) {
- case string:
- t.Fatalf("expected cache_control content blocks, got plain string %q", x)
- return "", nil
- case []any:
- require.NotEmpty(t, x)
- block, ok := x[0].(map[string]any)
- require.True(t, ok)
- text, _ := block["text"].(string)
- cache, _ := block["cache_control"].(map[string]any)
- require.NotNil(t, cache)
- return text, cache
- default:
- t.Fatalf("unexpected content type %T", v)
- return "", nil
- }
-}
diff --git a/internal/models/chat/anthropic_tools.go b/internal/models/chat/anthropic_tools.go
deleted file mode 100644
index 3b00b9ca0..000000000
--- a/internal/models/chat/anthropic_tools.go
+++ /dev/null
@@ -1,185 +0,0 @@
-package chat
-
-import (
- "encoding/json"
- "sort"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-type anthropicTool struct {
- Name string `json:"name"`
- Description string `json:"description"`
- InputSchema json.RawMessage `json:"input_schema"`
-}
-
-type anthropicToolChoice struct {
- Type string `json:"type"`
- Name string `json:"name,omitempty"`
- DisableParallelToolUse *bool `json:"disable_parallel_tool_use,omitempty"`
-}
-
-func anthropicToolOptions(req *anthropicRequest, opts *ChatOptions) {
- if opts == nil || len(opts.Tools) == 0 {
- return
- }
- for _, tool := range opts.Tools {
- req.Tools = append(
- req.Tools,
- anthropicTool{
- Name: tool.Function.Name,
- Description: tool.Function.Description,
- InputSchema: tool.Function.Parameters,
- },
- )
- }
- choice := &anthropicToolChoice{Type: "auto"}
- switch opts.ToolChoice {
- case "", "auto":
- case "required":
- choice.Type = "any"
- case "none":
- choice.Type = "none"
- default:
- choice.Type, choice.Name = "tool", opts.ToolChoice
- }
- if opts.ParallelToolCalls != nil && choice.Type != "none" {
- disable := !*opts.ParallelToolCalls
- choice.DisableParallelToolUse = &disable
- }
- req.ToolChoice = choice
-}
-
-// Tool calls are assistant content blocks; all parallel results belong in the
-// immediately following user message. Keep IDs, JSON and empty tool results.
-func anthropicMessages(messages []Message) ([]string, []anthropicMessage) {
- var system []string
- var result []anthropicMessage
- for _, msg := range messages {
- msg = neutralizeMessageSpecialTokens(msg)
- content := strings.TrimSpace(msg.Content)
- if content == "" {
- content = textFromMultiContent(msg.MultiContent)
- }
- switch {
- case msg.Role == "system":
- if content != "" {
- system = append(system, content)
- }
- case msg.Role == "assistant" && len(msg.ToolCalls) > 0:
- var blocks []anthropicContentBlock
- if content != "" {
- blocks = append(blocks, anthropicContentBlock{Type: "text", Text: content})
- }
- for _, call := range msg.ToolCalls {
- input := json.RawMessage(call.Function.Arguments)
- if len(input) == 0 {
- input = json.RawMessage(`{}`)
- }
- blocks = append(
- blocks,
- anthropicContentBlock{Type: "tool_use", ID: call.ID, Name: call.Function.Name, Input: input},
- )
- }
- result = append(result, anthropicMessage{Role: "assistant", Content: blocks})
- case msg.Role == "tool":
- block := anthropicContentBlock{Type: "tool_result", ToolUseID: msg.ToolCallID, Content: msg.Content}
- if len(result) > 0 && result[len(result)-1].Role == "user" {
- if blocks, ok := result[len(result)-1].Content.([]anthropicContentBlock); ok && len(blocks) > 0 &&
- blocks[0].Type == "tool_result" {
- result[len(result)-1].Content = append(blocks, block)
- continue
- }
- }
- result = append(result, anthropicMessage{Role: "user", Content: []anthropicContentBlock{block}})
- default:
- if content == "" {
- continue
- }
- role := "user"
- if msg.Role == "assistant" {
- role = "assistant"
- }
- result = append(result, anthropicMessage{Role: role, Content: content})
- }
- }
- return system, result
-}
-
-type anthropicToolInput struct {
- call types.LLMToolCall
- initial string
- json strings.Builder
- closed bool
-}
-
-type anthropicToolStream map[int]*anthropicToolInput
-
-func (s anthropicToolStream) consume(event anthropicStreamEvent) {
- switch event.Type {
- case "content_block_start":
- if block := event.ContentBlock; block != nil && block.Type == "tool_use" {
- initial := string(block.Input)
- if initial == "" {
- initial = "{}"
- }
- s[event.Index] = &anthropicToolInput{
- initial: initial,
- call: types.LLMToolCall{
- ID: block.ID,
- Type: "function",
- Function: types.FunctionCall{Name: block.Name},
- },
- }
- }
- case "content_block_delta":
- if tool := s[event.Index]; tool != nil && event.Delta != nil && event.Delta.Type == "input_json_delta" {
- tool.json.WriteString(event.Delta.PartialJSON)
- }
- case "content_block_stop":
- if tool := s[event.Index]; tool != nil {
- tool.closed = true
- }
- }
-}
-
-func (s anthropicToolStream) calls() []types.LLMToolCall {
- indexes := make([]int, 0, len(s))
- for index := range s {
- indexes = append(indexes, index)
- }
- sort.Ints(indexes)
- var calls []types.LLMToolCall
- for _, index := range indexes {
- tool := s[index]
- if !tool.closed {
- // A cut-off stream often starts the next tool_use with {}. Executing
- // that empty object is worse than omitting it: the model never
- // asked to run an incomplete call.
- continue
- }
- call := tool.call
- call.Function.Arguments = tool.initial
- if tool.json.Len() > 0 {
- call.Function.Arguments = tool.json.String()
- }
- calls = append(calls, call)
- }
- return calls
-}
-
-func (s anthropicToolStream) finishReason(reason string) string {
- if reason == "max_tokens" {
- return "length"
- }
- if reason == "" {
- return types.FinishReasonIncomplete
- }
- for _, tool := range s {
- if !tool.closed {
- return types.FinishReasonIncomplete
- }
- }
- return reason
-}
diff --git a/internal/models/chat/anthropic_tools_test.go b/internal/models/chat/anthropic_tools_test.go
deleted file mode 100644
index 8484df1dc..000000000
--- a/internal/models/chat/anthropic_tools_test.go
+++ /dev/null
@@ -1,137 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "io"
- "net/http"
- "strings"
- "testing"
-
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/stretchr/testify/require"
-)
-
-func TestAnthropicToolsPreserveParallelHistoryAndSchema(t *testing.T) {
- schema := json.RawMessage(
- `{"type":"object","$defs":{"id":{"type":"string"}},` +
- `"properties":{"id":{"$ref":"#/$defs/id"}},` +
- `"oneOf":[{"required":["id"]}],"additionalProperties":false}`,
- )
- parallel := false
- opts := &ChatOptions{
- Tools: []Tool{
- {
- Type: "function",
- Function: FunctionDef{
- Name: "lookup",
- Description: strings.Repeat("Detailed usage ", 40),
- Parameters: schema,
- },
- },
- },
- ToolChoice: "required",
- ParallelToolCalls: &parallel,
- }
- model := &AnthropicChat{modelName: "claude-test"}
- req := model.buildRequest(context.Background(), []Message{
- {Role: "user", Content: "find both"},
- {Role: "assistant", ToolCalls: []ToolCall{
- {ID: "a", Function: FunctionCall{Name: "lookup", Arguments: `{"id":"i1"}`}},
- {ID: "b", Function: FunctionCall{Name: "lookup", Arguments: `{"id":"i2"}`}},
- }},
- {Role: "tool", ToolCallID: "a", Content: " keep whitespace "},
- {Role: "tool", ToolCallID: "b", Content: ""},
- }, opts)
- require.Len(t, req.Tools, 1)
- require.Equal(t, opts.Tools[0].Function.Description, req.Tools[0].Description)
- require.JSONEq(t, string(schema), string(req.Tools[0].InputSchema))
- require.Equal(t, "any", req.ToolChoice.Type)
- require.True(t, *req.ToolChoice.DisableParallelToolUse)
- require.Len(t, req.Messages, 3)
- assistant := req.Messages[1].Content.([]anthropicContentBlock)
- require.Len(t, assistant, 2)
- require.Equal(t, "tool_use", assistant[0].Type)
- require.Equal(t, "a", assistant[0].ID)
- results := req.Messages[2].Content.([]anthropicContentBlock)
- require.Equal(t, "user", req.Messages[2].Role)
- require.Len(t, results, 2)
- require.Equal(t, " keep whitespace ", results[0].Content)
- require.Equal(t, "b", results[1].ToolUseID)
- raw, err := json.Marshal(req)
- require.NoError(t, err)
- require.Contains(t, string(raw), `"tool_use_id":"b","content":""`)
-}
-
-func TestAnthropicToolStreamParallelFragmentsAndIncompleteCalls(t *testing.T) {
- prefix := "data: {\"type\":\"content_block_start\",\"index\":1," +
- "\"content_block\":{\"type\":\"tool_use\",\"id\":\"a\",\"name\":\"lookup\"," +
- "\"input\":{}}}\n\ndata: {\"type\":\"content_block_delta\",\"index\":1," +
- "\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"id\\\":\"}}\n\ndata: " +
- "{\"type\":\"content_block_delta\",\"index\":1," +
- "\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\\\"42\\\"}\"}}\n\ndata: " +
- "{\"type\":\"content_block_stop\",\"index\":1}\n\ndata: " +
- "{\"type\":\"content_block_start\",\"index\":2," +
- "\"content_block\":{\"type\":\"tool_use\",\"id\":\"b\",\"name\":\"list\"," +
- "\"input\":{}}}\n\n"
- for _, test := range []struct{ name, tail, reason string }{
- {"complete", "data: {\"type\":\"content_block_stop\",\"index\":2}\n\ndata: " +
- "{\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\"}}\n\ndata: " +
- "{\"type\":\"message_stop\"}\n\n", "tool_use"},
- {"cut off", "", types.FinishReasonIncomplete},
- {
- "missing block stop",
- "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\"}}\n\n",
- types.FinishReasonIncomplete,
- },
- {"token limit", "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"max_tokens\"}}\n\n", "length"},
- } {
- t.Run(test.name, func(t *testing.T) {
- body := prefix + test.tail
- parsed, err := parseAnthropicSSE(strings.NewReader(body))
- require.NoError(t, err)
- require.Equal(t, test.reason, parsed.FinishReason)
- require.JSONEq(t, `{"id":"42"}`, parsed.ToolCalls[0].Function.Arguments)
- if test.name == "complete" {
- require.Len(t, parsed.ToolCalls, 2)
- require.Equal(t, "{}", parsed.ToolCalls[1].Function.Arguments)
- } else {
- require.Len(t, parsed.ToolCalls, 1, "unclosed tool_use must not be emitted for execution")
- }
- channel := make(chan types.StreamResponse, 8)
- processAnthropicStream(
- context.Background(),
- "test",
- &http.Response{Body: io.NopCloser(strings.NewReader(body))},
- channel,
- )
- var last types.StreamResponse
- for chunk := range channel {
- last = chunk
- }
- require.True(t, last.Done)
- require.Equal(t, test.reason, last.FinishReason)
- require.Equal(t, parsed.ToolCalls, last.ToolCalls)
- })
- }
-}
-
-func TestAnthropicNonStreamingToolUse(t *testing.T) {
- var response anthropicResponse
- require.NoError(
- t,
- json.Unmarshal(
- []byte(
- `{"content":[{"type":"text","text":"Checking"},{"type":"tool_use",`+
- `"id":"a","name":"lookup","input":{"id":"42"}}],`+
- `"stop_reason":"tool_use"}`,
- ),
- &response,
- ),
- )
- parsed := (&AnthropicChat{}).parseResponse(&response)
- require.Equal(t, "Checking", parsed.Content)
- require.Len(t, parsed.ToolCalls, 1)
- require.Equal(t, "a", parsed.ToolCalls[0].ID)
- require.JSONEq(t, `{"id":"42"}`, parsed.ToolCalls[0].Function.Arguments)
-}
diff --git a/internal/models/chat/chat.go b/internal/models/chat/chat.go
index 55e34048b..386db11f9 100644
--- a/internal/models/chat/chat.go
+++ b/internal/models/chat/chat.go
@@ -1,119 +1,65 @@
+// Package chat exposes the Chat interface used by the application layer and
+// builds the right protocol client for a configured model. Every vendor fact
+// comes from internal/models/catalog; every wire protocol lives under
+// internal/models/api. This package only glues the two together and wraps
+// the client with debug / tracing / concurrency decorators.
package chat
import (
"context"
- "encoding/json"
"fmt"
"strings"
- "github.com/Tencent/WeKnora/internal/models/provider"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/api/anthropicmessages"
+ "github.com/Tencent/WeKnora/internal/models/api/googlegenai"
+ "github.com/Tencent/WeKnora/internal/models/api/openaicompletions"
+ "github.com/Tencent/WeKnora/internal/models/api/openairesponses"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
"github.com/Tencent/WeKnora/internal/models/utils/ollama"
+ // Built-in vendors register with the catalog through package init; the
+ // chat factory is the one place that must never see an empty catalog.
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
"github.com/Tencent/WeKnora/internal/types"
+ secutils "github.com/Tencent/WeKnora/internal/utils"
)
-// Tool represents a function/tool definition
-type Tool struct {
- Type string `json:"type"` // "function"
- Function FunctionDef `json:"function"`
-}
-
-// FunctionDef represents a function definition
-type FunctionDef struct {
- Name string `json:"name"`
- Description string `json:"description"`
- Parameters json.RawMessage `json:"parameters"`
-}
-
-// ChatOptions 聊天选项
-type ChatOptions struct {
- Temperature float64 `json:"temperature"` // 温度参数
- TopP float64 `json:"top_p"` // Top P 参数
- Seed int `json:"seed"` // 随机种子
- // MaxTokens and MaxCompletionTokens are aliases for one completion budget.
- // Callers may set either; CompletionBudget() prefers MaxCompletionTokens.
- // The outbound Chat Completions JSON carries exactly one of max_tokens or
- // max_completion_tokens, chosen per provider (see wireCompletionTokenField).
- MaxTokens int `json:"max_tokens"`
- MaxCompletionTokens int `json:"max_completion_tokens"`
- FrequencyPenalty float64 `json:"frequency_penalty"` // 频率惩罚
- PresencePenalty float64 `json:"presence_penalty"` // 存在惩罚
- Thinking *bool `json:"thinking"` // 是否启用思考
- Tools []Tool `json:"tools,omitempty"` // 可用工具列表
- ToolChoice string `json:"tool_choice,omitempty"` // "auto", "required", "none", or specific tool
- ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty"` // 是否允许并行工具调用(默认 nil 表示由模型决定)
- Format json.RawMessage `json:"format,omitempty"` // 响应格式定义
- // PromptCacheKey is the provider routing key (OpenAI prompt_cache_key).
- // Empty falls back to the session ID on the call context.
- PromptCacheKey string `json:"-"`
- // CacheRetention controls provider prompt-cache TTL. none disables cache
- // markers; empty/short is the default 5-minute cache; long requests 1h/24h
- // where the provider accepts it.
- CacheRetention CacheRetention `json:"-"`
-}
-
-// MessageContentPart represents a part of multi-content message
-type MessageContentPart struct {
- Type string `json:"type"` // "text" or "image_url"
- Text string `json:"text,omitempty"` // For type="text"
- ImageURL *ImageURL `json:"image_url,omitempty"` // For type="image_url"
-}
-
-// ImageURL represents the image URL structure
-type ImageURL struct {
- URL string `json:"url"` // URL or base64 data URI
- Detail string `json:"detail,omitempty"` // "auto", "low", "high"
-}
+// Message and the other aliases below re-export the request model defined
+// in internal/models/api so historical chat.* names keep working.
+//
+//nolint:revive // ChatOptions is the historical name every caller uses.
+type (
+ Message = api.Message
+ MessageContentPart = api.MessageContentPart
+ ImageURL = api.ImageURL
+ MessageKind = api.MessageKind
+ ToolCall = api.ToolCall
+ FunctionCall = api.FunctionCall
+ Tool = api.Tool
+ FunctionDef = api.FunctionDef
+ ChatOptions = api.Options
+ CacheRetention = api.CacheRetention
+ ReasoningEffort = api.ReasoningEffort
+)
-// MessageKind marks messages the engine synthesized rather than received from
-// the user or the model. Compaction needs to tell its own summary apart from a
-// real user turn: a summary that looks like ordinary history gets fed back into
-// the next summarization pass and degrades into a summary of a summary.
-type MessageKind string
-
-// MessageKindCompactionSummary marks the message that replaces compacted
-// history. It carries the `user` role because that is where providers expect
-// conversation history, so the role alone cannot identify it.
-const MessageKindCompactionSummary MessageKind = "compaction_summary"
-
-// Message 表示聊天消息
-type Message struct {
- Role string `json:"role"` // 角色:system, user, assistant, tool
- Content string `json:"content"` // 消息内容
- MultiContent []MessageContentPart `json:"multi_content,omitempty"` // 多内容消息(文本+图片)
- Name string `json:"name,omitempty"` // Function/tool name (for tool role)
- ToolCallID string `json:"tool_call_id,omitempty"` // Tool call ID (for tool role)
- ToolCalls []ToolCall `json:"tool_calls,omitempty"` // Tool calls (for assistant role)
- Images []string `json:"images,omitempty"` // Image URLs for multimodal (only for current user message)
- // ReasoningContent 是 assistant 推理类模型(DeepSeek thinking、小米 MiMo、vLLM reasoning 等)
- // 上一轮输出的思考内容。部分供应商(MiMo、DeepSeek V3.2/V4 thinking 模式)要求多轮对话中
- // 把 assistant 的 reasoning_content 原样回传,否则会以 400 拒绝请求;其他不要求的供应商
- // 会忽略未知字段,无副作用。
- ReasoningContent string `json:"reasoning_content,omitempty"`
- // Kind is engine-internal bookkeeping. `json:"-"` keeps it off the wire:
- // providers reject unknown message fields on some endpoints, and this one
- // means nothing to them anyway.
- Kind MessageKind `json:"-"`
- // TurnID is the stored assistant message whose turn this history message
- // was replayed from. It is empty for the live turn and for messages the
- // engine synthesized. Compaction uses it to tell whether a summary ends
- // exactly on a stored turn, the only kind it can persist for later turns.
- // Engine-internal like Kind, and kept off the wire for the same reason.
- TurnID string `json:"-"`
-}
+// Re-exported constants of the request model.
+const (
+ MessageKindCompactionSummary = api.MessageKindCompactionSummary
+ CacheRetentionNone = api.CacheRetentionNone
+ CacheRetentionShort = api.CacheRetentionShort
+ CacheRetentionLong = api.CacheRetentionLong
+)
-// ToolCall represents a tool call in a message
-type ToolCall struct {
- ID string `json:"id"`
- Type string `json:"type"` // "function"
- Function FunctionCall `json:"function"`
- ProviderMetadata types.ToolCallMetadata `json:"provider_metadata,omitempty"`
-}
+// SanitizeReasoningEffort is re-exported for the callers that build
+// ChatOptions from stored strings (agent config, session SummaryConfig).
+var SanitizeReasoningEffort = api.SanitizeReasoningEffort
-// FunctionCall represents a function call
-type FunctionCall struct {
- Name string `json:"name"`
- Arguments string `json:"arguments"` // JSON string
-}
+// Prompt-cache helpers re-exported for the application layer.
+var (
+ FingerprintPromptPrefix = api.FingerprintPromptPrefix
+ PromptPrefixFingerprint = api.PromptPrefixFingerprint
+ BuildPromptCacheKey = api.BuildPromptCacheKey
+)
// Chat 定义了聊天接口
type Chat interface {
@@ -130,6 +76,7 @@ type Chat interface {
GetModelID() string
}
+// ChatConfig is the operator-facing configuration of one chat model.
type ChatConfig struct {
Source types.ModelSource
BaseURL string
@@ -141,15 +88,17 @@ type ChatConfig struct {
// back to the process-wide default (see limiter.GateN).
MaxConcurrency int
ExtraConfig map[string]string
- // CustomHeaders 允许在调用远程 OpenAI 兼容 API 时附加自定义 HTTP 请求头(类似 OpenAI Python SDK 的 extra_headers)。
+ // CustomHeaders 允许在调用远程 API 时附加自定义 HTTP 请求头(类似 OpenAI Python SDK 的 extra_headers)。
CustomHeaders map[string]string
AppID string
- AppSecret string // 加密值,由工厂函数调用方传入,在 NewWeKnoraCloudChat 中使用前已解密
+ AppSecret string // 加密值,由工厂函数调用方传入,在使用前已解密
+ // Spec carries per-row catalog overrides (protocol, compat, levels).
+ Spec *types.ModelSpecOverride
}
// ConfigFromModel 根据 types.Model 构造 ChatConfig。
// 保证生产路径(service 层根据 DB 中的模型配置拉起实例)和测试路径
-// (handler 层根据前端表单临时拉起实例)走完全相同的字段映射,避免重复样板。
+// (handler 层根据前端表单临时拉起实例)走完全相同的字段映射。
// appID / appSecret 是已经解密/解析好的 WeKnoraCloud 凭证,调用方负责传入。
func ConfigFromModel(m *types.Model, appID, appSecret string) *ChatConfig {
if m == nil {
@@ -167,6 +116,7 @@ func ConfigFromModel(m *types.Model, appID, appSecret string) *ChatConfig {
CustomHeaders: m.Parameters.CustomHeaders,
AppID: appID,
AppSecret: appSecret,
+ Spec: m.Parameters.Spec,
}
}
@@ -189,16 +139,122 @@ func NewChat(config *ChatConfig, ollamaService *ollama.OllamaService) (Chat, err
return wrapChatConcurrency(c, config.MaxConcurrency, err)
}
-// NewRemoteChat 根据 provider 创建远程聊天实例。
-// Anthropic 走独立的 Messages 协议实现;其余 OpenAI 兼容供应商统一由
-// RemoteAPIChat 处理,provider 特定行为在构造时通过 providerAdapter 解析。
+// Resolve looks the configuration up in the catalog. It is exposed so the
+// handler layer can report the effective protocol and capabilities.
+func Resolve(config *ChatConfig) (*catalog.Resolved, error) {
+ if config == nil {
+ return nil, fmt.Errorf("chat config is nil")
+ }
+ return catalog.Resolve(catalog.Ref{
+ Provider: config.Provider,
+ Model: config.ModelName,
+ BaseURL: config.BaseURL,
+ ModelType: types.ModelTypeKnowledgeQA,
+ Extra: config.ExtraConfig,
+ Override: config.Spec,
+ })
+}
+
+// EffectiveThinkingControl reports how the resolved model encodes thinking
+// ("none" when it cannot be asked to think). Kept for the model debug view.
+func EffectiveThinkingControl(config *ChatConfig) string {
+ resolved, err := Resolve(config)
+ if err != nil {
+ return "none"
+ }
+ caps := resolved.Capabilities()
+ if len(caps.ThinkingLevels) == 0 {
+ return "none"
+ }
+ return caps.ThinkingFormat
+}
+
+// NewRemoteChat builds the protocol client for a remote model.
func NewRemoteChat(config *ChatConfig) (Chat, error) {
- providerName := provider.ProviderName(config.Provider)
- if providerName == "" {
- providerName = provider.DetectProvider(config.BaseURL)
+ resolved, err := Resolve(config)
+ if err != nil {
+ return nil, err
+ }
+ vendor := resolved.Vendor
+ if resolved.BaseURL != "" {
+ if err := secutils.ValidateURLForSSRF(resolved.BaseURL); err != nil {
+ return nil, fmt.Errorf("baseURL SSRF check failed: %w", err)
+ }
+ }
+
+ creds := catalog.Credentials{APIKey: config.APIKey, AppID: config.AppID, AppSecret: config.AppSecret}
+ if creds.APIKey == "" {
+ creds.APIKey = vendor.DefaultAPIKey
}
- if providerName == provider.ProviderAnthropic {
- return NewAnthropicChat(config)
+ if vendor.Auth == catalog.AuthSigned {
+ if creds.AppID == "" {
+ return nil, fmt.Errorf("%s provider: AppID is required", vendor.Name)
+ }
+ if creds.AppSecret == "" {
+ return nil, fmt.Errorf("%s provider: AppSecret is required", vendor.Name)
+ }
+ } else if vendor.RequiresAuth && resolved.API == api.APIAnthropicMessages && strings.TrimSpace(creds.APIKey) == "" {
+ return nil, fmt.Errorf("%s provider: API key is required", vendor.Name)
+ }
+
+ headers := make(map[string]string, len(vendor.Headers)+len(config.CustomHeaders))
+ for k, v := range vendor.Headers {
+ headers[k] = v
+ }
+ for k, v := range config.CustomHeaders {
+ headers[k] = v
+ }
+ endpoint := api.Endpoint{
+ BaseURL: resolved.BaseURL,
+ Model: resolved.RemoteModel,
+ ModelID: config.ModelID,
+ Auth: vendor.AuthFunc(resolved.API, creds),
+ Headers: headers,
+ }
+ if vendor.Endpoint != nil {
+ url, query := vendor.Endpoint(catalog.EndpointRequest{
+ BaseURL: resolved.BaseURL,
+ Model: resolved.RemoteModel,
+ ModelType: types.ModelTypeKnowledgeQA,
+ API: resolved.API,
+ Extra: config.ExtraConfig,
+ })
+ if url != "" {
+ endpoint.URL = url
+ endpoint.Query = query
+ }
+ }
+
+ switch resolved.API {
+ case api.APIOpenAICompletions:
+ return openaicompletions.New(openaicompletions.Config{
+ Endpoint: endpoint,
+ Settings: resolved.OpenAICompletions,
+ ThinkingLevels: resolved.ThinkingLevels,
+ Reasoning: resolved.Spec.Reasoning,
+ }), nil
+ case api.APIOpenAIResponses:
+ return openairesponses.New(openairesponses.Config{
+ Endpoint: endpoint,
+ Settings: resolved.OpenAIResponses,
+ ThinkingLevels: resolved.ThinkingLevels,
+ Reasoning: resolved.Spec.Reasoning,
+ }), nil
+ case api.APIAnthropicMessages:
+ return anthropicmessages.New(anthropicmessages.Config{
+ Endpoint: endpoint,
+ Settings: resolved.AnthropicMessages,
+ ThinkingLevels: resolved.ThinkingLevels,
+ Reasoning: resolved.Spec.Reasoning,
+ }), nil
+ case api.APIGoogleGenerativeAI:
+ return googlegenai.New(googlegenai.Config{
+ Endpoint: endpoint,
+ Settings: resolved.GoogleGenerativeAI,
+ ThinkingLevels: resolved.ThinkingLevels,
+ Reasoning: resolved.Spec.Reasoning,
+ }), nil
+ default:
+ return nil, fmt.Errorf("unsupported chat api %q for provider %s", resolved.API, vendor.ID)
}
- return NewRemoteAPIChat(config)
}
diff --git a/internal/models/chat/completion_budget.go b/internal/models/chat/completion_budget.go
deleted file mode 100644
index fe915a75f..000000000
--- a/internal/models/chat/completion_budget.go
+++ /dev/null
@@ -1,72 +0,0 @@
-package chat
-
-import (
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/sashabaranov/go-openai"
-)
-
-// completionTokenField is the single Chat Completions wire name for a
-// completion budget. OpenAI treats max_tokens and max_completion_tokens as
-// mutually exclusive; gateways such as Volcengine Ark reject requests that
-// carry both (Tencent/WeKnora#3014).
-type completionTokenField string
-
-const (
- completionTokenFieldMaxTokens completionTokenField = "max_tokens"
- completionTokenFieldMaxCompletionTokens completionTokenField = "max_completion_tokens"
-)
-
-// CompletionBudget is the single per-call generation cap. MaxTokens and
-// MaxCompletionTokens on ChatOptions are input aliases for the same budget
-// (YAML, older callers, and the agent UI all feed one of them). When both are
-// set, the newer MaxCompletionTokens wins.
-func (o *ChatOptions) CompletionBudget() int {
- if o == nil {
- return 0
- }
- if o.MaxCompletionTokens > 0 {
- return o.MaxCompletionTokens
- }
- return o.MaxTokens
-}
-
-// wireCompletionTokenField picks the Chat Completions JSON key for this
-// provider+model, following the earendil-works/pi compat.maxTokensField
-// pattern: one internal budget, exactly one outbound field.
-//
-// Default is max_completion_tokens (OpenAI Chat Completions, Azure, Ark),
-// matching Pi. Only providers whose docs (or Pi's catalog) use the legacy
-// name stay on max_tokens. WeKnora-only hosts that document max_tokens
-// (LKEAP) are listed here too. Unknown OpenAI-compat hosts — including
-// Aliyun DashScope — keep the default. GPT-5 / o-series always use
-// max_completion_tokens.
-func wireCompletionTokenField(name provider.ProviderName, model string) completionTokenField {
- if provider.IsOpenAIReasoningOrGPT5Model(model) {
- return completionTokenFieldMaxCompletionTokens
- }
- switch name {
- case provider.ProviderDeepSeek, // api-docs.deepseek.com: max_tokens only
- provider.ProviderZhipu, // open.bigmodel.cn: max_tokens only (Pi isZai)
- provider.ProviderSiliconFlow, // docs.siliconflow.com schema: max_tokens
- provider.ProviderMoonshot, // Pi useMaxTokens (moonshot.ai)
- provider.ProviderNvidia, // Pi useMaxTokens (NIM / vLLM)
- provider.ProviderGeneric, // self-hosted vLLM typically ignores the new field
- provider.ProviderGPUStack, // private vLLM-class runtime
- provider.ProviderLKEAP: // cloud.tencent.com/document/product/1772/115969: max_tokens only
- return completionTokenFieldMaxTokens
- default:
- return completionTokenFieldMaxCompletionTokens
- }
-}
-
-func applyCompletionBudget(req *openai.ChatCompletionRequest, budget int, field completionTokenField) {
- if req == nil || budget <= 0 {
- return
- }
- switch field {
- case completionTokenFieldMaxTokens:
- req.MaxTokens = budget
- default:
- req.MaxCompletionTokens = budget
- }
-}
diff --git a/internal/models/chat/completion_budget_test.go b/internal/models/chat/completion_budget_test.go
deleted file mode 100644
index 90d2cc969..000000000
--- a/internal/models/chat/completion_budget_test.go
+++ /dev/null
@@ -1,177 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "testing"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-func TestChatOptionsCompletionBudget(t *testing.T) {
- assert.Zero(t, (*ChatOptions)(nil).CompletionBudget())
- assert.Zero(t, (&ChatOptions{}).CompletionBudget())
- assert.Equal(t, 128, (&ChatOptions{MaxTokens: 128}).CompletionBudget())
- assert.Equal(t, 256, (&ChatOptions{MaxCompletionTokens: 256}).CompletionBudget())
- assert.Equal(t, 256, (&ChatOptions{MaxTokens: 128, MaxCompletionTokens: 256}).CompletionBudget())
-}
-
-func TestWireCompletionTokenField(t *testing.T) {
- // Every AllProviders() name must be classified here so a new vendor cannot
- // silently inherit the default. Match Pi's polarity: default
- // max_completion_tokens; only documented max_tokens hosts (plus WeKnora
- // self-hosted / LKEAP, which Pi does not catalog) are exceptions.
- want := map[provider.ProviderName]completionTokenField{
- provider.ProviderDeepSeek: completionTokenFieldMaxTokens,
- provider.ProviderZhipu: completionTokenFieldMaxTokens,
- provider.ProviderSiliconFlow: completionTokenFieldMaxTokens,
- provider.ProviderMoonshot: completionTokenFieldMaxTokens,
- provider.ProviderNvidia: completionTokenFieldMaxTokens,
- provider.ProviderGeneric: completionTokenFieldMaxTokens,
- provider.ProviderGPUStack: completionTokenFieldMaxTokens,
- provider.ProviderLKEAP: completionTokenFieldMaxTokens,
- provider.ProviderOpenAI: completionTokenFieldMaxCompletionTokens,
- provider.ProviderAzureOpenAI: completionTokenFieldMaxCompletionTokens,
- provider.ProviderVolcengine: completionTokenFieldMaxCompletionTokens,
- provider.ProviderAliyun: completionTokenFieldMaxCompletionTokens,
- provider.ProviderLiteLLM: completionTokenFieldMaxCompletionTokens,
- provider.ProviderGemini: completionTokenFieldMaxCompletionTokens,
- provider.ProviderWeKnoraCloud: completionTokenFieldMaxCompletionTokens,
- provider.ProviderHunyuan: completionTokenFieldMaxCompletionTokens,
- provider.ProviderMiniMax: completionTokenFieldMaxCompletionTokens,
- provider.ProviderOpenRouter: completionTokenFieldMaxCompletionTokens,
- provider.ProviderRequesty: completionTokenFieldMaxCompletionTokens,
- provider.ProviderJina: completionTokenFieldMaxCompletionTokens,
- provider.ProviderMimo: completionTokenFieldMaxCompletionTokens,
- provider.ProviderModelScope: completionTokenFieldMaxCompletionTokens,
- provider.ProviderQianfan: completionTokenFieldMaxCompletionTokens,
- provider.ProviderQiniu: completionTokenFieldMaxCompletionTokens,
- provider.ProviderLongCat: completionTokenFieldMaxCompletionTokens,
- provider.ProviderNovita: completionTokenFieldMaxCompletionTokens,
- provider.ProviderAnthropic: completionTokenFieldMaxCompletionTokens,
- }
- require.Len(t, want, len(provider.AllProviders()), "classify every AllProviders() name")
- for _, name := range provider.AllProviders() {
- field, ok := want[name]
- require.True(t, ok, "classify %s in TestWireCompletionTokenField", name)
- assert.Equal(t, field, wireCompletionTokenField(name, "any"), string(name))
- }
-
- // GPT-5 / o-series always use the modern field, even on a max_tokens provider.
- assert.Equal(t, completionTokenFieldMaxCompletionTokens,
- wireCompletionTokenField(provider.ProviderGeneric, "gpt-5-mini"))
-}
-
-func TestBuildChatCompletionRequest_OneWireTokenField(t *testing.T) {
- messages := []Message{{Role: "user", Content: "hello"}}
-
- t.Run("volcengine both aliases send only max_completion_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderVolcengine), "doubao-seed-2-0-mini", nil)
- req := c.BuildChatCompletionRequest(messages, &ChatOptions{
- MaxTokens: 2048, MaxCompletionTokens: 4096,
- }, false)
- assert.Equal(t, 4096, req.MaxCompletionTokens)
- assert.Zero(t, req.MaxTokens)
-
- body, err := json.Marshal(req)
- require.NoError(t, err)
- assert.Contains(t, string(body), `"max_completion_tokens":4096`)
- assert.NotContains(t, string(body), `"max_tokens"`)
- })
-
- t.Run("deepseek sends max_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderDeepSeek), "deepseek-chat", nil)
- req := c.shapedRequest(messages, &ChatOptions{
- MaxTokens: 2048, MaxCompletionTokens: 4096,
- }, false)
- assert.Equal(t, 4096, req.MaxTokens)
- assert.Zero(t, req.MaxCompletionTokens)
-
- body, err := json.Marshal(req)
- require.NoError(t, err)
- assert.Contains(t, string(body), `"max_tokens":4096`)
- assert.NotContains(t, string(body), "max_completion_tokens")
- })
-
- t.Run("lkeap sends max_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderLKEAP), "deepseek-v3.1", nil)
- req := c.BuildChatCompletionRequest(messages, &ChatOptions{MaxCompletionTokens: 4096}, false)
- assert.Equal(t, 4096, req.MaxTokens)
- assert.Zero(t, req.MaxCompletionTokens)
-
- body, err := json.Marshal(req)
- require.NoError(t, err)
- assert.Contains(t, string(body), `"max_tokens":4096`)
- assert.NotContains(t, string(body), "max_completion_tokens")
- })
-
- t.Run("generic vLLM sends max_tokens from MaxTokens-only callers", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderGeneric), "qwen3", nil)
- req := c.BuildChatCompletionRequest(messages, &ChatOptions{MaxTokens: 2048}, false)
- assert.Equal(t, 2048, req.MaxTokens)
- assert.Zero(t, req.MaxCompletionTokens)
- })
-
- t.Run("aliyun dashscope keeps max_completion_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderAliyun), "qwen-plus", nil)
- req := c.BuildChatCompletionRequest(messages, &ChatOptions{MaxTokens: 2048}, false)
- assert.Zero(t, req.MaxTokens)
- assert.Equal(t, 2048, req.MaxCompletionTokens)
- })
-
- t.Run("openai gpt-4o sends max_completion_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderOpenAI), "gpt-4o", nil)
- req := c.BuildChatCompletionRequest(messages, &ChatOptions{MaxTokens: 128}, false)
- assert.Zero(t, req.MaxTokens)
- assert.Equal(t, 128, req.MaxCompletionTokens)
- })
-}
-
-func TestBuildOutbound_OneWireTokenField(t *testing.T) {
- msgs := []Message{{Role: "user", Content: "hello"}}
-
- t.Run("volcengine thinking keeps only max_completion_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderVolcengine), "doubao-seed-2-0-mini", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{
- MaxTokens: 2048, MaxCompletionTokens: 4096, Thinking: ptrBool(true),
- }, true)
- require.NoError(t, err)
- require.True(t, useRaw)
- js := mustJSON(t, body)
- assert.Contains(t, js, `"thinking"`)
- assert.Contains(t, js, `"max_completion_tokens":4096`)
- assert.NotContains(t, js, `"max_tokens"`)
- })
-
- t.Run("lkeap thinking keeps only max_tokens", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderLKEAP), "deepseek-v3.1", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{
- MaxCompletionTokens: 4096, Thinking: ptrBool(false),
- }, true)
- require.NoError(t, err)
- require.True(t, useRaw)
- js := mustJSON(t, body)
- assert.Contains(t, js, `"thinking"`)
- assert.Contains(t, js, `"max_tokens":4096`)
- assert.NotContains(t, js, "max_completion_tokens")
- })
-}
-
-func TestOllamaBuildChatRequestUsesCompletionBudget(t *testing.T) {
- c := &OllamaChat{modelName: "llama3"}
- req := c.buildChatRequest(
- []Message{{Role: "user", Content: "hi"}},
- &ChatOptions{MaxCompletionTokens: 512},
- false,
- )
- assert.Equal(t, 512, req.Options["num_predict"])
-}
-
-func TestBuildLangfuseModelParamsUsesCompletionBudget(t *testing.T) {
- params := buildLangfuseModelParams(&ChatOptions{MaxTokens: 128, MaxCompletionTokens: 256})
- assert.Equal(t, 256, params["max_completion_tokens"])
- _, hasLegacy := params["max_tokens"]
- assert.False(t, hasLegacy)
-}
diff --git a/internal/models/chat/image_resolve.go b/internal/models/chat/image_resolve.go
deleted file mode 100644
index d0a46db6f..000000000
--- a/internal/models/chat/image_resolve.go
+++ /dev/null
@@ -1,105 +0,0 @@
-package chat
-
-import (
- "encoding/base64"
- "fmt"
- "log"
- "net/http"
- "os"
- "path/filepath"
- "strings"
-)
-
-// resolveImageURLForLLM converts stored image paths to a format that LLM APIs can consume.
-// - data: URIs and http(s):// URLs are returned as-is.
-// - resource:// and provider-backed local paths are read through the
-// application resolver and converted to base64 data URIs.
-func resolveImageURLForLLM(imageURL string) string {
- if strings.HasPrefix(imageURL, "data:") || strings.HasPrefix(imageURL, "http://") || strings.HasPrefix(imageURL, "https://") {
- return imageURL
- }
- if isApplicationStoredImage(imageURL) {
- data := readLocalStorageBytes(imageURL)
- if data != nil {
- mime := http.DetectContentType(data)
- return fmt.Sprintf("data:%s;base64,%s", mime, base64.StdEncoding.EncodeToString(data))
- }
- }
- return imageURL
-}
-
-// resolveImageURLForOllama converts stored image paths to raw bytes for the Ollama API.
-func resolveImageURLForOllama(imageURL string) []byte {
- if strings.HasPrefix(imageURL, "data:") {
- idx := strings.Index(imageURL, ";base64,")
- if idx < 0 {
- return nil
- }
- decoded, err := base64.StdEncoding.DecodeString(imageURL[idx+8:])
- if err != nil {
- return nil
- }
- return decoded
- }
- if isApplicationStoredImage(imageURL) {
- return readLocalStorageBytes(imageURL)
- }
- return nil
-}
-
-func isApplicationStoredImage(imageURL string) bool {
- return strings.HasPrefix(imageURL, "resource://") ||
- strings.HasPrefix(imageURL, "local://") ||
- strings.HasPrefix(imageURL, "storage://")
-}
-
-// LocalImageResolver, when set by the application layer at startup, resolves a
-// resource:// or provider storage URL to bytes using the owning tenant's
-// storage config.
-// Stored local:// URLs are relative to the storage base dir and do NOT encode
-// the tenant's configured PathPrefix, so a plain env-based join would miss the
-// prefix. When nil (e.g. in tests), callers fall back to the env-based
-// LOCAL_STORAGE_BASE_DIR resolution below.
-var LocalImageResolver func(storageURL string) ([]byte, bool)
-
-// readLocalStorageBytes resolves a local:// storage path to disk bytes.
-func readLocalStorageBytes(storagePath string) []byte {
- if LocalImageResolver != nil {
- if data, ok := LocalImageResolver(storagePath); ok {
- return data
- }
- }
- relPath := strings.TrimPrefix(storagePath, "local://")
- baseDir := os.Getenv("LOCAL_STORAGE_BASE_DIR")
- if baseDir == "" {
- baseDir = "/data/files"
- }
- localPath := filepath.Join(baseDir, filepath.FromSlash(relPath))
- data, err := os.ReadFile(localPath)
- if err != nil {
- log.Printf("[image-resolve] failed to read local file %s: %v", localPath, err)
- return nil
- }
- return data
-}
-
-// isMultimodalNotSupportedError checks if an error indicates the model does not
-// support multimodal/image input.
-func isMultimodalNotSupportedError(err error) bool {
- if err == nil {
- return false
- }
- msg := strings.ToLower(err.Error())
- return (strings.Contains(msg, "multimodal") || strings.Contains(msg, "image") || strings.Contains(msg, "vision")) &&
- (strings.Contains(msg, "not support") || strings.Contains(msg, "unsupported") || strings.Contains(msg, "400"))
-}
-
-// stripImagesFromMessages returns a copy of messages with all image data removed.
-func stripImagesFromMessages(messages []Message) []Message {
- cleaned := make([]Message, len(messages))
- for i, msg := range messages {
- cleaned[i] = msg
- cleaned[i].Images = nil
- }
- return cleaned
-}
diff --git a/internal/models/chat/llm_debug.go b/internal/models/chat/llm_debug.go
index df6c12098..1badc6326 100644
--- a/internal/models/chat/llm_debug.go
+++ b/internal/models/chat/llm_debug.go
@@ -6,6 +6,8 @@ import (
"strings"
"time"
+ "github.com/Tencent/WeKnora/internal/models/api"
+
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
)
@@ -29,7 +31,8 @@ func buildLLMMessages(messages []Message) []logger.LLMMessage {
parts = append(parts, mc.Text)
case "image_url":
if mc.ImageURL != nil {
- parts = append(parts, fmt.Sprintf("[image_url: %s]", truncateForDebug(mc.ImageURL.URL, 120)))
+ parts = append(parts,
+ fmt.Sprintf("[image_url: %s]", api.TruncateForDebug(mc.ImageURL.URL, 120)))
}
}
}
@@ -202,11 +205,3 @@ func logLLMDebugStream(ctx context.Context, model string, messages []Message, op
}
logger.LLMDebugLog(ctx, record)
}
-
-func truncateForDebug(s string, maxRunes int) string {
- runes := []rune(s)
- if len(runes) <= maxRunes {
- return s
- }
- return string(runes[:maxRunes]) + fmt.Sprintf("...(%d chars)", len(runes))
-}
diff --git a/internal/models/chat/ollama.go b/internal/models/chat/ollama.go
index b50f93b28..9067aa377 100644
--- a/internal/models/chat/ollama.go
+++ b/internal/models/chat/ollama.go
@@ -9,6 +9,8 @@ import (
"strings"
"time"
+ "github.com/Tencent/WeKnora/internal/models/api"
+
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/utils/ollama"
"github.com/Tencent/WeKnora/internal/types"
@@ -36,7 +38,7 @@ func NewOllamaChat(config *ChatConfig, ollamaService *ollama.OllamaService) (*Ol
func (c *OllamaChat) convertMessages(messages []Message) []ollamaapi.Message {
ollamaMessages := make([]ollamaapi.Message, 0, len(messages))
for _, msg := range messages {
- msg = neutralizeMessageSpecialTokens(msg)
+ msg = api.NeutralizeMessageSpecialTokens(msg)
msgOllama := ollamaapi.Message{
Role: msg.Role,
Content: msg.Content,
@@ -45,8 +47,32 @@ func (c *OllamaChat) convertMessages(messages []Message) []ollamaapi.Message {
if msg.Role == "tool" {
msgOllama.ToolName = msg.Name
}
- if len(msg.Images) > 0 && msg.Role == "user" {
- for _, imgURL := range msg.Images {
+ // The agent builds multimodal turns as MultiContent parts, the shape
+ // every remote protocol prefers, and only the older callers fill
+ // Images. Reading just Images dropped both the text and the pictures
+ // of such a turn: Ollama answered about nothing, without an error.
+ images := msg.Images
+ if len(msg.MultiContent) > 0 {
+ // Copy first: appending to the caller's slice could write into
+ // its spare capacity and leak an image into another message.
+ images = append([]string(nil), msg.Images...)
+ var text strings.Builder
+ for _, part := range msg.MultiContent {
+ switch part.Type {
+ case "text":
+ text.WriteString(part.Text)
+ case "image_url":
+ if part.ImageURL != nil && part.ImageURL.URL != "" {
+ images = append(images, part.ImageURL.URL)
+ }
+ }
+ }
+ if msgOllama.Content == "" {
+ msgOllama.Content = text.String()
+ }
+ }
+ if len(images) > 0 && msg.Role == "user" {
+ for _, imgURL := range images {
if imgData := resolveImageForOllama(imgURL); imgData != nil {
msgOllama.Images = append(msgOllama.Images, imgData)
}
@@ -60,7 +86,7 @@ func (c *OllamaChat) convertMessages(messages []Message) []ollamaapi.Message {
// resolveImageForOllama resolves an image URL into raw bytes for Ollama.
// Handles local serving paths (/files/...), data URIs, and remote HTTP URLs.
func resolveImageForOllama(imageURL string) ollamaapi.ImageData {
- if data := resolveImageURLForOllama(imageURL); data != nil {
+ if data := api.ResolveImageURLForOllama(imageURL); data != nil {
return data
}
if strings.HasPrefix(imageURL, "http://") || strings.HasPrefix(imageURL, "https://") {
@@ -107,10 +133,10 @@ func (c *OllamaChat) buildChatRequest(messages []Message, opts *ChatOptions, isS
if budget := opts.CompletionBudget(); budget > 0 {
chatReq.Options["num_predict"] = budget
}
- if opts.Thinking != nil {
- chatReq.Think = &ollamaapi.ThinkValue{
- Value: *opts.Thinking,
- }
+ if level, requested := opts.Reasoning(); requested {
+ // Ollama accepts a boolean switch; graded levels only exist for a
+ // few models, so they collapse to on/off here.
+ chatReq.Think = &ollamaapi.ThinkValue{Value: level.Enabled()}
}
if len(opts.Format) > 0 {
chatReq.Format = opts.Format
@@ -149,10 +175,12 @@ func (c *OllamaChat) Chat(ctx context.Context, messages []Message, opts *ChatOpt
}
toolCalls = c.toolCallTo(resp.Message.ToolCalls)
- // 获取token计数
+ // 获取token计数。eval_count 本身就是回答的 token 数,不含 prompt
+ // (https://github.com/ollama/ollama/blob/main/docs/api.md),所以不能再
+ // 减去 prompt_eval_count —— 流式分支一直是直接采用的,这里对齐它。
if resp.EvalCount > 0 {
promptTokens = resp.PromptEvalCount
- completionTokens = resp.EvalCount - promptTokens
+ completionTokens = resp.EvalCount
}
return nil
@@ -167,7 +195,7 @@ func (c *OllamaChat) Chat(ctx context.Context, messages []Message, opts *ChatOpt
TotalTokens: promptTokens + completionTokens,
}
usage.MarkPromptCacheUnsupported()
- logUsage(ctx, c.modelName, &usage)
+ api.LogUsage(ctx, c.modelName, &usage)
return &types.ChatResponse{
Content: responseContent,
@@ -200,16 +228,16 @@ func (c *OllamaChat) ChatStream(
go func() {
defer close(streamChan)
- var thinking thinkingEmitter
+ var thinking api.ThinkingEmitter
err := c.ollamaService.Chat(ctx, chatReq, func(resp ollamaapi.ChatResponse) error {
// 发送思考内容(支持 Qwen3、DeepSeek 等推理模型)
if resp.Message.Thinking != "" {
- thinking.emit(streamChan, resp.Message.Thinking)
+ thinking.Emit(streamChan, resp.Message.Thinking)
}
if resp.Message.Content != "" {
// 思考阶段结束后,发送思考完成事件
- thinking.finish(streamChan)
+ thinking.Finish(streamChan)
streamChan <- types.StreamResponse{
ResponseType: types.ResponseTypeAnswer,
Content: resp.Message.Content,
@@ -264,7 +292,7 @@ func (c *OllamaChat) ChatStream(
}
usage.MarkPromptCacheUnsupported()
}
- logUsage(ctx, c.modelName, usage)
+ api.LogUsage(ctx, c.modelName, usage)
streamChan <- types.StreamResponse{
ResponseType: types.ResponseTypeAnswer,
Done: true,
@@ -327,26 +355,6 @@ func (c *OllamaChat) toolFrom(tools []Tool) ollamaapi.Tools {
return ollamaTools
}
-// toolTo 将 Ollama 的 Tool 转换为本模块的 Tool
-func (c *OllamaChat) toolTo(ollamaTools ollamaapi.Tools) []Tool {
- if len(ollamaTools) == 0 {
- return nil
- }
- tools := make([]Tool, 0, len(ollamaTools))
- for _, tool := range ollamaTools {
- paramsBytes, _ := json.Marshal(tool.Function.Parameters)
- tools = append(tools, Tool{
- Type: tool.Type,
- Function: FunctionDef{
- Name: tool.Function.Name,
- Description: tool.Function.Description,
- Parameters: paramsBytes,
- },
- })
- }
- return tools
-}
-
// toolCallFrom 将本模块的 ToolCall 转换为 Ollama 的 ToolCall
func (c *OllamaChat) toolCallFrom(toolCalls []ToolCall) []ollamaapi.ToolCall {
if len(toolCalls) == 0 {
diff --git a/internal/models/chat/ollama_multicontent_test.go b/internal/models/chat/ollama_multicontent_test.go
new file mode 100644
index 000000000..ba17a9e16
--- /dev/null
+++ b/internal/models/chat/ollama_multicontent_test.go
@@ -0,0 +1,54 @@
+package chat
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+)
+
+// The agent composes multimodal turns as MultiContent parts — the shape every
+// remote protocol prefers — while older callers fill Images. Ollama read only
+// the latter, so such a turn reached the model with neither its question nor
+// its picture and came back answering about nothing.
+func TestOllamaConvertMessagesReadsMultiContent(t *testing.T) {
+ c := &OllamaChat{}
+ original := []string{"data:image/png;base64,aGVsbG8="}
+ messages := []Message{
+ {
+ Role: "user",
+ Images: original,
+ MultiContent: []api.MessageContentPart{
+ {Type: "text", Text: "what is this?"},
+ {Type: "image_url", ImageURL: &api.ImageURL{URL: "data:image/png;base64,d29ybGQ="}},
+ },
+ },
+ }
+
+ got := c.convertMessages(messages)
+ if len(got) != 1 {
+ t.Fatalf("expected one message, got %d", len(got))
+ }
+ if got[0].Content != "what is this?" {
+ t.Errorf("text parts should become the content, got %q", got[0].Content)
+ }
+ if len(got[0].Images) != 2 {
+ t.Errorf("both the legacy image and the MultiContent one should survive, got %d", len(got[0].Images))
+ }
+ if len(original) != 1 || original[0] != "data:image/png;base64,aGVsbG8=" {
+ t.Errorf("the caller's slice must not be written through, got %v", original)
+ }
+}
+
+func TestOllamaConvertMessagesKeepsExplicitContent(t *testing.T) {
+ c := &OllamaChat{}
+ got := c.convertMessages([]Message{{
+ Role: "user",
+ Content: "already set",
+ MultiContent: []api.MessageContentPart{
+ {Type: "text", Text: "ignored"},
+ },
+ }})
+ if got[0].Content != "already set" {
+ t.Errorf("an explicit Content wins over the parts, got %q", got[0].Content)
+ }
+}
diff --git a/internal/models/chat/openai_request.go b/internal/models/chat/openai_request.go
deleted file mode 100644
index 0527e6d5d..000000000
--- a/internal/models/chat/openai_request.go
+++ /dev/null
@@ -1,239 +0,0 @@
-package chat
-
-import (
- "encoding/json"
- "fmt"
-
- "github.com/sashabaranov/go-openai"
-)
-
-// ConvertMessages 转换消息格式为 OpenAI 格式(导出供子类使用)
-func (c *RemoteAPIChat) ConvertMessages(messages []Message) []openai.ChatCompletionMessage {
- openaiMessages := make([]openai.ChatCompletionMessage, 0, len(messages))
- for _, msg := range messages {
- msg = neutralizeMessageSpecialTokens(msg)
- openaiMsg := openai.ChatCompletionMessage{
- Role: msg.Role,
- }
-
- // 优先处理多内容消息(包含图片等)
- if len(msg.MultiContent) > 0 {
- openaiMsg.MultiContent = make([]openai.ChatMessagePart, 0, len(msg.MultiContent))
- for _, part := range msg.MultiContent {
- switch part.Type {
- case "text":
- openaiMsg.MultiContent = append(openaiMsg.MultiContent, openai.ChatMessagePart{
- Type: openai.ChatMessagePartTypeText,
- Text: part.Text,
- })
- case "image_url":
- if part.ImageURL != nil {
- openaiMsg.MultiContent = append(openaiMsg.MultiContent, openai.ChatMessagePart{
- Type: openai.ChatMessagePartTypeImageURL,
- ImageURL: &openai.ChatMessageImageURL{
- URL: part.ImageURL.URL,
- Detail: openai.ImageURLDetail(part.ImageURL.Detail),
- },
- })
- }
- }
- }
- } else if len(msg.Images) > 0 && msg.Role == "user" {
- parts := make([]openai.ChatMessagePart, 0, len(msg.Images)+1)
- for _, imgURL := range msg.Images {
- resolved := resolveImageURLForLLM(imgURL)
- parts = append(parts, openai.ChatMessagePart{
- Type: openai.ChatMessagePartTypeImageURL,
- ImageURL: &openai.ChatMessageImageURL{
- URL: resolved,
- Detail: openai.ImageURLDetailAuto,
- },
- })
- }
- parts = append(parts, openai.ChatMessagePart{
- Type: openai.ChatMessagePartTypeText,
- Text: msg.Content,
- })
- openaiMsg.MultiContent = parts
- } else if msg.Content != "" {
- openaiMsg.Content = msg.Content
- }
-
- if len(msg.ToolCalls) > 0 {
- openaiMsg.ToolCalls = make([]openai.ToolCall, 0, len(msg.ToolCalls))
- for _, tc := range msg.ToolCalls {
- toolType := openai.ToolType(tc.Type)
- openaiMsg.ToolCalls = append(openaiMsg.ToolCalls, openai.ToolCall{
- ID: tc.ID,
- Type: toolType,
- Function: openai.FunctionCall{
- Name: tc.Function.Name,
- Arguments: tc.Function.Arguments,
- },
- })
- }
- }
-
- if msg.Role == "tool" {
- openaiMsg.ToolCallID = msg.ToolCallID
- openaiMsg.Name = msg.Name
- }
-
- // Round-trip reasoning_content on assistant turns. MiMo and DeepSeek V3.2+
- // thinking mode reject multi-turn requests where the prior assistant
- // message lacks its reasoning_content with HTTP 400 ("The reasoning_content
- // in the thinking mode must be passed back to the API."). Providers that
- // don't recognize the field ignore it harmlessly.
- if msg.Role == "assistant" && msg.ReasoningContent != "" {
- openaiMsg.ReasoningContent = msg.ReasoningContent
- }
-
- openaiMessages = append(openaiMessages, openaiMsg)
- }
- return openaiMessages
-}
-
-// BuildChatCompletionRequest 构建标准聊天请求参数(导出供子类使用)。
-//
-// 采样参数(temperature / top_p / penalties)按 opts 直接映射。完成预算经
-// CompletionBudget 收成一个值,再按供应商只写入 max_tokens 或
-// max_completion_tokens 之一(二者互斥,见 #3014)。其余供应商特判
-// (o-series / GPT-5 采样参数、Moonshot 固定温度等)仍由
-// providerAdapter.ShapeRequest 在事后施加,见 provider.go。
-func (c *RemoteAPIChat) BuildChatCompletionRequest(
- messages []Message, opts *ChatOptions, isStream bool,
-) openai.ChatCompletionRequest {
- req := openai.ChatCompletionRequest{
- Model: c.modelName,
- Messages: c.ConvertMessages(messages),
- Stream: isStream,
- }
-
- if isStream {
- req.StreamOptions = &openai.StreamOptions{IncludeUsage: true}
- }
-
- if opts == nil {
- return req
- }
-
- req.Temperature = float32(opts.Temperature)
- if opts.TopP > 0 {
- req.TopP = float32(opts.TopP)
- }
- if opts.FrequencyPenalty > 0 {
- req.FrequencyPenalty = float32(opts.FrequencyPenalty)
- }
- if opts.PresencePenalty > 0 {
- req.PresencePenalty = float32(opts.PresencePenalty)
- }
-
- applyCompletionBudget(&req, opts.CompletionBudget(), wireCompletionTokenField(c.provider, c.modelName))
-
- // 处理 Tools
- if len(opts.Tools) > 0 {
- req.Tools = make([]openai.Tool, 0, len(opts.Tools))
- for _, tool := range opts.Tools {
- toolType := openai.ToolType(tool.Type)
- openaiTool := openai.Tool{
- Type: toolType,
- Function: &openai.FunctionDefinition{
- Name: tool.Function.Name,
- Description: tool.Function.Description,
- },
- }
- if tool.Function.Parameters != nil {
- openaiTool.Function.Parameters = tool.Function.Parameters
- }
- req.Tools = append(req.Tools, openaiTool)
- }
- }
-
- // 处理 ParallelToolCalls
- if opts.ParallelToolCalls != nil {
- val := *opts.ParallelToolCalls
- req.ParallelToolCalls = val
- }
-
- // 处理 ToolChoice(标准实现)
- if opts.ToolChoice != "" {
- switch opts.ToolChoice {
- case "none", "required", "auto":
- req.ToolChoice = opts.ToolChoice
- default:
- req.ToolChoice = openai.ToolChoice{
- Type: "function",
- Function: openai.ToolFunction{
- Name: opts.ToolChoice,
- },
- }
- }
- }
-
- if len(opts.Format) > 0 {
- req.ResponseFormat = &openai.ChatCompletionResponseFormat{
- Type: openai.ChatCompletionResponseFormatTypeJSONObject,
- }
- req.Messages[len(req.Messages)-1].Content += fmt.Sprintf("\nUse this JSON schema: %s", opts.Format)
- }
-
- return req
-}
-
-func (c *RemoteAPIChat) buildProviderOpenAIRequest(
- body any,
- openAIMessages []openai.ChatCompletionMessage,
- messages []Message,
-) (map[string]any, error) {
- data, err := json.Marshal(body)
- if err != nil {
- return nil, fmt.Errorf("marshal provider request: %w", err)
- }
-
- var out map[string]any
- if err := json.Unmarshal(data, &out); err != nil {
- return nil, fmt.Errorf("unmarshal provider request: %w", err)
- }
-
- providerMessages := make([]map[string]any, 0, len(openAIMessages))
- for i, msg := range openAIMessages {
- msgData, err := json.Marshal(msg)
- if err != nil {
- return nil, fmt.Errorf("marshal provider message: %w", err)
- }
- var msgMap map[string]any
- if err := json.Unmarshal(msgData, &msgMap); err != nil {
- return nil, fmt.Errorf("unmarshal provider message: %w", err)
- }
-
- if i < len(messages) && len(messages[i].ToolCalls) > 0 && len(msg.ToolCalls) > 0 {
- toolCalls := make([]map[string]any, 0, len(msg.ToolCalls))
- for j, tc := range msg.ToolCalls {
- tcData, err := json.Marshal(tc)
- if err != nil {
- return nil, fmt.Errorf("marshal provider tool call: %w", err)
- }
- var tcMap map[string]any
- if err := json.Unmarshal(tcData, &tcMap); err != nil {
- return nil, fmt.Errorf("unmarshal provider tool call: %w", err)
- }
- if j < len(messages[i].ToolCalls) {
- c.adapter.InjectToolCallMetadata(tcMap, messages[i].ToolCalls[j].ProviderMetadata)
- }
- toolCalls = append(toolCalls, tcMap)
- }
- msgMap["tool_calls"] = toolCalls
- }
-
- providerMessages = append(providerMessages, msgMap)
- }
- out["messages"] = providerMessages
- return out, nil
-}
-
-func (c *RemoteAPIChat) shapeProviderRequest(body any, req openai.ChatCompletionRequest, messages []Message) (any, error) {
- if !c.adapter.ForceRawHTTP() {
- return body, nil
- }
- return c.buildProviderOpenAIRequest(body, req.Messages, messages)
-}
diff --git a/internal/models/chat/openai_stream.go b/internal/models/chat/openai_stream.go
deleted file mode 100644
index 555f52cc3..000000000
--- a/internal/models/chat/openai_stream.go
+++ /dev/null
@@ -1,630 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "fmt"
- "io"
- "net/http"
- "strings"
- "time"
-
- "github.com/Tencent/WeKnora/internal/logger"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/sashabaranov/go-openai"
-)
-
-// parseCompletionResponse 解析非流式响应
-func (c *RemoteAPIChat) parseCompletionResponse(resp *openai.ChatCompletionResponse) (*types.ChatResponse, error) {
- if len(resp.Choices) == 0 {
- return nil, fmt.Errorf("no response from API")
- }
-
- choice := resp.Choices[0]
-
- // 处理思考模型的输出:移除 <think></think> 标签包裹的思考过程
- // 为设置了 Thinking=false 但模型仍返回思考内容的情况和部分不支持Thinking=false的思考模型(例如Miniax-M2.1)提供兜底策略
- content := removeThinkingContent(choice.Message.Content)
-
- usage := tokenUsageFromOpenAI(resp.Usage, c.provider)
- response := &types.ChatResponse{
- Content: content,
- FinishReason: string(choice.FinishReason),
- Usage: usage,
- }
-
- if len(choice.Message.ToolCalls) > 0 {
- response.ToolCalls = make([]types.LLMToolCall, 0, len(choice.Message.ToolCalls))
- for _, tc := range choice.Message.ToolCalls {
- response.ToolCalls = append(response.ToolCalls, types.LLMToolCall{
- ID: tc.ID,
- Type: string(tc.Type),
- Function: types.FunctionCall{
- Name: tc.Function.Name,
- Arguments: tc.Function.Arguments,
- },
- })
- }
- }
-
- return response, nil
-}
-
-func (c *RemoteAPIChat) applyCompletionToolCallMetadata(body []byte, result *types.ChatResponse) {
- if result == nil || len(result.ToolCalls) == 0 {
- return
- }
-
- var raw struct {
- Choices []struct {
- Message struct {
- ToolCalls []json.RawMessage `json:"tool_calls,omitempty"`
- } `json:"message"`
- } `json:"choices"`
- }
- if err := json.Unmarshal(body, &raw); err != nil || len(raw.Choices) == 0 {
- return
- }
-
- for i, rawToolCall := range raw.Choices[0].Message.ToolCalls {
- var indexed struct {
- Index *int `json:"index,omitempty"`
- }
- _ = json.Unmarshal(rawToolCall, &indexed)
- idx := i
- if indexed.Index != nil {
- idx = *indexed.Index
- }
- if idx >= 0 && idx < len(result.ToolCalls) {
- result.ToolCalls[idx].ProviderMetadata = c.adapter.ExtractToolCallMetadata(rawToolCall)
- }
- }
-}
-
-// removeThinkingContent 移除思考模型输出中的 <think></think> 思考过程
-// 仅当内容以 <think> 开头时才处理
-func removeThinkingContent(content string) string {
- const thinkStartTag = "<think>"
- const thinkEndTag = "</think>"
-
- trimmed := strings.TrimSpace(content)
- if !strings.HasPrefix(trimmed, thinkStartTag) {
- return content
- }
-
- // 查找最后一个 </think> 标签(处理嵌套情况)
- if lastEndIdx := strings.LastIndex(trimmed, thinkEndTag); lastEndIdx != -1 {
- if result := strings.TrimSpace(trimmed[lastEndIdx+len(thinkEndTag):]); result != "" {
- return result
- }
- return ""
- }
-
- return "" // 未找到 </think>,可能思考内容过长被截断,返回空字符串
-}
-
-// processStream 处理 OpenAI SDK 流式响应
-func (c *RemoteAPIChat) processStream(
- ctx context.Context,
- stream *openai.ChatCompletionStream,
- streamChan chan types.StreamResponse,
- dumper *streamPacketDumper,
-) {
- defer close(streamChan)
- defer stream.Close()
-
- state := newStreamState()
-
- for {
- response, err := stream.Recv()
- if err != nil {
- if err == io.EOF {
- logUsage(ctx, c.modelName, state.usage)
- toolCalls := state.buildOrderedToolCalls()
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer,
- Content: "",
- Done: true,
- ToolCalls: toolCalls,
- Usage: state.usage,
- FinishReason: state.lastFinishReason,
- }
- } else {
- logger.Errorf(ctx, "Stream read error: %v (tool_calls_assembled=%d)",
- err, len(state.toolCallMap))
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeError,
- Content: err.Error(),
- Done: true,
- ToolCalls: state.buildOrderedToolCalls(),
- Usage: state.usage,
- FinishReason: types.FinishReasonIncomplete,
- }
- }
- return
- }
-
- if dumper != nil {
- dumper.WritePacket(response)
- }
-
- if response.Usage != nil {
- usage := tokenUsageFromOpenAI(*response.Usage, c.provider)
- state.usage = &usage
- }
-
- if len(response.Choices) > 0 {
- c.processStreamDelta(ctx, &response.Choices[0], state, streamChan, response.Choices[0].Delta.ReasoningContent)
- }
- }
-}
-
-// processRawHTTPStream 处理原始 HTTP 流式响应
-func (c *RemoteAPIChat) processRawHTTPStream(
- ctx context.Context,
- resp *http.Response,
- streamChan chan types.StreamResponse,
- dumper *streamPacketDumper,
-) {
- defer close(streamChan)
- defer resp.Body.Close()
-
- state := newStreamState()
- reader := NewSSEReader(resp.Body)
-
- for {
- event, err := reader.ReadEvent()
- if err != nil {
- if err == io.EOF {
- logUsage(ctx, c.modelName, state.usage)
- toolCalls := state.buildOrderedToolCalls()
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer,
- Content: "",
- Done: true,
- ToolCalls: toolCalls,
- Usage: state.usage,
- }
- } else {
- logger.Errorf(ctx, "Stream read error: %v (tool_calls_assembled=%d)",
- err, len(state.toolCallMap))
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeError,
- Content: err.Error(),
- Done: true,
- ToolCalls: state.buildOrderedToolCalls(),
- Usage: state.usage,
- FinishReason: types.FinishReasonIncomplete,
- }
- }
- return
- }
-
- if event == nil {
- continue
- }
-
- if event.Done {
- logUsage(ctx, c.modelName, state.usage)
- toolCalls := state.buildOrderedToolCalls()
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer,
- Content: "",
- Done: true,
- ToolCalls: toolCalls,
- Usage: state.usage,
- }
- return
- }
-
- if event.Data == nil {
- continue
- }
-
- if dumper != nil {
- // 保留上游 SSE data 行的原始 JSON,不经过中间结构体裁剪。
- raw := make([]byte, len(event.Data))
- copy(raw, event.Data)
- dumper.WritePacketRaw(raw)
- }
-
- // 使用局部结构体进行一次性解析,同时捕捉标准字段和 vLLM 的 reasoning 字段,避免性能损失
- var streamResp struct {
- openai.ChatCompletionStreamResponse
- Choices []struct {
- Index int `json:"index"`
- Delta struct {
- openai.ChatCompletionStreamChoiceDelta
- Reasoning string `json:"reasoning,omitempty"`
- } `json:"delta"`
- FinishReason openai.FinishReason `json:"finish_reason"`
- } `json:"choices"`
- }
-
- if err := json.Unmarshal(event.Data, &streamResp); err != nil {
- logger.Errorf(ctx, "Failed to parse stream response: %v", err)
- continue
- }
-
- if streamResp.Usage != nil {
- usage := tokenUsageFromOpenAI(*streamResp.Usage, c.provider)
- applyRawPromptCacheUsage(event.Data, &usage)
- state.usage = &usage
- }
-
- if len(streamResp.Choices) > 0 {
- choice := streamResp.Choices[0]
- // 统一获取逻辑(支持标准和 vLLM 两种路径)
- reasoning := choice.Delta.Reasoning
- if reasoning == "" {
- reasoning = choice.Delta.ReasoningContent
- }
-
- // 构造一个标准 SDK 兼容的 choice 对象传给下游,保证现有逻辑完全不动
- sdkChoice := openai.ChatCompletionStreamChoice{
- Index: choice.Index,
- Delta: choice.Delta.ChatCompletionStreamChoiceDelta,
- FinishReason: choice.FinishReason,
- }
- c.applyStreamToolCallMetadata(event.Data, state)
- c.processStreamDelta(ctx, &sdkChoice, state, streamChan, reasoning)
- }
- }
-}
-
-func (c *RemoteAPIChat) applyStreamToolCallMetadata(data []byte, state *streamState) {
- if state == nil {
- return
- }
-
- var raw struct {
- Choices []struct {
- Delta struct {
- ToolCalls []json.RawMessage `json:"tool_calls,omitempty"`
- } `json:"delta"`
- } `json:"choices"`
- }
- if err := json.Unmarshal(data, &raw); err != nil || len(raw.Choices) == 0 {
- return
- }
-
- for _, rawToolCall := range raw.Choices[0].Delta.ToolCalls {
- metadata := c.adapter.ExtractToolCallMetadata(rawToolCall)
- if len(metadata) == 0 {
- continue
- }
- var indexed struct {
- Index *int `json:"index,omitempty"`
- }
- _ = json.Unmarshal(rawToolCall, &indexed)
- idx := 0
- if indexed.Index != nil {
- idx = *indexed.Index
- }
- state.setToolCallProviderMetadata(idx, metadata)
- }
-}
-
-// streamState 流式处理状态
-type streamState struct {
- thinkingEmitter
- toolCallMap map[int]*types.LLMToolCall
- lastFunctionName map[int]string
- nameNotified map[int]bool
- fieldExtractors map[int]*jsonFieldExtractor // per tool-call-index extractors for streaming field extraction
- fileProgress map[int]*sandboxFileProgress
- usage *types.TokenUsage // captured from the final stream chunk when include_usage is enabled
- lastFinishReason string // last observed finish_reason for EOF handler fallback
-
- // Diagnostic flags (fire-once) used to log earliest signals of tool_call
- // presence/absence at the OpenAI-protocol level. These are independent of
- // the higher-level ResponseTypeToolCall marker (which only fires once
- // function name has stabilized) and let us distinguish between
- // (A) no tool_calls field ever observed (true natural-stop), and
- // (B) tool_calls field observed but marker not yet emitted.
- firstToolCallSeen bool // true once any delta carried tool_calls
- noToolCallStopLogged bool // true once we logged "stop without tool_calls"
- firstContentSeen bool // true once delta.Content first appeared
- firstReasoningSeen bool // true once reasoning_content first appeared
- streamStartedAt time.Time
-}
-
-func newStreamState() *streamState {
- return &streamState{
- toolCallMap: make(map[int]*types.LLMToolCall),
- lastFunctionName: make(map[int]string),
- nameNotified: make(map[int]bool),
- fieldExtractors: make(map[int]*jsonFieldExtractor),
- fileProgress: make(map[int]*sandboxFileProgress),
- streamStartedAt: time.Now(),
- }
-}
-
-// elapsedMs returns the milliseconds elapsed since the stream state was
-// initialized. Used to attach time-since-stream-start to fire-once diagnostic
-// logs so a single grep can reveal the temporal layout of a single stream
-// (TTFC / TTFT / first-tool-call / natural-stop confirmation, etc).
-func (s *streamState) elapsedMs() int64 {
- if s.streamStartedAt.IsZero() {
- return 0
- }
- return time.Since(s.streamStartedAt).Milliseconds()
-}
-
-func (s *streamState) buildOrderedToolCalls() []types.LLMToolCall {
- if len(s.toolCallMap) == 0 {
- return nil
- }
- result := make([]types.LLMToolCall, 0, len(s.toolCallMap))
- for i := 0; i < len(s.toolCallMap); i++ {
- if tc, ok := s.toolCallMap[i]; ok && tc != nil {
- result = append(result, *tc)
- }
- }
- if len(result) == 0 {
- return nil
- }
- return result
-}
-
-func (s *streamState) setToolCallProviderMetadata(index int, metadata types.ToolCallMetadata) {
- if len(metadata) == 0 {
- return
- }
- toolCallEntry, exists := s.toolCallMap[index]
- if !exists || toolCallEntry == nil {
- toolCallEntry = &types.LLMToolCall{
- Type: "function",
- Function: types.FunctionCall{
- Name: "",
- Arguments: "",
- },
- }
- s.toolCallMap[index] = toolCallEntry
- }
- toolCallEntry.ProviderMetadata = metadata
-}
-
-// processStreamDelta 处理流式响应的单个 delta
-func (c *RemoteAPIChat) processStreamDelta(
- ctx context.Context,
- choice *openai.ChatCompletionStreamChoice,
- state *streamState,
- streamChan chan types.StreamResponse,
- reasoningContent string,
-) {
- delta := choice.Delta
- isDone := string(choice.FinishReason) != ""
-
- // Track finish_reason for EOF handler fallback
- if isDone {
- state.lastFinishReason = string(choice.FinishReason)
- }
-
- // 处理 tool calls
- if len(delta.ToolCalls) > 0 {
- c.processToolCallsDelta(ctx, delta.ToolCalls, state, streamChan)
- }
-
- // Earliest reliable "no tool_calls" signal at the OpenAI-protocol level:
- // finish_reason=stop arrived AND we never observed a tool_calls field on
- // any prior delta. Logged once per stream so callers can grep for the
- // natural-stop entry point without waiting for the higher-level summary.
- if isDone &&
- string(choice.FinishReason) == "stop" &&
- !state.firstToolCallSeen &&
- !state.noToolCallStopLogged {
- logger.Infof(ctx, "[LLM Stream] Natural-stop at OpenAI layer "+
- "(finish=stop, tool_calls field never observed, thinking_seen=%t, "+
- "first_content_seen=%t, elapsed_ms=%d)",
- state.active, state.firstContentSeen, state.elapsedMs())
- state.noToolCallStopLogged = true
- }
-
- // 发送思考内容(ReasoningContent,支持 DeepSeek 等模型)
- if reasoningContent != "" {
- // Earliest reasoning_content signal at the OpenAI-protocol level. Fired
- // once per stream so we can distinguish "model emitted thinking before
- // answer" vs "model never produced thinking" when triaging logs.
- if !state.firstReasoningSeen {
- state.firstReasoningSeen = true
- logger.Infof(ctx, "[LLM Stream] First reasoning_content at OpenAI layer "+
- "(len=%d, preview=%q, elapsed_ms=%d)",
- len(reasoningContent), truncateForDebug(reasoningContent, 80), state.elapsedMs())
- }
- state.emit(streamChan, reasoningContent)
- }
-
- // 发送回答内容
- if delta.Content != "" {
- // Earliest delta.Content signal at the OpenAI-protocol level. Fired once
- // per stream so we can measure TTFC (time-to-first-content) and tell
- // "answer started before any tool_call" from "tool_call came first".
- if !state.firstContentSeen {
- state.firstContentSeen = true
- logger.Infof(ctx, "[LLM Stream] First delta.Content at OpenAI layer "+
- "(len=%d, preview=%q, tool_call_seen=%t, thinking_seen=%t, elapsed_ms=%d)",
- len(delta.Content), truncateForDebug(delta.Content, 80),
- state.firstToolCallSeen, state.firstReasoningSeen, state.elapsedMs())
- }
- // If we had thinking content and this is the first answer chunk,
- // send a thinking done event first.
- state.finish(streamChan)
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer,
- Content: delta.Content,
- Done: isDone,
- ToolCalls: state.buildOrderedToolCalls(),
- FinishReason: string(choice.FinishReason),
- }
- }
-
- if isDone && len(state.toolCallMap) > 0 {
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer,
- Content: "",
- Done: true,
- ToolCalls: state.buildOrderedToolCalls(),
- FinishReason: string(choice.FinishReason),
- }
- }
-
- // Ensure thinking done is sent when stream finishes without any answer content
- // (e.g., model only produced reasoning then hit finish_reason with empty content).
- if isDone {
- state.finish(streamChan)
- }
-
- // Catch-all: isDone but none of the above branches sent a response with
- // FinishReason (empty content, no tool calls, no thinking). This prevents
- // the finish_reason from being lost in the streaming pipeline.
- if isDone && delta.Content == "" && len(state.toolCallMap) == 0 {
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeAnswer,
- Done: true,
- FinishReason: string(choice.FinishReason),
- }
- }
-}
-
-// processToolCallsDelta 处理 tool calls 的增量更新
-func (c *RemoteAPIChat) processToolCallsDelta(
- ctx context.Context,
- toolCalls []openai.ToolCall,
- state *streamState,
- streamChan chan types.StreamResponse,
-) {
- // Earliest signal at the OpenAI-protocol level that this stream will
- // produce at least one tool call. Fires *before* the function name has
- // stabilized, i.e. earlier than the higher-level ResponseTypeToolCall
- // marker downstream consumers see. Useful for distinguishing
- // "tool_calls field arrived but marker not yet emitted" from
- // "tool_calls field truly absent" when triaging stream behavior.
- if !state.firstToolCallSeen && len(toolCalls) > 0 {
- state.firstToolCallSeen = true
- var firstID, firstName string
- for _, tc := range toolCalls {
- if tc.ID != "" {
- firstID = tc.ID
- }
- if tc.Function.Name != "" {
- firstName = tc.Function.Name
- }
- if firstID != "" || firstName != "" {
- break
- }
- }
- logger.Infof(ctx, "[LLM Stream] First tool_calls delta at OpenAI layer "+
- "(count=%d, first_id=%q, first_name=%q, "+
- "first_content_seen=%t, thinking_seen=%t, elapsed_ms=%d)",
- len(toolCalls), firstID, firstName,
- state.firstContentSeen, state.firstReasoningSeen, state.elapsedMs())
- }
-
- for _, tc := range toolCalls {
- var toolCallIndex int
- if tc.Index != nil {
- toolCallIndex = *tc.Index
- }
- toolCallEntry, exists := state.toolCallMap[toolCallIndex]
- if !exists || toolCallEntry == nil {
- toolCallEntry = &types.LLMToolCall{
- Type: string(tc.Type),
- Function: types.FunctionCall{
- Name: "",
- Arguments: "",
- },
- }
- state.toolCallMap[toolCallIndex] = toolCallEntry
- }
-
- if tc.ID != "" {
- toolCallEntry.ID = tc.ID
- }
- if tc.Type != "" {
- toolCallEntry.Type = string(tc.Type)
- }
- if tc.Function.Name != "" {
- // 防御性校验:解决部分供应商(如vLLM Ascend等)在每个流 Chunk 中重复发送完整工具名的问题。
- // 如果当前已存名字与新收到名字一致,则视为冗余重复,不进行叠加。
- if toolCallEntry.Function.Name != tc.Function.Name {
- toolCallEntry.Function.Name += tc.Function.Name
- }
- }
-
- argsUpdated := false
- if tc.Function.Arguments != "" {
- toolCallEntry.Function.Arguments += tc.Function.Arguments
- argsUpdated = true
- }
-
- currName := toolCallEntry.Function.Name
- var progressArgs map[string]any
- if isSandboxMutationTool(currName) && argsUpdated && tc.Function.Arguments != "" {
- prog := state.fileProgress[toolCallIndex]
- if prog == nil {
- prog = newSandboxFileProgress(currName)
- state.fileProgress[toolCallIndex] = prog
- }
- if payload, ok := prog.Feed(tc.Function.Arguments); ok {
- progressArgs = payload
- }
- }
-
- if currName != "" &&
- currName == state.lastFunctionName[toolCallIndex] &&
- argsUpdated &&
- !state.nameNotified[toolCallIndex] &&
- toolCallEntry.ID != "" {
- data := map[string]interface{}{
- "tool_name": currName,
- "tool_call_id": toolCallEntry.ID,
- }
- if progressArgs != nil {
- data["arguments"] = progressArgs
- }
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeToolCall,
- Content: "",
- Done: false,
- Data: data,
- }
- state.nameNotified[toolCallIndex] = true
- progressArgs = nil
- } else if progressArgs != nil && toolCallEntry.ID != "" && currName != "" {
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeToolCall,
- Content: "",
- Done: false,
- Data: map[string]interface{}{
- "tool_name": currName,
- "tool_call_id": toolCallEntry.ID,
- "arguments": progressArgs,
- },
- }
- }
-
- state.lastFunctionName[toolCallIndex] = currName
-
- // Stream thinking tool's thought field as thinking-type chunks
- if toolCallEntry.Function.Name == "thinking" && argsUpdated {
- extractor, exists := state.fieldExtractors[toolCallIndex]
- if !exists {
- extractor = newJSONFieldExtractor("thought")
- state.fieldExtractors[toolCallIndex] = extractor
- }
- thoughtChunk := extractor.Feed(tc.Function.Arguments)
- if thoughtChunk != "" {
- streamChan <- types.StreamResponse{
- ResponseType: types.ResponseTypeThinking,
- Content: thoughtChunk,
- Done: false,
- Data: map[string]interface{}{
- "source": "thinking_tool",
- "tool_call_id": toolCallEntry.ID,
- },
- }
- }
- }
- }
-}
diff --git a/internal/models/chat/prompt_cache.go b/internal/models/chat/prompt_cache.go
deleted file mode 100644
index 0938ab3c7..000000000
--- a/internal/models/chat/prompt_cache.go
+++ /dev/null
@@ -1,374 +0,0 @@
-package chat
-
-import (
- "context"
- "crypto/sha256"
- "encoding/hex"
- "encoding/json"
- "fmt"
- "net/http"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/sashabaranov/go-openai"
-)
-
-// FingerprintPromptPrefix returns a short, non-reversible identifier suitable
-// for logs and cache routing. Raw prompts must never be used as metric labels.
-func FingerprintPromptPrefix(parts ...string) string {
- h := sha256.New()
- for _, part := range parts {
- _, _ = h.Write([]byte(part))
- _, _ = h.Write([]byte{0})
- }
- return hex.EncodeToString(h.Sum(nil))[:16]
-}
-
-// PromptPrefixFingerprint hashes the stable portion common to normal chat and
-// agent requests: leading system messages plus the deterministic tool schema.
-// Dynamic conversation/user messages intentionally do not participate.
-func PromptPrefixFingerprint(messages []Message, opts *ChatOptions) string {
- type stablePrefix struct {
- System []Message `json:"system,omitempty"`
- Tools []Tool `json:"tools,omitempty"`
- }
- prefix := stablePrefix{}
- for _, message := range messages {
- if message.Role != "system" {
- break
- }
- prefix.System = append(prefix.System, message)
- }
- if opts != nil {
- prefix.Tools = opts.Tools
- }
- data, _ := json.Marshal(prefix)
- return FingerprintPromptPrefix(string(data))
-}
-
-// BuildPromptCacheKey derives an opaque process-local coordination key.
-// Tenant and model identifiers are hashed rather than retained in memory.
-func BuildPromptCacheKey(tenantID uint64, modelID, purpose, prefixFingerprint string) string {
- return "wk-" + FingerprintPromptPrefix(
- fmt.Sprintf("%d", tenantID), modelID, purpose, prefixFingerprint,
- )
-}
-
-func providerCacheAccountingStatus(name provider.ProviderName) types.PromptCacheStatus {
- switch name {
- case provider.ProviderOpenAI,
- provider.ProviderAzureOpenAI,
- provider.ProviderDeepSeek,
- provider.ProviderAliyun,
- provider.ProviderAnthropic:
- return types.PromptCacheStatusUnreported
- default:
- return types.PromptCacheStatusUnsupported
- }
-}
-
-func tokenUsageFromOpenAI(usage openai.Usage, providerName provider.ProviderName) types.TokenUsage {
- u := types.TokenUsage{
- PromptTokens: usage.PromptTokens,
- CompletionTokens: usage.CompletionTokens,
- TotalTokens: usage.TotalTokens,
- }
- if usage.PromptTokensDetails != nil {
- read := usage.PromptTokensDetails.CachedTokens
- u.SetPromptCacheUsage(read, 0, max(0, usage.PromptTokens-read), true)
- return u
- }
- if providerCacheAccountingStatus(providerName) == types.PromptCacheStatusUnsupported {
- u.MarkPromptCacheUnsupported()
- } else {
- u.SetPromptCacheUsage(0, 0, 0, false)
- }
- return u
-}
-
-// cachedTokens is retained as the nil-safe primitive used by older callers
-// and focused tests; normalization happens in tokenUsageFromOpenAI.
-func cachedTokens(details *openai.PromptTokensDetails) int {
- if details == nil {
- return 0
- }
- return details.CachedTokens
-}
-
-type rawPromptCacheUsage struct {
- Usage struct {
- PromptTokens int `json:"prompt_tokens"`
- PromptCacheHit *int `json:"prompt_cache_hit_tokens"`
- PromptCacheMiss *int `json:"prompt_cache_miss_tokens"`
- CacheReadInput *int `json:"cache_read_input_tokens"`
- CacheCreationInput *int `json:"cache_creation_input_tokens"`
- PromptTokensDetails *struct {
- CachedTokens *int `json:"cached_tokens"`
- CacheWriteTokens *int `json:"cache_write_tokens"`
- } `json:"prompt_tokens_details"`
- } `json:"usage"`
-}
-
-// applyRawPromptCacheUsage captures native fields discarded by the pinned
-// OpenAI-compatible SDK (notably DeepSeek hit/miss counters).
-func applyRawPromptCacheUsage(data []byte, usage *types.TokenUsage) {
- if usage == nil || len(data) == 0 {
- return
- }
- var raw rawPromptCacheUsage
- if json.Unmarshal(data, &raw) != nil {
- return
- }
- if raw.Usage.PromptCacheHit != nil || raw.Usage.PromptCacheMiss != nil {
- read := valueOrZero(raw.Usage.PromptCacheHit)
- miss := valueOrZero(raw.Usage.PromptCacheMiss)
- usage.SetPromptCacheUsage(read, 0, miss, true)
- return
- }
- if raw.Usage.CacheReadInput != nil || raw.Usage.CacheCreationInput != nil {
- read := valueOrZero(raw.Usage.CacheReadInput)
- write := valueOrZero(raw.Usage.CacheCreationInput)
- usage.SetPromptCacheUsage(read, write, max(0, usage.PromptTokens-read), true)
- return
- }
- if details := raw.Usage.PromptTokensDetails; details != nil {
- read := valueOrZero(details.CachedTokens)
- write := valueOrZero(details.CacheWriteTokens)
- usage.SetPromptCacheUsage(read, write, max(0, usage.PromptTokens-read), true)
- }
-}
-
-func valueOrZero(value *int) int {
- if value == nil {
- return 0
- }
- return *value
-}
-
-// CacheRetention is the prompt-cache TTL preference. Empty means short (the
-// default 5-minute provider cache). Compaction/summarization uses none so a
-// different prompt prefix does not occupy the session's cache slot.
-type CacheRetention string
-
-const (
- CacheRetentionNone CacheRetention = "none"
- CacheRetentionShort CacheRetention = "short"
- CacheRetentionLong CacheRetention = "long"
-)
-
-const openAIPromptCacheKeyMaxLength = 64
-
-func clampPromptCacheKey(key string) string {
- if key == "" {
- return ""
- }
- runes := []rune(key)
- if len(runes) <= openAIPromptCacheKeyMaxLength {
- return key
- }
- return string(runes[:openAIPromptCacheKeyMaxLength])
-}
-
-func resolveCacheRetention(opts *ChatOptions) CacheRetention {
- if opts != nil && opts.CacheRetention != "" {
- return opts.CacheRetention
- }
- return CacheRetentionShort
-}
-
-func promptCacheSessionID(ctx context.Context, opts *ChatOptions) string {
- if opts != nil && opts.PromptCacheKey != "" {
- return clampPromptCacheKey(opts.PromptCacheKey)
- }
- if sessionID, ok := types.SessionIDFromContext(ctx); ok {
- return clampPromptCacheKey(sessionID)
- }
- return ""
-}
-
-type promptCachePolicy struct {
- sendKey bool
- sendCacheControl bool
- sendAffinity bool
-}
-
-func promptCachePolicyFor(name provider.ProviderName, baseURL string) promptCachePolicy {
- switch name {
- case provider.ProviderOpenAI, provider.ProviderAzureOpenAI, provider.ProviderOpenRouter:
- return promptCachePolicy{sendKey: true, sendAffinity: true}
- case provider.ProviderAliyun:
- return promptCachePolicy{sendCacheControl: true}
- case provider.ProviderAnthropic:
- return promptCachePolicy{sendCacheControl: true}
- }
- if strings.Contains(baseURL, "api.openai.com") {
- return promptCachePolicy{sendKey: true, sendAffinity: true}
- }
- return promptCachePolicy{}
-}
-
-type cacheControlMarker struct {
- Type string `json:"type"`
- TTL string `json:"ttl,omitempty"`
-}
-
-func cacheControlFor(retention CacheRetention, longTTL string) *cacheControlMarker {
- if retention == CacheRetentionNone {
- return nil
- }
- marker := &cacheControlMarker{Type: "ephemeral"}
- if retention == CacheRetentionLong && longTTL != "" {
- marker.TTL = longTTL
- }
- return marker
-}
-
-// applyPromptCacheToJSONBody injects provider cache routing and breakpoints
-// into an already-shaped OpenAI-compatible request object. Returns the (possibly
-// rewritten) body and whether the caller must send it via raw HTTP because the
-// SDK struct cannot carry these fields.
-func applyPromptCacheToJSONBody(
- body any,
- policy promptCachePolicy,
- sessionID string,
- retention CacheRetention,
-) (any, bool, error) {
- if retention == CacheRetentionNone {
- return body, false, nil
- }
- if !policy.sendKey && !policy.sendCacheControl {
- return body, false, nil
- }
-
- data, err := json.Marshal(body)
- if err != nil {
- return nil, false, err
- }
- var payload map[string]any
- if err := json.Unmarshal(data, &payload); err != nil {
- return nil, false, err
- }
-
- rewritten := false
- if policy.sendKey && sessionID != "" {
- payload["prompt_cache_key"] = sessionID
- if retention == CacheRetentionLong {
- payload["prompt_cache_retention"] = "24h"
- }
- rewritten = true
- }
- if policy.sendCacheControl {
- marker := cacheControlFor(retention, "1h")
- if marker != nil {
- applyCacheControlBreakpoints(payload, marker)
- rewritten = true
- }
- }
- if !rewritten {
- return body, false, nil
- }
- return payload, true, nil
-}
-
-func applyCacheControlBreakpoints(payload map[string]any, marker *cacheControlMarker) {
- if marker == nil {
- return
- }
- applyCacheControlToInstructionMessages(payload["messages"], marker)
- applyCacheControlToLastTool(payload["tools"], marker)
- applyCacheControlToLastConversationMessage(payload["messages"], marker)
-}
-
-func applyCacheControlToInstructionMessages(raw any, marker *cacheControlMarker) {
- messages, ok := raw.([]any)
- if !ok {
- return
- }
- for _, item := range messages {
- msg, ok := item.(map[string]any)
- if !ok {
- continue
- }
- role, _ := msg["role"].(string)
- if role == "system" || role == "developer" {
- addCacheControlToMessageContent(msg, marker)
- return
- }
- }
-}
-
-func applyCacheControlToLastConversationMessage(raw any, marker *cacheControlMarker) {
- messages, ok := raw.([]any)
- if !ok {
- return
- }
- for i := len(messages) - 1; i >= 0; i-- {
- msg, ok := messages[i].(map[string]any)
- if !ok {
- continue
- }
- role, _ := msg["role"].(string)
- if role == "user" || role == "assistant" || role == "tool" {
- if addCacheControlToMessageContent(msg, marker) {
- return
- }
- }
- }
-}
-
-func applyCacheControlToLastTool(raw any, marker *cacheControlMarker) {
- tools, ok := raw.([]any)
- if !ok || len(tools) == 0 {
- return
- }
- last, ok := tools[len(tools)-1].(map[string]any)
- if !ok {
- return
- }
- last["cache_control"] = marker
-}
-
-func addCacheControlToMessageContent(msg map[string]any, marker *cacheControlMarker) bool {
- content, ok := msg["content"]
- if !ok || content == nil {
- return false
- }
- if text, ok := content.(string); ok {
- if text == "" {
- return false
- }
- msg["content"] = []any{
- map[string]any{
- "type": "text",
- "text": text,
- "cache_control": marker,
- },
- }
- return true
- }
- parts, ok := content.([]any)
- if !ok {
- return false
- }
- for i := len(parts) - 1; i >= 0; i-- {
- part, ok := parts[i].(map[string]any)
- if !ok {
- continue
- }
- if partType, _ := part["type"].(string); partType == "text" || partType == "tool_result" {
- part["cache_control"] = marker
- return true
- }
- }
- return false
-}
-
-func attachPromptCacheHeaders(req *http.Request, policy promptCachePolicy, sessionID string) {
- if req == nil || !policy.sendAffinity || sessionID == "" {
- return
- }
- req.Header.Set("session_id", sessionID)
- req.Header.Set("x-client-request-id", sessionID)
- req.Header.Set("x-session-affinity", sessionID)
-}
diff --git a/internal/models/chat/prompt_cache_apply_test.go b/internal/models/chat/prompt_cache_apply_test.go
deleted file mode 100644
index 2b68c8598..000000000
--- a/internal/models/chat/prompt_cache_apply_test.go
+++ /dev/null
@@ -1,117 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "net/http"
- "strings"
- "testing"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/sashabaranov/go-openai"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-func TestClampPromptCacheKey(t *testing.T) {
- assert.Equal(t, "", clampPromptCacheKey(""))
- assert.Equal(t, "sess-1", clampPromptCacheKey("sess-1"))
- long := strings.Repeat("a", 80)
- got := clampPromptCacheKey(long)
- assert.Equal(t, 64, len([]rune(got)))
- assert.Equal(t, strings.Repeat("a", 64), got)
-}
-
-func TestApplyPromptCacheToJSONBody_OpenAIKey(t *testing.T) {
- req := openai.ChatCompletionRequest{
- Model: "gpt-4o",
- Messages: []openai.ChatCompletionMessage{
- {Role: "system", Content: "sys"},
- {Role: "user", Content: "hi"},
- },
- }
- policy := promptCachePolicyFor(provider.ProviderOpenAI, "")
- body, forceRaw, err := applyPromptCacheToJSONBody(req, policy, "sess-abc", CacheRetentionShort)
- require.NoError(t, err)
- require.True(t, forceRaw)
- payload := body.(map[string]any)
- assert.Equal(t, "sess-abc", payload["prompt_cache_key"])
- assert.NotContains(t, payload, "prompt_cache_retention")
-}
-
-func TestApplyPromptCacheToJSONBody_OpenAILongRetention(t *testing.T) {
- req := openai.ChatCompletionRequest{Model: "gpt-4o"}
- policy := promptCachePolicyFor(provider.ProviderOpenAI, "")
- body, forceRaw, err := applyPromptCacheToJSONBody(req, policy, "sess-abc", CacheRetentionLong)
- require.NoError(t, err)
- require.True(t, forceRaw)
- payload := body.(map[string]any)
- assert.Equal(t, "24h", payload["prompt_cache_retention"])
-}
-
-func TestApplyPromptCacheToJSONBody_NoneLeavesBodyUntouched(t *testing.T) {
- req := &openai.ChatCompletionRequest{Model: "gpt-4o"}
- policy := promptCachePolicyFor(provider.ProviderOpenAI, "")
- body, forceRaw, err := applyPromptCacheToJSONBody(req, policy, "sess-abc", CacheRetentionNone)
- require.NoError(t, err)
- assert.False(t, forceRaw)
- assert.Equal(t, req, body)
-}
-
-func TestApplyPromptCacheToJSONBody_AliyunCacheControlBreakpoints(t *testing.T) {
- req := openai.ChatCompletionRequest{
- Model: "qwen-plus",
- Messages: []openai.ChatCompletionMessage{
- {Role: "system", Content: "stable system"},
- {Role: "user", Content: "turn question"},
- },
- Tools: []openai.Tool{{
- Type: openai.ToolTypeFunction,
- Function: &openai.FunctionDefinition{Name: "search", Description: "d", Parameters: json.RawMessage(`{}`)},
- }},
- }
- policy := promptCachePolicyFor(provider.ProviderAliyun, "")
- body, forceRaw, err := applyPromptCacheToJSONBody(req, policy, "", CacheRetentionShort)
- require.NoError(t, err)
- require.True(t, forceRaw)
- wire, err := json.Marshal(body)
- require.NoError(t, err)
- var payload map[string]any
- require.NoError(t, json.Unmarshal(wire, &payload))
-
- messages := payload["messages"].([]any)
- sys := messages[0].(map[string]any)
- sysParts := sys["content"].([]any)
- sysCache := sysParts[0].(map[string]any)["cache_control"].(map[string]any)
- assert.Equal(t, "ephemeral", sysCache["type"])
-
- user := messages[1].(map[string]any)
- userParts := user["content"].([]any)
- userCache := userParts[0].(map[string]any)["cache_control"].(map[string]any)
- assert.Equal(t, "ephemeral", userCache["type"])
-
- tools := payload["tools"].([]any)
- lastTool := tools[len(tools)-1].(map[string]any)
- toolCache := lastTool["cache_control"].(map[string]any)
- assert.Equal(t, "ephemeral", toolCache["type"])
-}
-
-func TestBuildOutbound_OpenAIPromptCacheKeyFromSession(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderOpenAI), "gpt-4o", nil)
- ctx := types.WithSessionID(context.Background(), "sess-live")
- body, _, useRaw, err := c.buildOutbound(ctx, []Message{{Role: "user", Content: "hi"}}, &ChatOptions{}, false)
- require.NoError(t, err)
- require.True(t, useRaw)
- payload := body.(map[string]any)
- assert.Equal(t, "sess-live", payload["prompt_cache_key"])
-}
-
-func TestAttachPromptCacheHeaders(t *testing.T) {
- req, err := http.NewRequest(http.MethodPost, "https://api.openai.com/v1/chat/completions", nil)
- require.NoError(t, err)
- attachPromptCacheHeaders(req, promptCachePolicy{sendAffinity: true}, "sess-1")
- assert.Equal(t, "sess-1", req.Header.Get("session_id"))
- assert.Equal(t, "sess-1", req.Header.Get("x-client-request-id"))
- assert.Equal(t, "sess-1", req.Header.Get("x-session-affinity"))
-}
diff --git a/internal/models/chat/provider.go b/internal/models/chat/provider.go
deleted file mode 100644
index be1a4f799..000000000
--- a/internal/models/chat/provider.go
+++ /dev/null
@@ -1,304 +0,0 @@
-package chat
-
-import (
- "encoding/json"
- "net/http"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- modelutils "github.com/Tencent/WeKnora/internal/models/utils"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/google/uuid"
- "github.com/sashabaranov/go-openai"
-)
-
-// authCreds carries the credentials a providerAdapter needs to authenticate a
-// raw HTTP request. APIKey covers the common Bearer / api-key cases; AppID and
-// AppSecret are only used by signing providers (WeKnoraCloud).
-type authCreds struct {
- APIKey string
- AppID string
- AppSecret string
-}
-
-// providerAdapter captures everything provider-specific about an
-// OpenAI-compatible chat backend. Every method has a sensible default on
-// baseProvider, so a new provider is added by embedding baseProvider and
-// overriding only the one or two methods that actually differ.
-type providerAdapter interface {
- // Name is the provider this adapter handles.
- Name() provider.ProviderName
- // Matches reports whether this adapter applies to the given model name.
- // Used for sub-provider routing (e.g. Qwen thinking models within Aliyun,
- // reasoning models within OpenAI). Default: true.
- Matches(model string) bool
- // Thinking is how this provider encodes ChatOptions.Thinking. Default: none.
- Thinking() ThinkingStrategy
- // ShapeRequest applies in-place parameter quirks to the standard request
- // (stripping unsupported fields, pinning temperature, …). Default: noop.
- ShapeRequest(req *openai.ChatCompletionRequest, opts *ChatOptions, isStream bool)
- // TransformMessages rewrites the converted messages (e.g. downgrading
- // multi-content to plain text). Default: identity.
- TransformMessages(msgs []openai.ChatCompletionMessage) []openai.ChatCompletionMessage
- // Endpoint overrides the request URL. Empty string means the standard
- // "<baseURL>/chat/completions" handled by the caller. Default: "".
- Endpoint(baseURL, modelID string, isStream bool) string
- // Auth sets authentication headers on a raw HTTP request. Default: Bearer.
- Auth(req *http.Request, creds authCreds, body []byte)
- // ForceRawHTTP forces the raw HTTP path even when the body is standard
- // (needed by providers that must sign the exact request bytes). Default: false.
- ForceRawHTTP() bool
- // ExtractToolCallMetadata captures provider-specific state from a raw
- // OpenAI-compatible tool_call object. Default: nil.
- ExtractToolCallMetadata(raw json.RawMessage) types.ToolCallMetadata
- // InjectToolCallMetadata writes provider-specific state back into an outbound
- // OpenAI-compatible tool_call object. Default: noop.
- InjectToolCallMetadata(toolCall map[string]any, metadata types.ToolCallMetadata)
-}
-
-// baseProvider supplies the default behavior for every providerAdapter method.
-// It is also the fallback returned by resolveProvider for unknown providers:
-// Bearer auth, standard endpoint, no thinking, no request shaping.
-type baseProvider struct{}
-
-func (baseProvider) Name() provider.ProviderName { return "" }
-func (baseProvider) Matches(string) bool { return true }
-func (baseProvider) Thinking() ThinkingStrategy { return noThinking{} }
-func (baseProvider) ShapeRequest(*openai.ChatCompletionRequest, *ChatOptions, bool) {}
-func (baseProvider) TransformMessages(msgs []openai.ChatCompletionMessage) []openai.ChatCompletionMessage {
- return msgs
-}
-func (baseProvider) Endpoint(string, string, bool) string { return "" }
-func (baseProvider) Auth(req *http.Request, creds authCreds, _ []byte) {
- req.Header.Set("Authorization", "Bearer "+creds.APIKey)
-}
-func (baseProvider) ForceRawHTTP() bool { return false }
-func (baseProvider) ExtractToolCallMetadata(json.RawMessage) types.ToolCallMetadata {
- return nil
-}
-func (baseProvider) InjectToolCallMetadata(map[string]any, types.ToolCallMetadata) {}
-
-// --- WeKnoraCloud: custom endpoint + request signing + multi-content downgrade ---
-
-type weKnoraCloudProvider struct{ baseProvider }
-
-func (weKnoraCloudProvider) Name() provider.ProviderName { return provider.ProviderWeKnoraCloud }
-
-func (weKnoraCloudProvider) Endpoint(baseURL, _ string, _ bool) string {
- return strings.TrimRight(baseURL, "/") + "/api/v1/chat/completions"
-}
-
-func (weKnoraCloudProvider) ForceRawHTTP() bool { return true }
-
-func (weKnoraCloudProvider) Auth(req *http.Request, creds authCreds, body []byte) {
- requestID := uuid.NewString()
- headers := modelutils.Sign(creds.AppID, creds.AppSecret, requestID, string(body))
- for k, v := range headers {
- req.Header.Set(k, v)
- }
-}
-
-// TransformMessages downgrades MultiContent to plain text while preserving
-// tool_calls / tool_call_id / name so the function-calling protocol keeps working.
-func (weKnoraCloudProvider) TransformMessages(messages []openai.ChatCompletionMessage) []openai.ChatCompletionMessage {
- result := make([]openai.ChatCompletionMessage, 0, len(messages))
- for _, m := range messages {
- msg := m
- if msg.Content == "" && len(msg.MultiContent) > 0 {
- var textParts []string
- for _, part := range msg.MultiContent {
- if part.Type == openai.ChatMessagePartTypeText && part.Text != "" {
- textParts = append(textParts, part.Text)
- }
- }
- msg.Content = strings.Join(textParts, "\n")
- msg.MultiContent = nil
- }
- result = append(result, msg)
- }
- return result
-}
-
-// --- Aliyun Qwen thinking models: enable_thinking (always sent, forced off non-stream) ---
-
-type qwenThinkingProvider struct{ baseProvider }
-
-func (qwenThinkingProvider) Name() provider.ProviderName { return provider.ProviderAliyun }
-func (qwenThinkingProvider) Matches(model string) bool { return provider.IsQwenThinkingModel(model) }
-func (qwenThinkingProvider) Thinking() ThinkingStrategy {
- return enableThinking{alwaysSend: true, disableOnNonStream: true}
-}
-
-// --- LKEAP: thinking via { "thinking": { "type": ... } }, only for DeepSeek V3.x ---
-// R1 series enables chain-of-thought by default and is left untouched (falls
-// back to baseProvider). See https://cloud.tencent.com/document/product/1772/115963
-
-type lkeapProvider struct{ baseProvider }
-
-func (lkeapProvider) Name() provider.ProviderName { return provider.ProviderLKEAP }
-func (lkeapProvider) Matches(model string) bool {
- return strings.Contains(strings.ToLower(model), "deepseek-v3")
-}
-func (lkeapProvider) Thinking() ThinkingStrategy { return thinkingTypeField{} }
-
-// --- DeepSeek: does not support tool_choice ---
-
-type deepseekProvider struct{ baseProvider }
-
-func (deepseekProvider) Name() provider.ProviderName { return provider.ProviderDeepSeek }
-
-// Native DeepSeek cache counters are not represented by go-openai v1.41.2;
-// use the raw path so prompt_cache_hit_tokens/miss_tokens remain observable.
-func (deepseekProvider) ForceRawHTTP() bool { return true }
-func (deepseekProvider) ShapeRequest(req *openai.ChatCompletionRequest, opts *ChatOptions, _ bool) {
- if opts != nil && opts.ToolChoice != "" {
- req.ToolChoice = nil
- }
-}
-
-// --- Generic (vLLM) / NVIDIA / LiteLLM: thinking via chat_template_kwargs ---
-
-type genericProvider struct{ baseProvider }
-
-func (genericProvider) Name() provider.ProviderName { return provider.ProviderGeneric }
-func (genericProvider) Thinking() ThinkingStrategy { return chatTemplateKwargs{} }
-
-type nvidiaProvider struct{ baseProvider }
-
-func (nvidiaProvider) Name() provider.ProviderName { return provider.ProviderNvidia }
-func (nvidiaProvider) Thinking() ThinkingStrategy { return chatTemplateKwargs{} }
-
-type liteLLMProvider struct{ baseProvider }
-
-func (liteLLMProvider) Name() provider.ProviderName { return provider.ProviderLiteLLM }
-func (liteLLMProvider) Thinking() ThinkingStrategy { return chatTemplateKwargs{} }
-
-// --- Gemini OpenAI compatibility: tool thought signatures live in extra_content ---
-
-type geminiProvider struct{ baseProvider }
-
-func (geminiProvider) Name() provider.ProviderName { return provider.ProviderGemini }
-func (geminiProvider) ForceRawHTTP() bool { return true }
-func (geminiProvider) ExtractToolCallMetadata(raw json.RawMessage) types.ToolCallMetadata {
- var tc struct {
- ExtraContent map[string]json.RawMessage `json:"extra_content,omitempty"`
- }
- if err := json.Unmarshal(raw, &tc); err != nil {
- return nil
- }
- google, ok := tc.ExtraContent["google"]
- if !ok || len(google) == 0 {
- return nil
- }
- return types.ToolCallMetadata{"google": google}
-}
-func (geminiProvider) InjectToolCallMetadata(toolCall map[string]any, metadata types.ToolCallMetadata) {
- if len(metadata) == 0 {
- return
- }
- google, ok := metadata["google"]
- if !ok || len(google) == 0 {
- return
- }
- var googleValue any
- if err := json.Unmarshal(google, &googleValue); err != nil {
- return
- }
- toolCall["extra_content"] = map[string]any{"google": googleValue}
-}
-
-// --- Volcengine (火山引擎 Ark): thinking via { "thinking": { "type": ... } } ---
-
-type volcengineProvider struct{ baseProvider }
-
-func (volcengineProvider) Name() provider.ProviderName { return provider.ProviderVolcengine }
-func (volcengineProvider) Thinking() ThinkingStrategy { return thinkingTypeField{} }
-
-// --- Azure OpenAI: api-key auth (reasoning variant also strips sampling params) ---
-
-type azureProvider struct{ baseProvider }
-
-func (azureProvider) Name() provider.ProviderName { return provider.ProviderAzureOpenAI }
-func (azureProvider) Auth(req *http.Request, creds authCreds, _ []byte) {
- req.Header.Set("api-key", creds.APIKey)
-}
-
-type azureReasoningProvider struct{ azureProvider }
-
-func (azureReasoningProvider) Matches(model string) bool {
- return provider.IsOpenAIReasoningOrGPT5Model(model)
-}
-func (azureReasoningProvider) ShapeRequest(req *openai.ChatCompletionRequest, _ *ChatOptions, _ bool) {
- shapeOpenAIReasoning(req)
-}
-
-// --- OpenAI reasoning / GPT-5: no sampling params, must use max_completion_tokens ---
-
-type openAIReasoningProvider struct{ baseProvider }
-
-func (openAIReasoningProvider) Name() provider.ProviderName { return provider.ProviderOpenAI }
-func (openAIReasoningProvider) Matches(model string) bool {
- return provider.IsOpenAIReasoningOrGPT5Model(model)
-}
-func (openAIReasoningProvider) ShapeRequest(req *openai.ChatCompletionRequest, _ *ChatOptions, _ bool) {
- shapeOpenAIReasoning(req)
-}
-
-// --- Moonshot: v1 models accept only temperature=1 ---
-
-type moonshotProvider struct{ baseProvider }
-
-func (moonshotProvider) Name() provider.ProviderName { return provider.ProviderMoonshot }
-func (moonshotProvider) Matches(model string) bool {
- return provider.IsMoonshotFixedTempModel(model)
-}
-func (moonshotProvider) ShapeRequest(req *openai.ChatCompletionRequest, _ *ChatOptions, _ bool) {
- // Pin temperature to 1 and drop the other sampling params, matching the
- // pre-refactor behavior where these fields were never set for this model.
- req.Temperature = 1
- req.TopP = 0
- req.FrequencyPenalty = 0
- req.PresencePenalty = 0
-}
-
-// shapeOpenAIReasoning strips sampling params (unsupported by o-series / GPT-5)
-// and migrates max_tokens to max_completion_tokens. See issue #1283.
-func shapeOpenAIReasoning(req *openai.ChatCompletionRequest) {
- req.Temperature = 0
- req.TopP = 0
- req.FrequencyPenalty = 0
- req.PresencePenalty = 0
- if req.MaxCompletionTokens == 0 && req.MaxTokens > 0 {
- req.MaxCompletionTokens = req.MaxTokens
- }
- req.MaxTokens = 0
-}
-
-// providerRegistry is ordered: more specific adapters (those with a real
-// Matches predicate) must precede the generic catch-all for the same provider.
-var providerRegistry = []providerAdapter{
- weKnoraCloudProvider{},
- qwenThinkingProvider{},
- lkeapProvider{},
- deepseekProvider{},
- genericProvider{},
- liteLLMProvider{},
- geminiProvider{},
- volcengineProvider{},
- nvidiaProvider{},
- azureReasoningProvider{},
- azureProvider{},
- openAIReasoningProvider{},
- moonshotProvider{},
-}
-
-// resolveProvider returns the adapter handling the given provider+model, or
-// baseProvider{} (Bearer auth, standard endpoint, no thinking) when none matches.
-func resolveProvider(name provider.ProviderName, model string) providerAdapter {
- for _, p := range providerRegistry {
- if p.Name() == name && p.Matches(model) {
- return p
- }
- }
- return baseProvider{}
-}
diff --git a/internal/models/chat/provider_test.go b/internal/models/chat/provider_test.go
deleted file mode 100644
index 48da3fc43..000000000
--- a/internal/models/chat/provider_test.go
+++ /dev/null
@@ -1,200 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "testing"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/sashabaranov/go-openai"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-// TestResolveProvider pins the provider+model routing table, including the
-// sub-model matchers (reasoning models, Qwen thinking, LKEAP DeepSeek V3) and
-// the baseProvider fallback for everything else.
-func TestResolveProvider(t *testing.T) {
- cases := []struct {
- name string
- prov provider.ProviderName
- model string
- want providerAdapter
- }{
- {"deepseek", provider.ProviderDeepSeek, "deepseek-chat", deepseekProvider{}},
- {"lkeap v3", provider.ProviderLKEAP, "deepseek-v3.1", lkeapProvider{}},
- {"lkeap r1 falls back", provider.ProviderLKEAP, "deepseek-r1", baseProvider{}},
- {"qwen thinking", provider.ProviderAliyun, "qwen3-32b", qwenThinkingProvider{}},
- {"generic", provider.ProviderGeneric, "anything", genericProvider{}},
- {"litellm", provider.ProviderLiteLLM, "anything", liteLLMProvider{}},
- {"gemini", provider.ProviderGemini, "gemini-3-flash-preview", geminiProvider{}},
- {"nvidia", provider.ProviderNvidia, "anything", nvidiaProvider{}},
- {"volcengine", provider.ProviderVolcengine, "doubao", volcengineProvider{}},
- {"openai non-reasoning falls back", provider.ProviderOpenAI, "gpt-4o", baseProvider{}},
- {"openai reasoning", provider.ProviderOpenAI, "gpt-5", openAIReasoningProvider{}},
- {"azure non-reasoning", provider.ProviderAzureOpenAI, "gpt-4", azureProvider{}},
- {"azure reasoning", provider.ProviderAzureOpenAI, "gpt-5-mini", azureReasoningProvider{}},
- {"moonshot fixed temp", provider.ProviderMoonshot, "moonshot-v1-8k", moonshotProvider{}},
- {"moonshot other falls back", provider.ProviderMoonshot, "kimi-latest", baseProvider{}},
- {"weknora cloud", provider.ProviderWeKnoraCloud, "anything", weKnoraCloudProvider{}},
- {"unknown falls back", provider.ProviderName("nope"), "x", baseProvider{}},
- }
- for _, tc := range cases {
- t.Run(tc.name, func(t *testing.T) {
- assert.IsType(t, tc.want, resolveProvider(tc.prov, tc.model))
- })
- }
-}
-
-func newOutboundChat(t *testing.T, providerName, model string, extra map[string]string) *RemoteAPIChat {
- t.Helper()
- c, err := NewRemoteAPIChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- ModelName: model,
- APIKey: "k",
- ModelID: model,
- Provider: providerName,
- ExtraConfig: extra,
- })
- require.NoError(t, err)
- return c
-}
-
-// TestBuildOutbound_Thinking is the characterization suite for the merged
-// thinking-control path: it asserts that buildOutbound produces the same wire
-// formats the pre-refactor provider customizers did.
-func TestBuildOutbound_Thinking(t *testing.T) {
- msgs := []Message{{Role: "user", Content: "hi"}}
-
- t.Run("generic explicit thinking_type overrides legacy kwargs", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderGeneric), "deepseek-v4-flash",
- map[string]string{ExtraConfigThinkingControl: "thinking_type"})
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(false)}, true)
- require.NoError(t, err)
- require.True(t, useRaw)
- js := mustJSON(t, body)
- assert.Contains(t, js, `"thinking"`)
- assert.Contains(t, js, `"disabled"`)
- assert.NotContains(t, js, "chat_template_kwargs")
- })
-
- t.Run("generic legacy chat_template_kwargs", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderGeneric), "qwen", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(false)}, true)
- require.NoError(t, err)
- require.True(t, useRaw)
- assert.Contains(t, mustJSON(t, body), "chat_template_kwargs")
- })
-
- t.Run("none keeps the standard SDK request", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderGeneric), "x",
- map[string]string{ExtraConfigThinkingControl: "none"})
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(false)}, true)
- require.NoError(t, err)
- assert.False(t, useRaw)
- _, ok := body.(*openai.ChatCompletionRequest)
- assert.True(t, ok)
- })
-
- t.Run("qwen non-stream forces disabled", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderAliyun), "qwen3-32b", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(true)}, false)
- require.NoError(t, err)
- require.True(t, useRaw)
- assert.Contains(t, mustJSON(t, body), `"enable_thinking":false`)
- })
-
- t.Run("qwen stream honors requested true", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderAliyun), "qwen3-32b", nil)
- body, _, _, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(true)}, true)
- require.NoError(t, err)
- assert.Contains(t, mustJSON(t, body), `"enable_thinking":true`)
- })
-
- t.Run("volcengine thinking enabled", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderVolcengine), "doubao", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(true)}, true)
- require.NoError(t, err)
- require.True(t, useRaw)
- js := mustJSON(t, body)
- assert.Contains(t, js, `"thinking"`)
- assert.Contains(t, js, `"enabled"`)
- })
-
- t.Run("lkeap deepseek-v3 emits thinking type", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderLKEAP), "deepseek-v3.1", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(false)}, true)
- require.NoError(t, err)
- require.True(t, useRaw)
- assert.Contains(t, mustJSON(t, body), `"thinking"`)
- })
-
- t.Run("lkeap r1 left untouched", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderLKEAP), "deepseek-r1", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Thinking: ptrBool(false)}, true)
- require.NoError(t, err)
- assert.False(t, useRaw)
- _, ok := body.(*openai.ChatCompletionRequest)
- assert.True(t, ok)
- })
-}
-
-// TestBuildOutbound_ShapeRequest covers the param-shaping providers that used
-// to live inline in BuildChatCompletionRequest.
-func TestBuildOutbound_ShapeRequest(t *testing.T) {
- msgs := []Message{{Role: "user", Content: "hi"}}
-
- t.Run("deepseek strips tool_choice", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderDeepSeek), "deepseek-chat", nil)
- body, _, useRaw, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{ToolChoice: "auto"}, false)
- require.NoError(t, err)
- assert.True(t, useRaw)
- request, ok := body.(map[string]any)
- require.True(t, ok)
- assert.NotContains(t, request, "tool_choice")
- })
-
- t.Run("moonshot pins temperature to 1", func(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderMoonshot), "moonshot-v1-8k", nil)
- body, _, _, err := c.buildOutbound(context.Background(), msgs, &ChatOptions{Temperature: 0.7, TopP: 0.9}, false)
- require.NoError(t, err)
- req := body.(*openai.ChatCompletionRequest)
- assert.EqualValues(t, 1, req.Temperature)
- assert.EqualValues(t, 0, req.TopP)
- })
-}
-
-func TestBuildOutbound_GeminiProviderMetadata(t *testing.T) {
- c := newOutboundChat(t, string(provider.ProviderGemini), "gemini-3-flash-preview", nil)
- messages := []Message{
- {Role: "user", Content: "find docs"},
- {
- Role: "assistant",
- ToolCalls: []ToolCall{{
- ID: "call_1",
- Type: "function",
- ProviderMetadata: types.ToolCallMetadata{"google": json.RawMessage(`{"thought_signature":"gemini-signature"}`)},
- Function: FunctionCall{
- Name: "wiki_search",
- Arguments: `{"query":"MACS"}`,
- },
- }},
- },
- }
-
- body, _, useRaw, err := c.buildOutbound(context.Background(), messages, &ChatOptions{}, false)
- require.NoError(t, err)
- require.True(t, useRaw)
-
- js := mustJSON(t, body)
- assert.Contains(t, js, `"extra_content"`)
- assert.Contains(t, js, `"thought_signature":"gemini-signature"`)
-}
-
-func mustJSON(t *testing.T, v any) string {
- t.Helper()
- b, err := json.Marshal(v)
- require.NoError(t, err)
- return string(b)
-}
diff --git a/internal/models/chat/remote_api.go b/internal/models/chat/remote_api.go
deleted file mode 100644
index c55e94ba1..000000000
--- a/internal/models/chat/remote_api.go
+++ /dev/null
@@ -1,429 +0,0 @@
-package chat
-
-import (
- "bytes"
- "context"
- "encoding/json"
- "fmt"
- "io"
- "net/http"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/logger"
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/Tencent/WeKnora/internal/types"
- secutils "github.com/Tencent/WeKnora/internal/utils"
- "github.com/sashabaranov/go-openai"
-)
-
-// RemoteAPIChat 实现了基于 OpenAI 兼容 API 的聊天。
-// 它本身只负责通用的请求/响应/流式处理;所有 provider 特定行为都委托给
-// providerAdapter(见 provider.go),thinking 编码委托给 ThinkingStrategy
-// (见 thinking.go)。
-type RemoteAPIChat struct {
- modelName string
- client *openai.Client
- modelID string
- baseURL string
- apiKey string
- provider provider.ProviderName
- appID string
- appSecret string
- // customHeaders 为用户在模型配置中指定的自定义 HTTP 请求头(类似 OpenAI Python SDK 的 extra_headers)。
- customHeaders map[string]string
-
- // adapter 承载所有 provider 特定行为(thinking / 参数特判 / endpoint / 鉴权 / 消息变换)。
- adapter providerAdapter
- // thinkingOverride 来自 extra_config.thinking_control,非 nil 时覆盖 adapter.Thinking()。
- thinkingOverride ThinkingStrategy
-}
-
-// NewRemoteAPIChat 创建远程 API 聊天实例
-func NewRemoteAPIChat(chatConfig *ChatConfig) (*RemoteAPIChat, error) {
- if chatConfig.BaseURL != "" {
- if err := secutils.ValidateURLForSSRF(chatConfig.BaseURL); err != nil {
- return nil, fmt.Errorf("baseURL SSRF check failed: %w", err)
- }
- }
-
- apiKey := chatConfig.APIKey
- providerName := provider.ProviderName(chatConfig.Provider)
- if providerName == "" {
- providerName = provider.DetectProvider(chatConfig.BaseURL)
- }
-
- var config openai.ClientConfig
- if providerName == provider.ProviderAzureOpenAI {
- config = openai.DefaultAzureConfig(apiKey, chatConfig.BaseURL)
- config.AzureModelMapperFunc = func(model string) string {
- return model
- }
- if chatConfig.ExtraConfig != nil {
- if v, ok := chatConfig.ExtraConfig["api_version"]; ok {
- config.APIVersion = v
- }
- }
- } else {
- config = openai.DefaultConfig(apiKey)
- if baseURL := chatConfig.BaseURL; baseURL != "" {
- config.BaseURL = baseURL
- } else if providerName == provider.ProviderDeepSeek {
- config.BaseURL = provider.DeepSeekBaseURL
- }
- }
-
- // The SDK must use the same SSRF-safe transport as the raw HTTP paths.
- // Constructor-time URL validation alone cannot prevent DNS rebinding or a
- // later redirect to an internal address.
- sdkHTTPClient := rawHTTPClient
- // 如果指定了 CustomHeaders,则给 SDK 使用的 HTTPClient 挂一层 RoundTripper,
- // 在每个请求上自动注入这些 header(raw HTTP 路径会在发送前单独处理)。
- if len(chatConfig.CustomHeaders) > 0 {
- sdkHTTPClient = secutils.WrapHTTPClientWithHeaders(sdkHTTPClient, chatConfig.CustomHeaders)
- }
- config.HTTPClient = sdkHTTPClient
-
- modelName := chatConfig.ModelName
- if chatConfig.ExtraConfig != nil {
- if override := strings.TrimSpace(chatConfig.ExtraConfig["remote_model_name"]); override != "" {
- modelName = override
- }
- }
- if providerName == provider.ProviderWeKnoraCloud {
- if chatConfig.AppID == "" {
- return nil, fmt.Errorf("WeKnoraCloud provider: AppID is required")
- }
- if chatConfig.AppSecret == "" {
- return nil, fmt.Errorf("WeKnoraCloud provider: AppSecret is required")
- }
- }
-
- return &RemoteAPIChat{
- modelName: modelName,
- client: openai.NewClientWithConfig(config),
- modelID: chatConfig.ModelID,
- baseURL: strings.TrimRight(config.BaseURL, "/"),
- apiKey: apiKey,
- provider: providerName,
- appID: chatConfig.AppID,
- appSecret: chatConfig.AppSecret,
- customHeaders: chatConfig.CustomHeaders,
- adapter: resolveProvider(providerName, modelName),
- thinkingOverride: parseThinkingOverride(chatConfig.ExtraConfig),
- }, nil
-}
-
-// authCreds bundles the credentials passed to the adapter's Auth method.
-func (c *RemoteAPIChat) authCreds() authCreds {
- return authCreds{APIKey: c.apiKey, AppID: c.appID, AppSecret: c.appSecret}
-}
-
-// shapedRequest builds the standard request and applies the adapter's message
-// transform and parameter shaping (but not thinking, which may wrap the body).
-func (c *RemoteAPIChat) shapedRequest(messages []Message, opts *ChatOptions, isStream bool) openai.ChatCompletionRequest {
- req := c.BuildChatCompletionRequest(messages, opts, isStream)
- req.Messages = c.adapter.TransformMessages(req.Messages)
- c.adapter.ShapeRequest(&req, opts, isStream)
- return req
-}
-
-// buildOutbound assembles the final outbound request: the body to send, the
-// endpoint override (empty for the standard endpoint), and whether the raw HTTP
-// path is required. This is the single place that composes adapter + thinking,
-// replacing the former buildRequestCustomizer plumbing.
-func (c *RemoteAPIChat) buildOutbound(
- ctx context.Context, messages []Message, opts *ChatOptions, isStream bool,
-) (body any, endpoint string, useRawHTTP bool, err error) {
- req := c.shapedRequest(messages, opts, isStream)
-
- thinking := c.thinkingOverride
- if thinking == nil {
- thinking = c.adapter.Thinking()
- }
- customBody, useRaw := thinking.Apply(&req, opts, isStream)
-
- body = &req
- if customBody != nil {
- body = customBody
- }
- body, err = c.shapeProviderRequest(body, req, messages)
- if err != nil {
- return nil, "", false, err
- }
-
- retention := resolveCacheRetention(opts)
- policy := promptCachePolicyFor(c.provider, c.baseURL)
- sessionID := promptCacheSessionID(ctx, opts)
- cachedBody, forceRaw, err := applyPromptCacheToJSONBody(body, policy, sessionID, retention)
- if err != nil {
- return nil, "", false, err
- }
- body = cachedBody
-
- endpoint = c.adapter.Endpoint(c.baseURL, c.modelID, isStream)
- useRawHTTP = useRaw || c.adapter.ForceRawHTTP() || endpoint != "" || forceRaw
- return body, endpoint, useRawHTTP, nil
-}
-
-// logRequest 记录请求日志
-func (c *RemoteAPIChat) logRequest(ctx context.Context, req any, isStream bool) {
- if jsonData, err := json.MarshalIndent(req, "", " "); err == nil {
- logger.Infof(ctx, "[LLM Request] model=%s, stream=%v, request:\n%s",
- c.modelName, isStream, secutils.CompactImageDataURLForLog(string(jsonData)))
- }
-}
-
-// Chat 进行非流式聊天
-func (c *RemoteAPIChat) Chat(ctx context.Context, messages []Message, opts *ChatOptions) (*types.ChatResponse, error) {
- // 仅在调用方未设置 deadline 时附加一个兜底超时,防止 hung 请求永久阻塞 worker;
- // 调用方若显式设置了更短或更长的 deadline,都会被原样尊重。
- timeoutCtx, cancel := withLLMTimeout(ctx, defaultChatTimeout)
- defer cancel()
-
- body, endpoint, useRawHTTP, err := c.buildOutbound(timeoutCtx, messages, opts, false)
- if err != nil {
- return nil, err
- }
- if useRawHTTP {
- return c.chatWithRawHTTP(timeoutCtx, endpoint, body, opts)
- }
-
- req := *(body.(*openai.ChatCompletionRequest))
- c.logRequest(timeoutCtx, req, false)
- resp, err := c.client.CreateChatCompletion(timeoutCtx, req)
- if err != nil {
- if isMultimodalNotSupportedError(err) {
- logger.Warnf(timeoutCtx, "[LLM Request] Model %s does not support multimodal, retrying without images", c.modelName)
- cleaned := stripImagesFromMessages(messages)
- req = c.shapedRequest(cleaned, opts, false)
- resp, err = c.client.CreateChatCompletion(timeoutCtx, req)
- }
- if err != nil {
- return nil, fmt.Errorf("create chat completion: %w", err)
- }
- }
-
- result, err := c.parseCompletionResponse(&resp)
- if err != nil {
- return nil, err
- }
- logUsage(timeoutCtx, c.modelName, &result.Usage)
- return result, nil
-}
-
-// chatWithRawHTTP 使用原始 HTTP 请求进行聊天(供自定义请求使用)
-func (c *RemoteAPIChat) chatWithRawHTTP(ctx context.Context, endpoint string, customReq any, opts *ChatOptions) (*types.ChatResponse, error) {
- jsonData, err := json.Marshal(customReq)
- if err != nil {
- return nil, fmt.Errorf("marshal request: %w", err)
- }
-
- if endpoint == "" {
- endpoint = c.baseURL + "/chat/completions"
- }
- if err := secutils.ValidateURLForSSRF(endpoint); err != nil {
- return nil, fmt.Errorf("endpoint SSRF check failed: %w", err)
- }
- logger.Infof(ctx, "[LLM Request] Remote HTTP, endpoint=%s, model=%s, raw HTTP request:\n%s",
- endpoint, c.modelName, secutils.CompactImageDataURLForLog(string(jsonData)))
-
- httpReq, err := http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewBuffer(jsonData))
- if err != nil {
- return nil, fmt.Errorf("create request: %w", err)
- }
-
- httpReq.Header.Set("Content-Type", "application/json")
- c.adapter.Auth(httpReq, c.authCreds(), jsonData)
-
- // 注入用户自定义 header(保留头会在工具内部自动跳过)
- secutils.ApplyCustomHeaders(httpReq, c.customHeaders)
- attachPromptCacheHeaders(httpReq, promptCachePolicyFor(c.provider, c.baseURL), promptCacheSessionID(ctx, opts))
-
- logger.Infof(ctx, "[LLM Request] Remote HTTP, endpoint=%s, model=%s",
- endpoint, c.modelName)
-
- resp, err := rawHTTPClient.Do(httpReq)
- if err != nil {
- return nil, fmt.Errorf("send request: %w", err)
- }
- defer resp.Body.Close()
-
- if resp.StatusCode != http.StatusOK {
- body, _ := io.ReadAll(resp.Body)
- return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, string(body))
- }
-
- body, err := io.ReadAll(resp.Body)
- if err != nil {
- return nil, fmt.Errorf("read response: %w", err)
- }
-
- var chatResp openai.ChatCompletionResponse
- if err := json.Unmarshal(body, &chatResp); err != nil {
- return nil, fmt.Errorf("decode response: %w", err)
- }
-
- result, err := c.parseCompletionResponse(&chatResp)
- if err != nil {
- return nil, err
- }
- c.applyCompletionToolCallMetadata(body, result)
- applyRawPromptCacheUsage(body, &result.Usage)
- logUsage(ctx, c.modelName, &result.Usage)
- return result, nil
-}
-
-// ChatStream 进行流式聊天
-func (c *RemoteAPIChat) ChatStream(ctx context.Context, messages []Message, opts *ChatOptions) (<-chan types.StreamResponse, error) {
- // 仅在调用方未设置 deadline 时附加兜底超时;流式调用默认超时更长,
- // 因为带思考/推理的模型可能数十秒甚至几分钟才产出首 token。
- timeoutCtx, cancel := withLLMTimeout(ctx, defaultStreamTimeout)
-
- body, endpoint, useRawHTTP, err := c.buildOutbound(timeoutCtx, messages, opts, true)
- if err != nil {
- cancel()
- return nil, err
- }
- if useRawHTTP {
- ch, err := c.chatStreamWithRawHTTP(timeoutCtx, endpoint, body, opts)
- return wrapStreamCancel(ch, err, cancel)
- }
-
- req := *(body.(*openai.ChatCompletionRequest))
- c.logRequest(timeoutCtx, req, true)
-
- streamDumper := newStreamPacketDumper(c.modelName, &req)
- if streamDumper != nil {
- logger.Infof(timeoutCtx, "[LLM Stream Raw Dump] writing packets to %s", streamDumper.Path())
- }
-
- streamChan := make(chan types.StreamResponse)
-
- stream, err := c.client.CreateChatCompletionStream(timeoutCtx, req)
- if err != nil {
- if isMultimodalNotSupportedError(err) {
- logger.Warnf(timeoutCtx, "[LLM Stream] Model %s does not support multimodal, retrying without images", c.modelName)
- cleaned := stripImagesFromMessages(messages)
- req = c.shapedRequest(cleaned, opts, true)
- stream, err = c.client.CreateChatCompletionStream(timeoutCtx, req)
- }
- if err != nil {
- cancel()
- close(streamChan)
- return nil, fmt.Errorf("create chat completion stream: %w", err)
- }
- }
-
- go func() {
- defer cancel()
- if streamDumper != nil {
- defer streamDumper.Close()
- }
- c.processStream(timeoutCtx, stream, streamChan, streamDumper)
- }()
-
- return streamChan, nil
-}
-
-// wrapStreamCancel 在子 channel 关闭后执行 cancel,避免 timeout context 泄漏。
-// 当底层调用直接返回 error 时,立即调用 cancel 并将 error 透出。
-func wrapStreamCancel(in <-chan types.StreamResponse, err error, cancel context.CancelFunc) (<-chan types.StreamResponse, error) {
- if err != nil {
- cancel()
- return nil, err
- }
- out := make(chan types.StreamResponse)
- go func() {
- defer cancel()
- defer close(out)
- for v := range in {
- out <- v
- }
- }()
- return out, nil
-}
-
-// chatStreamWithRawHTTP 使用原始 HTTP 请求进行流式聊天
-func (c *RemoteAPIChat) chatStreamWithRawHTTP(ctx context.Context, endpoint string, customReq any, opts *ChatOptions) (<-chan types.StreamResponse, error) {
- jsonData, err := json.Marshal(customReq)
- if err != nil {
- return nil, fmt.Errorf("marshal request: %w", err)
- }
-
- if endpoint == "" {
- endpoint = c.baseURL + "/chat/completions"
- }
- if err := secutils.ValidateURLForSSRF(endpoint); err != nil {
- return nil, fmt.Errorf("endpoint SSRF check failed: %w", err)
- }
-
- if prettyJSON, pErr := json.MarshalIndent(customReq, "", " "); pErr == nil {
- logger.Infof(ctx, "[LLM Stream Request] endpoint=%s, model=%s, stream=true, request:\n%s",
- endpoint, c.modelName, secutils.CompactImageDataURLForLog(string(prettyJSON)))
- } else {
- logger.Infof(ctx, "[LLM Stream] endpoint=%s, model=%s", endpoint, c.modelName)
- }
- httpReq, err := http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewBuffer(jsonData))
- if err != nil {
- return nil, fmt.Errorf("create request: %w", err)
- }
-
- httpReq.Header.Set("Content-Type", "application/json")
- c.adapter.Auth(httpReq, c.authCreds(), jsonData)
- httpReq.Header.Set("Accept", "text/event-stream")
-
- // 注入用户自定义 header(保留头会在工具内部自动跳过)
- secutils.ApplyCustomHeaders(httpReq, c.customHeaders)
- attachPromptCacheHeaders(httpReq, promptCachePolicyFor(c.provider, c.baseURL), promptCacheSessionID(ctx, opts))
-
- resp, err := rawHTTPClient.Do(httpReq)
- if err != nil {
- return nil, fmt.Errorf("send request: %w", err)
- }
-
- if resp.StatusCode != http.StatusOK {
- body, _ := io.ReadAll(resp.Body)
- resp.Body.Close()
- return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, string(body))
- }
-
- streamChan := make(chan types.StreamResponse)
- streamDumper := newStreamPacketDumper(c.modelName, customReq)
- if streamDumper != nil {
- logger.Infof(ctx, "[LLM Stream Raw Dump] writing packets to %s", streamDumper.Path())
- }
-
- go func() {
- if streamDumper != nil {
- defer streamDumper.Close()
- }
- c.processRawHTTPStream(ctx, resp, streamChan, streamDumper)
- }()
-
- return streamChan, nil
-}
-
-// GetModelName 获取模型名称
-func (c *RemoteAPIChat) GetModelName() string {
- return c.modelName
-}
-
-// GetModelID 获取模型ID
-func (c *RemoteAPIChat) GetModelID() string {
- return c.modelID
-}
-
-// GetProvider 获取 provider 名称
-func (c *RemoteAPIChat) GetProvider() provider.ProviderName {
- return c.provider
-}
-
-// GetBaseURL 获取 baseURL
-func (c *RemoteAPIChat) GetBaseURL() string {
- return c.baseURL
-}
-
-// GetAPIKey 获取 apiKey
-func (c *RemoteAPIChat) GetAPIKey() string {
- return c.apiKey
-}
diff --git a/internal/models/chat/remote_api_test.go b/internal/models/chat/remote_api_test.go
deleted file mode 100644
index a34e43be1..000000000
--- a/internal/models/chat/remote_api_test.go
+++ /dev/null
@@ -1,550 +0,0 @@
-package chat
-
-import (
- "context"
- "encoding/json"
- "os"
- "testing"
- "time"
-
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/sashabaranov/go-openai"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-func newTestRemoteChat(t *testing.T) *RemoteAPIChat {
- t.Helper()
-
- chat, err := NewRemoteAPIChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: "",
- ModelName: "test-model",
- APIKey: "test-key",
- ModelID: "test-model",
- })
- require.NoError(t, err)
- return chat
-}
-
-func TestBuildChatCompletionRequest_ParallelToolCalls(t *testing.T) {
- chat := newTestRemoteChat(t)
- messages := []Message{{Role: "user", Content: "hello"}}
-
- t.Run("nil ParallelToolCalls leaves default", func(t *testing.T) {
- opts := &ChatOptions{Temperature: 0.7}
- req := chat.BuildChatCompletionRequest(messages, opts, false)
- assert.Nil(t, req.ParallelToolCalls, "should be nil when not set")
- })
-
- t.Run("ParallelToolCalls true is propagated", func(t *testing.T) {
- ptc := true
- opts := &ChatOptions{
- Temperature: 0.7,
- ParallelToolCalls: &ptc,
- Tools: []Tool{{
- Type: "function",
- Function: FunctionDef{
- Name: "mcp_weather_getforecast",
- Description: "Get weather",
- Parameters: json.RawMessage(`{"type":"object"}`),
- },
- }},
- }
- req := chat.BuildChatCompletionRequest(messages, opts, true)
- assert.NotNil(t, req.ParallelToolCalls)
-
- val, ok := req.ParallelToolCalls.(bool)
- if ok {
- assert.Equal(t, true, val)
- } else {
- assert.Equal(t, true, req.ParallelToolCalls)
- }
-
- assert.Len(t, req.Tools, 1)
- assert.Equal(t, "mcp_weather_getforecast", req.Tools[0].Function.Name)
- })
-
- t.Run("ParallelToolCalls false is propagated", func(t *testing.T) {
- ptc := false
- opts := &ChatOptions{
- Temperature: 0.7,
- ParallelToolCalls: &ptc,
- }
- req := chat.BuildChatCompletionRequest(messages, opts, false)
- assert.NotNil(t, req.ParallelToolCalls)
-
- val, ok := req.ParallelToolCalls.(bool)
- if ok {
- assert.Equal(t, false, val)
- } else {
- assert.Equal(t, false, req.ParallelToolCalls)
- }
- })
-}
-
-func TestBuildChatCompletionRequest_MCPToolsFormat(t *testing.T) {
- chat := newTestRemoteChat(t)
- messages := []Message{{Role: "user", Content: "查询乙醇的理化性质"}}
-
- mcpTools := []Tool{
- {
- Type: "function",
- Function: FunctionDef{
- Name: "mcp_hazardous_chemicals_gethazardouschemicals",
- Description: "[MCP Service: hazardous_chemicals (external)] Get hazardous chemicals list",
- Parameters: json.RawMessage(`{"type":"object","properties":{}}`),
- },
- },
- {
- Type: "function",
- Function: FunctionDef{
- Name: "mcp_hazardous_chemicals_gethazardouschemicalbybizid",
- Description: "[MCP Service: hazardous_chemicals (external)] Get hazardous chemical by biz ID",
- Parameters: json.RawMessage(`{"type":"object","properties":{"bizId":{"type":"string"}},"required":["bizId"]}`),
- },
- },
- }
-
- ptc := true
- opts := &ChatOptions{
- Temperature: 0.7,
- Tools: mcpTools,
- ParallelToolCalls: &ptc,
- }
-
- req := chat.BuildChatCompletionRequest(messages, opts, true)
-
- assert.Len(t, req.Tools, 2)
- assert.Equal(t, "mcp_hazardous_chemicals_gethazardouschemicals", req.Tools[0].Function.Name)
- assert.Equal(t, "mcp_hazardous_chemicals_gethazardouschemicalbybizid", req.Tools[1].Function.Name)
- assert.Equal(t, true, req.ParallelToolCalls)
- assert.True(t, req.Stream)
-
- for _, tool := range req.Tools {
- name := tool.Function.Name
- assert.NotContains(t, name, "ed606721", "tool name must use service name, not UUID")
- assert.Regexp(t, `^[a-zA-Z0-9_-]+$`, name, "tool name must match OpenAI pattern")
- assert.LessOrEqual(t, len(name), 64, "tool name must be <= 64 chars")
- }
-}
-
-// TestBuildChatCompletionRequest_GPT5MaxCompletionTokens 验证 GPT-5 / o-series
-// 模型的 MaxTokens 自动迁移到 MaxCompletionTokens,且采样参数被剔除。
-// 见 issue #1283:Azure OpenAI 的 gpt-5 系列模型不再支持 max_tokens 字段。
-func TestBuildChatCompletionRequest_GPT5MaxCompletionTokens(t *testing.T) {
- build := func(t *testing.T, providerName, modelName string) *RemoteAPIChat {
- t.Helper()
- c, err := NewRemoteAPIChat(&ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: "https://example.openai.azure.com",
- ModelName: modelName,
- APIKey: "test-key",
- ModelID: modelName,
- Provider: providerName,
- ExtraConfig: map[string]string{
- "api_version": "2025-04-01-preview",
- },
- })
- require.NoError(t, err)
- return c
- }
-
- messages := []Message{{Role: "user", Content: "test"}}
-
- cases := []struct {
- name string
- provider string
- model string
- shouldRewriteMaxT bool
- }{
- {"AzureOpenAI gpt-5.2", "azure_openai", "gpt-5.2", true},
- {"AzureOpenAI gpt-5-mini", "azure_openai", "gpt-5-mini", true},
- {"OpenAI gpt-5", "openai", "gpt-5", true},
- {"OpenAI o1-mini", "openai", "o1-mini", true},
- {"OpenAI o3", "openai", "o3", true},
- {"OpenAI o4-mini", "openai", "o4-mini", true},
- {"OpenAI gpt-4o (unchanged)", "openai", "gpt-4o", false},
- {"AzureOpenAI gpt-4 (unchanged)", "azure_openai", "gpt-4", false},
- }
-
- for _, tc := range cases {
- t.Run(tc.name, func(t *testing.T) {
- c := build(t, tc.provider, tc.model)
- opts := &ChatOptions{
- Temperature: 0.7,
- TopP: 0.9,
- MaxTokens: 128,
- FrequencyPenalty: 0.1,
- PresencePenalty: 0.2,
- }
- req := c.shapedRequest(messages, opts, false)
-
- if tc.shouldRewriteMaxT {
- assert.Equal(t, 0, req.MaxTokens, "MaxTokens must NOT be sent for GPT-5/o-series")
- assert.Equal(t, 128, req.MaxCompletionTokens, "MaxCompletionTokens should be populated from MaxTokens")
- assert.EqualValues(t, 0, req.Temperature, "temperature must be omitted")
- assert.EqualValues(t, 0, req.TopP, "top_p must be omitted")
- assert.EqualValues(t, 0, req.FrequencyPenalty, "frequency_penalty must be omitted")
- assert.EqualValues(t, 0, req.PresencePenalty, "presence_penalty must be omitted")
- } else {
- assert.Zero(t, req.MaxTokens, "non-reasoning OpenAI/Azure send max_completion_tokens only")
- assert.Equal(t, 128, req.MaxCompletionTokens)
- assert.InDelta(t, 0.7, req.Temperature, 1e-6)
- }
- })
- }
-
- t.Run("MaxCompletionTokens takes precedence over MaxTokens", func(t *testing.T) {
- c := build(t, "openai", "gpt-5.2")
- opts := &ChatOptions{
- MaxTokens: 128,
- MaxCompletionTokens: 2048,
- }
- req := c.shapedRequest(messages, opts, false)
- assert.Equal(t, 0, req.MaxTokens)
- assert.Equal(t, 2048, req.MaxCompletionTokens)
- })
-}
-
-func TestBuildChatCompletionRequest_ToolChoice(t *testing.T) {
- chat := newTestRemoteChat(t)
- messages := []Message{{Role: "user", Content: "test"}}
-
- t.Run("auto tool choice", func(t *testing.T) {
- opts := &ChatOptions{ToolChoice: "auto"}
- req := chat.BuildChatCompletionRequest(messages, opts, false)
- assert.Equal(t, "auto", req.ToolChoice)
- })
-
- t.Run("specific tool choice", func(t *testing.T) {
- opts := &ChatOptions{ToolChoice: "mcp_svc_tool"}
- req := chat.BuildChatCompletionRequest(messages, opts, false)
- assert.NotNil(t, req.ToolChoice)
- })
-}
-
-// TestConvertMessages_ReasoningContentRoundTrip verifies that assistant
-// reasoning_content is propagated through ConvertMessages so that providers
-// like MiMo / DeepSeek thinking-mode can read it back from prior turns.
-// See issue #1302: MiMo rejects multi-turn requests with HTTP 400
-// "The reasoning_content in the thinking mode must be passed back to the API."
-// when this field is dropped.
-func TestConvertMessages_ReasoningContentRoundTrip(t *testing.T) {
- c := newTestRemoteChat(t)
-
- t.Run("assistant reasoning_content propagated", func(t *testing.T) {
- messages := []Message{
- {Role: "user", Content: "hi"},
- {
- Role: "assistant",
- Content: "the answer",
- ReasoningContent: "let me think about this carefully",
- },
- {Role: "user", Content: "follow-up"},
- }
- out := c.ConvertMessages(messages)
- require.Len(t, out, 3)
- assert.Equal(t, "let me think about this carefully", out[1].ReasoningContent,
- "assistant reasoning_content must be retained for multi-turn replay")
- assert.Empty(t, out[0].ReasoningContent, "user message must not carry reasoning_content")
- assert.Empty(t, out[2].ReasoningContent, "user message must not carry reasoning_content")
- })
-
- t.Run("non-assistant role drops reasoning_content even if set", func(t *testing.T) {
- messages := []Message{
- {Role: "user", Content: "hi", ReasoningContent: "should be dropped"},
- }
- out := c.ConvertMessages(messages)
- require.Len(t, out, 1)
- assert.Empty(t, out[0].ReasoningContent, "non-assistant roles must never carry reasoning_content upstream")
- })
-
- t.Run("empty assistant reasoning_content stays empty", func(t *testing.T) {
- messages := []Message{
- {Role: "assistant", Content: "no thinking"},
- }
- out := c.ConvertMessages(messages)
- require.Len(t, out, 1)
- assert.Empty(t, out[0].ReasoningContent)
- })
-}
-
-func TestApplyCompletionToolCallMetadata(t *testing.T) {
- c := newTestRemoteChat(t)
- c.adapter = geminiProvider{}
-
- resp := &types.ChatResponse{
- ToolCalls: []types.LLMToolCall{{
- ID: "call_1",
- Type: "function",
- Function: types.FunctionCall{
- Name: "wiki_search",
- Arguments: `{"query":"MACS"}`,
- },
- }},
- }
- body := []byte(`{
- "choices":[{
- "message":{
- "tool_calls":[{
- "id":"call_1",
- "type":"function",
- "function":{"name":"wiki_search","arguments":"{\"query\":\"MACS\"}"},
- "extra_content":{"google":{"thought_signature":"sig-from-gemini"}}
- }]
- }
- }]
- }`)
-
- c.applyCompletionToolCallMetadata(body, resp)
- require.Len(t, resp.ToolCalls, 1)
- assert.JSONEq(t, `{"thought_signature":"sig-from-gemini"}`,
- string(resp.ToolCalls[0].ProviderMetadata["google"]))
-}
-
-func TestApplyStreamToolCallMetadata(t *testing.T) {
- c := newTestRemoteChat(t)
- c.adapter = geminiProvider{}
- state := newStreamState()
-
- body := []byte(`{
- "choices":[{
- "delta":{
- "tool_calls":[{
- "index":0,
- "id":"call_1",
- "type":"function",
- "function":{"name":"wiki_search","arguments":"{\"query\":\"MACS\"}"},
- "extra_content":{"google":{"thought_signature":"stream-sig-from-gemini"}}
- }]
- }
- }]
- }`)
-
- c.applyStreamToolCallMetadata(body, state)
- toolCalls := state.buildOrderedToolCalls()
- require.Len(t, toolCalls, 1)
- assert.JSONEq(t, `{"thought_signature":"stream-sig-from-gemini"}`,
- string(toolCalls[0].ProviderMetadata["google"]))
-}
-
-// TestRemoteAPIChat 综合测试 Remote API Chat 的所有功能
-func TestRemoteAPIChat(t *testing.T) {
- // 获取环境变量
- deepseekAPIKey := os.Getenv("DEEPSEEK_API_KEY")
- aliyunAPIKey := os.Getenv("ALIYUN_API_KEY")
-
- // 定义测试配置
- testConfigs := []struct {
- name string
- apiKey string
- config *ChatConfig
- skipMsg string
- }{
- {
- name: "DeepSeek API",
- apiKey: deepseekAPIKey,
- config: &ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: "https://api.deepseek.com/v1",
- ModelName: "deepseek-chat",
- APIKey: deepseekAPIKey,
- ModelID: "deepseek-chat",
- },
- skipMsg: "DEEPSEEK_API_KEY environment variable not set",
- },
- {
- name: "Aliyun DeepSeek",
- apiKey: aliyunAPIKey,
- config: &ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
- ModelName: "deepseek-v3.1",
- APIKey: aliyunAPIKey,
- ModelID: "deepseek-v3.1",
- },
- skipMsg: "ALIYUN_API_KEY environment variable not set",
- },
- {
- name: "Aliyun Qwen3-32b",
- apiKey: aliyunAPIKey,
- config: &ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
- ModelName: "qwen3-32b",
- APIKey: aliyunAPIKey,
- ModelID: "qwen3-32b",
- },
- skipMsg: "ALIYUN_API_KEY environment variable not set",
- },
- {
- name: "Aliyun Qwen-max",
- apiKey: aliyunAPIKey,
- config: &ChatConfig{
- Source: types.ModelSourceRemote,
- BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
- ModelName: "qwen-max",
- APIKey: aliyunAPIKey,
- ModelID: "qwen-max",
- },
- skipMsg: "ALIYUN_API_KEY environment variable not set",
- },
- }
-
- // 测试消息
- testMessages := []Message{
- {
- Role: "user",
- Content: "test",
- },
- }
-
- // 测试选项
- testOptions := &ChatOptions{
- Temperature: 0.7,
- MaxTokens: 100,
- }
-
- // 创建上下文
- ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
- defer cancel()
-
- // 遍历所有配置进行测试
- for _, tc := range testConfigs {
- t.Run(tc.name, func(t *testing.T) {
- // 检查 API Key
- if tc.apiKey == "" {
- t.Skip(tc.skipMsg)
- }
-
- // 创建聊天实例
- chat, err := NewRemoteAPIChat(tc.config)
- require.NoError(t, err)
- assert.Equal(t, tc.config.ModelName, chat.GetModelName())
- assert.Equal(t, tc.config.ModelID, chat.GetModelID())
-
- // 测试基本聊天功能
- t.Run("Basic Chat", func(t *testing.T) {
- response, err := chat.Chat(ctx, testMessages, testOptions)
- require.NoError(t, err)
- require.NotNil(t, response, "response should not be nil")
- assert.NotEmpty(t, response.Content)
- assert.Greater(t, response.Usage.TotalTokens, 0)
- assert.Greater(t, response.Usage.PromptTokens, 0)
- assert.Greater(t, response.Usage.CompletionTokens, 0)
-
- t.Logf("%s Response: %s", tc.name, response.Content)
- t.Logf("Usage: Prompt=%d, Completion=%d, Total=%d",
- response.Usage.PromptTokens,
- response.Usage.CompletionTokens,
- response.Usage.TotalTokens)
- })
- })
- }
-}
-
-// TestCachedTokensHelper covers the nil-safety contract of the cachedTokens
-// helper. Some providers omit PromptTokensDetails entirely; the helper must
-// return zero rather than panic.
-func TestCachedTokensHelper(t *testing.T) {
- assert.Equal(t, 0, cachedTokens(nil), "nil details must return zero")
- assert.Equal(t, 0, cachedTokens(&openai.PromptTokensDetails{}),
- "empty details must return zero")
- assert.Equal(t, 1234, cachedTokens(&openai.PromptTokensDetails{CachedTokens: 1234}),
- "populated cached_tokens must round-trip")
-}
-
-// TestParseCompletionResponse_CachedTokens verifies that
-// prompt_tokens_details.cached_tokens from an OpenAI-compatible response is
-// propagated into TokenUsage.CachedTokens. This is the field Qwen explicit
-// caching populates on a cache hit.
-func TestParseCompletionResponse_CachedTokens(t *testing.T) {
- c := newTestRemoteChat(t)
-
- t.Run("cached_tokens populated from prompt_tokens_details", func(t *testing.T) {
- resp := &openai.ChatCompletionResponse{
- Choices: []openai.ChatCompletionChoice{
- {
- Message: openai.ChatCompletionMessage{Role: "assistant", Content: "hi"},
- FinishReason: openai.FinishReasonStop,
- },
- },
- Usage: openai.Usage{
- PromptTokens: 6929,
- CompletionTokens: 42,
- TotalTokens: 6971,
- PromptTokensDetails: &openai.PromptTokensDetails{
- CachedTokens: 6900,
- },
- },
- }
-
- got, err := c.parseCompletionResponse(resp)
- require.NoError(t, err)
- require.NotNil(t, got)
- assert.Equal(t, 6929, got.Usage.PromptTokens)
- assert.Equal(t, 42, got.Usage.CompletionTokens)
- assert.Equal(t, 6971, got.Usage.TotalTokens)
- assert.Equal(t, 6900, got.Usage.CachedTokens,
- "cached_tokens must mirror prompt_tokens_details.cached_tokens")
- assert.Equal(t, 6900, got.Usage.CacheReadTokens)
- assert.Equal(t, 29, got.Usage.CacheMissTokens)
- assert.True(t, got.Usage.CacheReported)
- assert.Equal(t, types.PromptCacheStatusHit, got.Usage.CacheStatus)
- })
-
- t.Run("missing prompt_tokens_details yields zero cached_tokens", func(t *testing.T) {
- resp := &openai.ChatCompletionResponse{
- Choices: []openai.ChatCompletionChoice{
- {
- Message: openai.ChatCompletionMessage{Role: "assistant", Content: "hi"},
- FinishReason: openai.FinishReasonStop,
- },
- },
- Usage: openai.Usage{
- PromptTokens: 100,
- CompletionTokens: 10,
- TotalTokens: 110,
- // PromptTokensDetails intentionally nil — providers like Ollama
- // and older OpenAI-compat backends omit this block entirely.
- },
- }
-
- got, err := c.parseCompletionResponse(resp)
- require.NoError(t, err)
- require.NotNil(t, got)
- assert.Equal(t, 0, got.Usage.CachedTokens,
- "missing details must surface as zero, not panic")
- assert.False(t, got.Usage.CacheReported)
- assert.Equal(t, types.PromptCacheStatusUnsupported, got.Usage.CacheStatus)
- })
-}
-
-func TestApplyRawPromptCacheUsage_DeepSeekNativeFields(t *testing.T) {
- usage := types.TokenUsage{PromptTokens: 4096, CompletionTokens: 10, TotalTokens: 4106}
- applyRawPromptCacheUsage([]byte(`{"usage":{"prompt_tokens":4096,"prompt_cache_hit_tokens":3072,"prompt_cache_miss_tokens":1024}}`), &usage)
- assert.Equal(t, 3072, usage.CacheReadTokens)
- assert.Equal(t, 1024, usage.CacheMissTokens)
- assert.True(t, usage.CacheReported)
- assert.Equal(t, types.PromptCacheStatusHit, usage.CacheStatus)
-}
-
-// TestTokenUsage_CachedTokensJSONOmitempty ensures the new CachedTokens field
-// stays out of serialized payloads when it is zero. This keeps logs and API
-// responses unchanged for providers that never report cache hits.
-func TestTokenUsage_CachedTokensJSONOmitempty(t *testing.T) {
- t.Run("zero is omitted", func(t *testing.T) {
- u := types.TokenUsage{PromptTokens: 10, CompletionTokens: 5, TotalTokens: 15}
- b, err := json.Marshal(u)
- require.NoError(t, err)
- assert.NotContains(t, string(b), "cached_tokens")
- })
-
- t.Run("non-zero is emitted", func(t *testing.T) {
- u := types.TokenUsage{PromptTokens: 10, CompletionTokens: 5, TotalTokens: 15, CachedTokens: 7}
- b, err := json.Marshal(u)
- require.NoError(t, err)
- assert.Contains(t, string(b), `"cached_tokens":7`)
- })
-}
diff --git a/internal/models/chat/thinking.go b/internal/models/chat/thinking.go
deleted file mode 100644
index 23e92372f..000000000
--- a/internal/models/chat/thinking.go
+++ /dev/null
@@ -1,172 +0,0 @@
-package chat
-
-import (
- "strings"
-
- "github.com/Tencent/WeKnora/internal/models/provider"
- "github.com/sashabaranov/go-openai"
-)
-
-// ExtraConfigThinkingControl is the model parameters.extra_config key for
-// selecting how ChatOptions.Thinking is translated to provider HTTP fields.
-// The accepted values mirror the strings the frontend writes (see
-// ModelEditorDialog.vue): "none", "enable_thinking", "thinking_type",
-// "chat_template_kwargs".
-const ExtraConfigThinkingControl = "thinking_control"
-
-// Wire-format request bodies used by providers that express extended-thinking
-// through a non-standard top-level field. They embed the standard OpenAI
-// request so all other fields are marshalled unchanged.
-
-// QwenChatCompletionRequest adds Aliyun Qwen's `enable_thinking` boolean.
-type QwenChatCompletionRequest struct {
- openai.ChatCompletionRequest
- EnableThinking *bool `json:"enable_thinking,omitempty"`
-}
-
-// ThinkingConfig is the `{ "type": "enabled"|"disabled" }` block used by
-// LKEAP / Volcengine style providers.
-type ThinkingConfig struct {
- Type string `json:"type"`
-}
-
-// ThinkingChatCompletionRequest adds the `thinking` object for providers that
-// use the `{ "thinking": { "type": ... } }` wire format.
-type ThinkingChatCompletionRequest struct {
- openai.ChatCompletionRequest
- Thinking *ThinkingConfig `json:"thinking,omitempty"`
-}
-
-// ThinkingStrategy encodes how ChatOptions.Thinking is mapped onto a provider's
-// HTTP request. Apply returns (customBody, useRawHTTP):
-// - (nil, false) means "send the standard OpenAI request unchanged" (the
-// caller keeps using the SDK path).
-// - a non-nil customBody must be sent verbatim over raw HTTP because it
-// carries fields the OpenAI SDK would strip.
-//
-// When opts.Thinking is nil most strategies emit nothing, deferring to the
-// model's own default; the exception is enableThinking{alwaysSend: true}
-// (Aliyun Qwen), which must always pin the field.
-type ThinkingStrategy interface {
- Apply(req *openai.ChatCompletionRequest, opts *ChatOptions, isStream bool) (customBody any, useRawHTTP bool)
-}
-
-// noThinking sends no thinking-related fields at all.
-type noThinking struct{}
-
-func (noThinking) Apply(*openai.ChatCompletionRequest, *ChatOptions, bool) (any, bool) {
- return nil, false
-}
-
-// enableThinking encodes thinking via Qwen's `enable_thinking` boolean.
-//
-// - alwaysSend: pin the field even when opts.Thinking is nil (Aliyun Qwen
-// thinking models require it on every request; default value is false).
-// - disableOnNonStream: force enable_thinking=false for non-stream requests
-// (Qwen3 rejects thinking in non-stream mode).
-type enableThinking struct {
- alwaysSend bool
- disableOnNonStream bool
-}
-
-func (s enableThinking) Apply(req *openai.ChatCompletionRequest, opts *ChatOptions, isStream bool) (any, bool) {
- thinking := false
- switch {
- case opts != nil && opts.Thinking != nil:
- thinking = *opts.Thinking
- case !s.alwaysSend:
- return nil, false
- }
- if s.disableOnNonStream && !isStream {
- thinking = false
- }
- qwenReq := QwenChatCompletionRequest{ChatCompletionRequest: *req}
- qwenReq.EnableThinking = &thinking
- return qwenReq, true
-}
-
-// thinkingTypeField encodes thinking via the `{ "thinking": { "type": ... } }`
-// object (LKEAP / Volcengine). Emits nothing when opts.Thinking is unset.
-type thinkingTypeField struct{}
-
-func (thinkingTypeField) Apply(req *openai.ChatCompletionRequest, opts *ChatOptions, _ bool) (any, bool) {
- if opts == nil || opts.Thinking == nil {
- return nil, false
- }
- r := ThinkingChatCompletionRequest{ChatCompletionRequest: *req}
- thinkingType := "disabled"
- if *opts.Thinking {
- thinkingType = "enabled"
- }
- r.Thinking = &ThinkingConfig{Type: thinkingType}
- return r, true
-}
-
-// chatTemplateKwargs encodes thinking via the standard request's
-// `chat_template_kwargs.enable_thinking` (vLLM / NVIDIA / generic local
-// deployments). Emits nothing when opts.Thinking is unset.
-type chatTemplateKwargs struct{}
-
-func (chatTemplateKwargs) Apply(req *openai.ChatCompletionRequest, opts *ChatOptions, _ bool) (any, bool) {
- if opts == nil || opts.Thinking == nil {
- return nil, false
- }
- req.ChatTemplateKwargs = map[string]interface{}{
- "enable_thinking": *opts.Thinking,
- }
- return req, true
-}
-
-// parseThinkingOverride reads extra_config.thinking_control and returns the
-// strategy it selects, or nil when unset (the provider adapter's default
-// strategy then applies). An unrecognized non-empty value falls back to
-// chat_template_kwargs, preserving the legacy default-mode behavior.
-func parseThinkingOverride(extraConfig map[string]string) ThinkingStrategy {
- if extraConfig == nil {
- return nil
- }
- switch strings.ToLower(strings.TrimSpace(extraConfig[ExtraConfigThinkingControl])) {
- case "":
- return nil
- case "none":
- return noThinking{}
- case "enable_thinking":
- return enableThinking{}
- case "thinking_type":
- return thinkingTypeField{}
- default:
- // "chat_template_kwargs" and any unknown non-empty value.
- return chatTemplateKwargs{}
- }
-}
-
-// EffectiveThinkingControl reports the provider field that will carry
-// ChatOptions.Thinking. It intentionally shares the same adapter/override
-// resolution as the real request path so diagnostics do not guess from the
-// frontend selection.
-func EffectiveThinkingControl(config *ChatConfig) string {
- if config == nil {
- return "none"
- }
- if override := parseThinkingOverride(config.ExtraConfig); override != nil {
- return thinkingStrategyName(override)
- }
- providerName := provider.ProviderName(config.Provider)
- if providerName == "" {
- providerName = provider.DetectProvider(config.BaseURL)
- }
- return thinkingStrategyName(resolveProvider(providerName, config.ModelName).Thinking())
-}
-
-func thinkingStrategyName(strategy ThinkingStrategy) string {
- switch strategy.(type) {
- case enableThinking:
- return "enable_thinking"
- case thinkingTypeField:
- return "thinking_type"
- case chatTemplateKwargs:
- return "chat_template_kwargs"
- default:
- return "none"
- }
-}
diff --git a/internal/models/chat/thinking_test.go b/internal/models/chat/thinking_test.go
deleted file mode 100644
index 139969978..000000000
--- a/internal/models/chat/thinking_test.go
+++ /dev/null
@@ -1,144 +0,0 @@
-package chat
-
-import (
- "encoding/json"
- "testing"
-
- "github.com/sashabaranov/go-openai"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-func ptrBool(b bool) *bool { return &b }
-
-// TestThinkingStrategy_NilThinking verifies the strategies that defer to the
-// model default emit nothing when ChatOptions.Thinking is unset.
-func TestThinkingStrategy_NilThinking(t *testing.T) {
- req := openai.ChatCompletionRequest{Model: "test"}
- strategies := []ThinkingStrategy{
- noThinking{},
- enableThinking{}, // not alwaysSend
- thinkingTypeField{},
- chatTemplateKwargs{},
- }
- for _, s := range strategies {
- custom, raw := s.Apply(&req, nil, true)
- assert.Nil(t, custom, "%T", s)
- assert.False(t, raw, "%T", s)
- }
-}
-
-// TestEnableThinking_QwenSemantics pins the Aliyun Qwen behavior: thinking is
-// always sent, defaults to false, and is forced off on non-stream requests.
-func TestEnableThinking_QwenSemantics(t *testing.T) {
- s := enableThinking{alwaysSend: true, disableOnNonStream: true}
- req := openai.ChatCompletionRequest{Model: "qwen3-32b"}
-
- t.Run("non-stream forces false even when requested true", func(t *testing.T) {
- custom, raw := s.Apply(&req, &ChatOptions{Thinking: ptrBool(true)}, false)
- require.True(t, raw)
- qwen, ok := custom.(QwenChatCompletionRequest)
- require.True(t, ok)
- require.NotNil(t, qwen.EnableThinking)
- assert.False(t, *qwen.EnableThinking)
- })
-
- t.Run("stream honors requested true", func(t *testing.T) {
- custom, raw := s.Apply(&req, &ChatOptions{Thinking: ptrBool(true)}, true)
- require.True(t, raw)
- qwen := custom.(QwenChatCompletionRequest)
- require.NotNil(t, qwen.EnableThinking)
- assert.True(t, *qwen.EnableThinking)
- })
-
- t.Run("stream defaults to false when unset", func(t *testing.T) {
- custom, raw := s.Apply(&req, nil, true)
- require.True(t, raw)
- qwen := custom.(QwenChatCompletionRequest)
- require.NotNil(t, qwen.EnableThinking)
- assert.False(t, *qwen.EnableThinking)
- })
-}
-
-// TestEnableThinking_ExtraConfigSemantics pins the extra_config "enable_thinking"
-// override: only sent when explicitly requested.
-func TestEnableThinking_ExtraConfigSemantics(t *testing.T) {
- s := enableThinking{}
- req := openai.ChatCompletionRequest{Model: "qwen3"}
-
- custom, raw := s.Apply(&req, &ChatOptions{Thinking: ptrBool(true)}, true)
- require.True(t, raw)
- qwen := custom.(QwenChatCompletionRequest)
- require.NotNil(t, qwen.EnableThinking)
- assert.True(t, *qwen.EnableThinking)
-
- custom, raw = s.Apply(&req, nil, true)
- assert.Nil(t, custom)
- assert.False(t, raw)
-}
-
-func TestThinkingTypeField(t *testing.T) {
- s := thinkingTypeField{}
- req := openai.ChatCompletionRequest{Model: "ds-v3"}
-
- custom, raw := s.Apply(&req, &ChatOptions{Thinking: ptrBool(false)}, true)
- require.True(t, raw)
- typed, ok := custom.(ThinkingChatCompletionRequest)
- require.True(t, ok)
- require.NotNil(t, typed.Thinking)
- assert.Equal(t, "disabled", typed.Thinking.Type)
-
- custom, raw = s.Apply(&req, &ChatOptions{Thinking: ptrBool(true)}, true)
- require.True(t, raw)
- assert.Equal(t, "enabled", custom.(ThinkingChatCompletionRequest).Thinking.Type)
-}
-
-func TestChatTemplateKwargs(t *testing.T) {
- s := chatTemplateKwargs{}
- req := openai.ChatCompletionRequest{Model: "vllm"}
-
- custom, raw := s.Apply(&req, &ChatOptions{Thinking: ptrBool(true)}, true)
- require.True(t, raw)
- out, ok := custom.(*openai.ChatCompletionRequest)
- require.True(t, ok)
- assert.Equal(t, true, out.ChatTemplateKwargs["enable_thinking"])
-
- body, err := json.Marshal(custom)
- require.NoError(t, err)
- assert.Contains(t, string(body), "chat_template_kwargs")
-}
-
-func TestParseThinkingOverride(t *testing.T) {
- cases := map[string]ThinkingStrategy{
- "none": noThinking{},
- "enable_thinking": enableThinking{},
- "thinking_type": thinkingTypeField{},
- "chat_template_kwargs": chatTemplateKwargs{},
- "something-unknown": chatTemplateKwargs{}, // legacy default-mode fallback
- }
- for value, want := range cases {
- got := parseThinkingOverride(map[string]string{ExtraConfigThinkingControl: value})
- assert.IsType(t, want, got, "value=%q", value)
- }
-
- assert.Nil(t, parseThinkingOverride(nil))
- assert.Nil(t, parseThinkingOverride(map[string]string{}))
- assert.Nil(t, parseThinkingOverride(map[string]string{ExtraConfigThinkingControl: ""}))
-}
-
-func TestEffectiveThinkingControl(t *testing.T) {
- assert.Equal(t, "enable_thinking", EffectiveThinkingControl(&ChatConfig{
- Provider: "aliyun",
- ModelName: "qwen3-32b",
- }))
- assert.Equal(t, "chat_template_kwargs", EffectiveThinkingControl(&ChatConfig{
- Provider: "generic",
- ModelName: "qwen3",
- ExtraConfig: map[string]string{ExtraConfigThinkingControl: "chat_template_kwargs"},
- }))
- assert.Equal(t, "none", EffectiveThinkingControl(&ChatConfig{
- Provider: "generic",
- ModelName: "qwen3",
- ExtraConfig: map[string]string{ExtraConfigThinkingControl: "none"},
- }))
-}
diff --git a/internal/models/embedding/azure_openai.go b/internal/models/embedding/azure_openai.go
index 1ee59175d..328ea8faa 100644
--- a/internal/models/embedding/azure_openai.go
+++ b/internal/models/embedding/azure_openai.go
@@ -7,21 +7,30 @@ import (
"fmt"
"io"
"net/http"
+ "net/url"
+ "strings"
"time"
"github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/models/provider"
+ "github.com/Tencent/WeKnora/internal/types"
secutils "github.com/Tencent/WeKnora/internal/utils"
)
// AzureOpenAIEmbedder implements text vectorization using Azure OpenAI API
type AzureOpenAIEmbedder struct {
- apiKey string
- baseURL string
- modelName string
- truncatePromptTokens int
- dimensions int
- modelID string
+ apiKey string
+ baseURL string
+ modelName string
+ truncatePromptTokens int
+ dimensions int
+ modelID string
+ // apiVersion is the stored extra_config.api_version, empty for the v1
+ // GA data plane. It only selects requestURL; see azureEmbeddingURL.
apiVersion string
+ requestURL string
httpClient *http.Client
maxRetries int
customHeaders map[string]string
@@ -56,9 +65,6 @@ func NewAzureOpenAIEmbedder(apiKey, baseURL, modelName string,
if modelName == "" {
return nil, fmt.Errorf("deployment name (model name) is required")
}
- if apiVersion == "" {
- apiVersion = "2024-10-21"
- }
if truncatePromptTokens == 0 {
truncatePromptTokens = 511
}
@@ -75,12 +81,51 @@ func NewAzureOpenAIEmbedder(apiKey, baseURL, modelName string,
dimensions: dimensions,
modelID: modelID,
apiVersion: apiVersion,
+ requestURL: azureEmbeddingURL(baseURL, modelName, apiVersion),
httpClient: newEmbeddingHTTPClient(60 * time.Second),
maxRetries: 3,
EmbedderPooler: pooler,
}, nil
}
+// azureEmbeddingURL resolves the embeddings URL through the catalog's Azure
+// vendor, so one stored row lands on the same data plane for embedding as it
+// does for chat and VLM (which both go through catalog.Vendor.Endpoint via
+// internal/models/chat): an empty api_version means the v1 GA path
+// {base}/openai/v1/embeddings with the deployment name in the body's `model`
+// field, and a non-empty one means the dated
+// {base}/openai/deployments/{deployment}/embeddings?api-version=... path.
+// See the package comment of internal/models/vendors/azure_openai for the
+// documentation behind that rule.
+//
+// The literal fallback below only runs if the vendor package was not linked
+// in; embedder.go blank-imports internal/models/vendors so it normally is.
+func azureEmbeddingURL(baseURL, deployment, apiVersion string) string {
+ root := strings.TrimRight(strings.TrimSpace(baseURL), "/")
+ extra := map[string]string{}
+ version := strings.TrimSpace(apiVersion)
+ if version != "" {
+ extra[catalog.ExtraAPIVersion] = version
+ }
+ if vendor, ok := catalog.Get(string(provider.ProviderAzureOpenAI)); ok && vendor.Endpoint != nil {
+ target, query := vendor.Endpoint(catalog.EndpointRequest{
+ BaseURL: root,
+ Model: deployment,
+ ModelType: types.ModelTypeEmbedding,
+ API: api.APIOpenAICompletions,
+ Extra: extra,
+ })
+ if target != "" {
+ return api.Endpoint{URL: target, Query: query}.Resolve("")
+ }
+ }
+ if version != "" {
+ return root + "/openai/deployments/" + url.PathEscape(deployment) +
+ "/embeddings?api-version=" + version
+ }
+ return root + "/openai/v1/embeddings"
+}
+
func (e *AzureOpenAIEmbedder) Embed(ctx context.Context, text string) ([]float32, error) {
for range 3 {
embeddings, err := e.BatchEmbed(ctx, []string{text})
@@ -146,9 +191,6 @@ func (e *AzureOpenAIEmbedder) BatchEmbed(ctx context.Context, texts []string) ([
}
func (e *AzureOpenAIEmbedder) doRequestWithRetry(ctx context.Context, jsonData []byte) (*http.Response, error) {
- url := fmt.Sprintf("%s/openai/deployments/%s/embeddings?api-version=%s",
- e.baseURL, e.modelName, e.apiVersion)
-
var resp *http.Response
var err error
@@ -165,7 +207,7 @@ func (e *AzureOpenAIEmbedder) doRequestWithRetry(ctx context.Context, jsonData [
}
}
- req, reqErr := http.NewRequestWithContext(ctx, "POST", url, bytes.NewReader(jsonData))
+ req, reqErr := http.NewRequestWithContext(ctx, "POST", e.requestURL, bytes.NewReader(jsonData))
if reqErr != nil {
err = reqErr
continue
diff --git a/internal/models/embedding/azure_openai_test.go b/internal/models/embedding/azure_openai_test.go
index b81110eff..f84a698cf 100644
--- a/internal/models/embedding/azure_openai_test.go
+++ b/internal/models/embedding/azure_openai_test.go
@@ -7,6 +7,10 @@ import (
"io"
"net/http"
"testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
)
func TestAzureOpenAIEmbedderBatchEmbedSendsConfiguredDimensions(t *testing.T) {
@@ -149,6 +153,112 @@ func TestAzureOpenAIEmbedderBatchEmbedSendsDimensionsWhenOverrideEnabledRegardle
}
}
+// TestAzureOpenAIEmbedderURLFollowsAPIVersionRule pins the one rule a stored
+// Azure row picks its data plane by, the same rule the catalog's Endpoint
+// hook applies to that row's chat and VLM clients: an empty api_version means
+// the v1 GA path with the deployment name in the body, a non-empty one means
+// the dated deployments path. Before the catalog, embedding hard-defaulted to
+// 2024-10-21 here and put one row on two different data planes.
+func TestAzureOpenAIEmbedderURLFollowsAPIVersionRule(t *testing.T) {
+ t.Parallel()
+
+ const (
+ baseURL = "https://example-resource.openai.azure.com"
+ deployment = "text-embedding-3-large-deployment"
+ )
+
+ for _, tc := range []struct {
+ name string
+ apiVersion string
+ wantURL string
+ }{
+ {
+ name: "row without api_version uses the v1 GA data plane",
+ apiVersion: "",
+ wantURL: baseURL + "/openai/v1/embeddings",
+ },
+ {
+ name: "row with the legacy GA api_version keeps the deployments path",
+ apiVersion: "2024-10-21",
+ wantURL: baseURL + "/openai/deployments/" + deployment +
+ "/embeddings?api-version=2024-10-21",
+ },
+ {
+ name: "row with a preview api_version keeps the deployments path",
+ apiVersion: "2025-04-01-preview",
+ wantURL: baseURL + "/openai/deployments/" + deployment +
+ "/embeddings?api-version=2025-04-01-preview",
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ var gotURL string
+ var requestBody map[string]any
+ transport := roundTripFunc(func(r *http.Request) (*http.Response, error) {
+ gotURL = r.URL.String()
+ if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+ t.Errorf("decode request body: %v", err)
+ }
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Header: make(http.Header),
+ Body: io.NopCloser(bytes.NewBufferString(
+ `{"data":[{"embedding":[0.1,0.2],"index":0}]}`)),
+ }, nil
+ })
+
+ embedder, err := NewAzureOpenAIEmbedder("test-key", baseURL, deployment,
+ 511, 256, "text-embedding-3-large", tc.apiVersion, nil)
+ if err != nil {
+ t.Fatalf("create embedder: %v", err)
+ }
+ embedder.httpClient = &http.Client{Transport: transport}
+
+ if _, err := embedder.BatchEmbed(context.Background(), []string{"hello"}); err != nil {
+ t.Fatalf("BatchEmbed returned error: %v", err)
+ }
+ if gotURL != tc.wantURL {
+ t.Fatalf("request URL = %q, want %q", gotURL, tc.wantURL)
+ }
+ // Both shapes carry the deployment name in the body; the v1
+ // path has nowhere else to put it.
+ if requestBody["model"] != deployment {
+ t.Fatalf("request body model = %v, want %q", requestBody["model"], deployment)
+ }
+ })
+ }
+}
+
+// TestAzureEmbeddingURLMatchesVendorHook pins that the embedding URL is the
+// vendor hook's answer and not a second, parallel implementation of the rule.
+func TestAzureEmbeddingURLMatchesVendorHook(t *testing.T) {
+ t.Parallel()
+
+ vendor, ok := catalog.Get("azure_openai")
+ if !ok {
+ t.Fatal("azure_openai vendor is not registered")
+ }
+ for _, version := range []string{"", "2024-10-21"} {
+ extra := map[string]string{}
+ if version != "" {
+ extra[catalog.ExtraAPIVersion] = version
+ }
+ target, query := vendor.Endpoint(catalog.EndpointRequest{
+ BaseURL: "https://example-resource.openai.azure.com",
+ Model: "embed deploy",
+ ModelType: types.ModelTypeEmbedding,
+ API: api.APIOpenAICompletions,
+ Extra: extra,
+ })
+ want := api.Endpoint{URL: target, Query: query}.Resolve("")
+ got := azureEmbeddingURL("https://example-resource.openai.azure.com/", "embed deploy", version)
+ if got != want {
+ t.Fatalf("azureEmbeddingURL(api_version=%q) = %q, want the hook's %q", version, got, want)
+ }
+ }
+}
+
type roundTripFunc func(*http.Request) (*http.Response, error)
func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
diff --git a/internal/models/embedding/embedder.go b/internal/models/embedding/embedder.go
index 8f40f79f2..2c5434996 100644
--- a/internal/models/embedding/embedder.go
+++ b/internal/models/embedding/embedder.go
@@ -8,6 +8,12 @@ import (
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/provider"
"github.com/Tencent/WeKnora/internal/models/utils/ollama"
+ // provider.DetectProvider answers from the vendor catalog, which is empty
+ // until the vendor packages have run their init. Without this import every
+ // URL detects as "generic" and the per-vendor embedders below are never
+ // selected — silently, and only in builds that do not already link the
+ // container (leaf tests, future tools).
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
"github.com/Tencent/WeKnora/internal/tracing/langfuse"
"github.com/Tencent/WeKnora/internal/types"
)
@@ -200,11 +206,13 @@ func newEmbedder(config Config, pooler EmbedderPooler, ollamaService *ollama.Oll
embedder, err = jinaEmb, jErr
return embedder, err
case provider.ProviderAzureOpenAI:
- apiVersion := "2024-10-21"
+ // No default: an empty api_version means the v1 GA data
+ // plane, exactly as it does for this row's chat and VLM
+ // clients. Filling in a dated version here would put the
+ // same stored row on two different data planes.
+ var apiVersion string
if config.ExtraConfig != nil {
- if v, ok := config.ExtraConfig["api_version"]; ok {
- apiVersion = v
- }
+ apiVersion = config.ExtraConfig["api_version"]
}
azureEmb, azErr := NewAzureOpenAIEmbedder(config.APIKey,
config.BaseURL,
diff --git a/internal/models/embedding/provider_detection_test.go b/internal/models/embedding/provider_detection_test.go
new file mode 100644
index 000000000..682a09ca9
--- /dev/null
+++ b/internal/models/embedding/provider_detection_test.go
@@ -0,0 +1,31 @@
+package embedding
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/provider"
+)
+
+// TestDetectProviderSeesVendorCatalog guards the blank import of
+// internal/models/vendors in embedder.go.
+//
+// provider.DetectProvider is a thin wrapper over catalog.DetectByURL, which
+// returns "generic" for every URL while the catalog is empty. Without the
+// vendor packages linked in, a stored embedding row that carries no explicit
+// provider id falls through newEmbedder's switch to the plain OpenAI-compatible
+// embedder: an Azure row loses its api-version/deployment URL, an Aliyun
+// multimodal row loses the DashScope endpoint, and both fail at call time.
+func TestDetectProviderSeesVendorCatalog(t *testing.T) {
+ cases := map[string]provider.ProviderName{
+ "https://my-resource.openai.azure.com": provider.ProviderAzureOpenAI,
+ "https://dashscope.aliyuncs.com/compatible-mode/v1": provider.ProviderAliyun,
+ "https://open.bigmodel.cn/api/paas/v4": provider.ProviderZhipu,
+ "https://api.jina.ai/v1": provider.ProviderJina,
+ "https://self-hosted-gateway.example.internal/v1": provider.ProviderGeneric,
+ }
+ for baseURL, want := range cases {
+ if got := provider.DetectProvider(baseURL); got != want {
+ t.Errorf("DetectProvider(%q) = %q, want %q", baseURL, got, want)
+ }
+ }
+}
diff --git a/internal/models/embedding/volcengine.go b/internal/models/embedding/volcengine.go
index f0917168f..59ca449be 100644
--- a/internal/models/embedding/volcengine.go
+++ b/internal/models/embedding/volcengine.go
@@ -256,7 +256,6 @@ func (e *VolcengineEmbedder) BatchEmbed(ctx context.Context, texts []string) ([]
}
return embeddings, nil
-
}
// GetModelName returns the model name
diff --git a/internal/models/parity/parity_test.go b/internal/models/parity/parity_test.go
new file mode 100644
index 000000000..fc1f74206
--- /dev/null
+++ b/internal/models/parity/parity_test.go
@@ -0,0 +1,751 @@
+// Package parity holds the cross-cutting safety net for the vendor catalog:
+//
+// - TestLegacyWireParity pins the outbound request shape against the
+// behaviour of the pre-catalog implementation (the providerAdapter /
+// ThinkingStrategy / wireCompletionTokenField tables that lived in
+// internal/models/chat before the refactor). Every deliberate divergence
+// is listed explicitly with the reason, so an accidental one fails here.
+// - TestLegacyProviderDetection pins DetectProvider's URL table.
+// - TestCatalogInvariants and TestEveryChatModelRequestShape are
+// data-driven: they walk every registered vendor and every catalog model,
+// so a newly added vendor or model is covered without touching this file.
+//
+// The tests drive the real stack: chat.NewRemoteChat resolves the catalog and
+// returns the protocol client, and the body asserted here is exactly what
+// would go on the wire.
+package parity
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
+ "github.com/Tencent/WeKnora/internal/types"
+ secutils "github.com/Tencent/WeKnora/internal/utils"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// TestMain whitelists the loopback host: several vendors ship a placeholder
+// default URL (self-hosted runtimes) or a templated one (Azure), which the
+// SSRF guard rejects before any request is built. Those cases are re-pointed
+// at 127.0.0.1 by reachableBaseURL.
+func TestMain(m *testing.M) {
+ secutils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ defer secutils.ResetSSRFWhitelistForTest()
+ os.Exit(m.Run())
+}
+
+// reachableBaseURL replaces a placeholder or templated vendor URL with a
+// loopback one so the SSRF guard lets the request through. The protocol and
+// compat resolution under test do not depend on the host.
+func reachableBaseURL(url string) string {
+ if url == "" {
+ return ""
+ }
+ if strings.Contains(url, "your_") || strings.Contains(url, "{") {
+ return "http://127.0.0.1:9/v1"
+ }
+ return url
+}
+
+// bodyBuilder is implemented by every protocol client; it returns the exact
+// JSON object the client would send.
+type bodyBuilder interface {
+ BuildRequestBody(messages []api.Message, opts *api.Options, stream bool) (map[string]any, error)
+}
+
+func ptrBool(b bool) *bool { return &b }
+
+var userTurn = []api.Message{{Role: "user", Content: "hi"}}
+
+// buildBody runs the production path: ChatConfig -> catalog.Resolve ->
+// protocol client -> request body, then round-trips through JSON so the
+// assertions see the real wire types.
+func buildBody(t *testing.T, cfg *chat.ChatConfig, opts *api.Options, stream bool) map[string]any {
+ t.Helper()
+ if cfg.Source == "" {
+ cfg.Source = types.ModelSourceRemote
+ }
+ if cfg.APIKey == "" {
+ cfg.APIKey = "k"
+ }
+ cfg.BaseURL = reachableBaseURL(cfg.BaseURL)
+ client, err := chat.NewRemoteChat(cfg)
+ require.NoError(t, err, "NewRemoteChat(%s/%s)", cfg.Provider, cfg.ModelName)
+ builder, ok := client.(bodyBuilder)
+ require.True(t, ok, "%s/%s: protocol client does not expose BuildRequestBody", cfg.Provider, cfg.ModelName)
+ body, err := builder.BuildRequestBody(userTurn, opts, stream)
+ require.NoError(t, err)
+ raw, err := json.Marshal(body)
+ require.NoError(t, err)
+ var out map[string]any
+ require.NoError(t, json.Unmarshal(raw, &out))
+ return out
+}
+
+func resolve(t *testing.T, provider, model string) *catalog.Resolved {
+ t.Helper()
+ r, err := catalog.Resolve(catalog.Ref{Provider: provider, Model: model})
+ require.NoError(t, err)
+ return r
+}
+
+// TestLegacyWireParity compares today's wire body with the pre-refactor
+// behaviour, case by case.
+//
+// `want` lists fields that must match the old implementation; a nil value
+// means the field must be absent, exactly as before. `divergence` documents
+// a deliberate behaviour change — those entries assert the NEW behaviour and
+// carry the reason, so the change stays visible in review.
+func TestLegacyWireParity(t *testing.T) {
+ cases := []struct {
+ name string
+ provider string
+ model string
+ baseURL string
+ extra map[string]string
+ opts *api.Options
+ stream bool
+ want map[string]any
+ divergence string
+ }{
+ // ---- completion budget field (old wireCompletionTokenField table) ----
+ {
+ name: "deepseek keeps max_tokens", provider: "deepseek", model: "deepseek-v4-pro",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "zhipu keeps max_tokens", provider: "zhipu", model: "glm-4.7",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "siliconflow keeps max_tokens", provider: "siliconflow", model: "deepseek-ai/DeepSeek-V4-Pro",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "moonshot moved to max_completion_tokens", provider: "moonshot", model: "kimi-k2.6",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_tokens": nil},
+ divergence: "the old table sent max_tokens. platform.kimi.com now documents " +
+ "max_completion_tokens as the field and max_tokens as deprecated, so the vendor " +
+ "audit switched it; both are still accepted upstream.",
+ },
+ // The six vendors below moved the other way: the old table left them
+ // on the default max_completion_tokens and the audit put them on
+ // max_tokens. Each entry carries the documentation that decided it, so
+ // a later flip back is a visible change rather than a silent one.
+ {
+ name: "hunyuan moved to max_tokens", provider: "hunyuan", model: "hunyuan-turbos-latest",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "the OpenAI-compatible reference documents only max_tokens (default 4096); " +
+ "max_completion_tokens appears nowhere in it.",
+ },
+ {
+ name: "modelscope moved to max_tokens", provider: "modelscope", model: "ZhipuAI/GLM-4.6",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "ModelScope API-Inference documents no output-cap parameter at all. " +
+ "max_tokens is carried over from the DashScope/Bailian channel behind it and is " +
+ "marked unverified in the vendor package, so this case pins a guess, not a fact.",
+ },
+ {
+ name: "qiniu moved to max_tokens", provider: "qiniu", model: "qwen3.5-397b-a17b",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "max_completion_tokens is not in the Qiniu reference.",
+ },
+ {
+ name: "longcat moved to max_tokens", provider: "longcat", model: "LongCat-2.0",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "max_completion_tokens is not part of the LongCat reference; max_tokens " +
+ "defaults to and tops out at the model's 131072 output budget.",
+ },
+ {
+ name: "requesty moved to max_tokens", provider: "requesty", model: "anthropic/claude-opus-5",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "max_completion_tokens appears nowhere in Requesty's documentation.",
+ },
+ {
+ name: "novita moved to max_tokens", provider: "novita", model: "moonshotai/kimi-k3",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "Novita documents max_tokens as required and never mentions " +
+ "max_completion_tokens.",
+ },
+ // NVIDIA is the one vendor whose output-cap field is per model, so the
+ // vendor-level case above ("nvidia keeps max_tokens", an uncatalogued
+ // deployment) does not cover these two.
+ {
+ name: "nvidia kimi-k3 overrides the vendor default", provider: "nvidia", model: "moonshotai/kimi-k3",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_tokens": nil},
+ divergence: "NVIDIA's own curl and Python samples use max_tokens, which is why that is " +
+ "the vendor default, but the build.nvidia.com cards for kimi-k3 and " +
+ "gemma-4-31b-it show max_completion_tokens; those two entries override it.",
+ },
+ {
+ name: "nvidia gemma-4 overrides the vendor default",
+ provider: "nvidia", model: "google/gemma-4-31b-it",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_tokens": nil},
+ divergence: "see the kimi-k3 case above; the model card shows max_completion_tokens.",
+ },
+ {
+ name: "nvidia keeps max_tokens", provider: "nvidia", model: "some-nim-model",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "generic keeps max_tokens", provider: "generic", model: "Qwen/Qwen3-32B",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "gpustack keeps max_tokens", provider: "gpustack", model: "qwen3",
+ baseURL: "http://127.0.0.1:9/v1-openai",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "lkeap keeps max_tokens", provider: "lkeap", model: "deepseek-r1-0528",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_tokens": float64(100), "max_completion_tokens": nil},
+ },
+ {
+ name: "volcengine keeps max_completion_tokens", provider: "volcengine", model: "doubao-seed-1-6-251015",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_tokens": nil},
+ },
+ {
+ // Not a divergence: the pre-catalog table left DashScope on the
+ // default too. The audit briefly moved it to max_tokens because
+ // the compatible mode has always accepted that field; it was
+ // moved back because DashScope's parameter table marks
+ // max_tokens 即将废弃 and names max_completion_tokens its
+ // successor, and following a vendor that has announced a
+ // replacement is the cheaper side of the bet.
+ name: "aliyun keeps max_completion_tokens", provider: "aliyun", model: "qwen3-max",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_tokens": nil},
+ },
+ {
+ name: "litellm keeps max_completion_tokens", provider: "litellm", model: "gpt-4o",
+ baseURL: "http://127.0.0.1:9/v1",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_tokens": nil},
+ },
+ {
+ name: "openai reasoning model keeps max_completion_tokens and drops sampling",
+ provider: "openai", model: "gpt-5.5",
+ extra: map[string]string{catalog.ExtraAPI: "openai-completions"},
+ opts: &api.Options{MaxTokens: 100, Temperature: 0.7, TopP: 0.9},
+ want: map[string]any{
+ "max_completion_tokens": float64(100), "max_tokens": nil,
+ "temperature": nil, "top_p": nil,
+ },
+ },
+ {
+ name: "azure reasoning deployment drops sampling", provider: "azure_openai", model: "gpt-5-prod",
+ baseURL: "http://127.0.0.1:9",
+ opts: &api.Options{MaxTokens: 100, Temperature: 0.7},
+ want: map[string]any{"max_completion_tokens": float64(100), "temperature": nil},
+ },
+
+ // ---- thinking encodings (old ThinkingStrategy table) ----
+ {
+ name: "aliyun qwen thinking model always pins enable_thinking, off in non-stream",
+ provider: "aliyun", model: "qwen3-max",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ stream: false,
+ want: map[string]any{"enable_thinking": false},
+ },
+ {
+ name: "aliyun qwen thinking model streams with enable_thinking true",
+ provider: "aliyun", model: "qwen3-max",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ stream: true,
+ want: map[string]any{"enable_thinking": true},
+ },
+ {
+ name: "aliyun sends the switch even without a caller preference",
+ provider: "aliyun", model: "qwen3-max",
+ opts: &api.Options{Temperature: 0.2},
+ want: map[string]any{"enable_thinking": false},
+ },
+ {
+ name: "volcengine uses thinking.type", provider: "volcengine", model: "doubao-seed-1-6-251015",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"thinking": map[string]any{"type": "enabled"}},
+ },
+ {
+ name: "lkeap deepseek v3 uses thinking.type", provider: "lkeap", model: "deepseek-v3.2",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"thinking": map[string]any{"type": "enabled"}},
+ },
+ {
+ name: "lkeap deepseek r1 is always-on so no switch is sent",
+ provider: "lkeap", model: "deepseek-r1",
+ opts: &api.Options{Thinking: ptrBool(false)},
+ want: map[string]any{"thinking": nil, "enable_thinking": nil, "reasoning_effort": nil},
+ },
+ {
+ name: "generic uses chat_template_kwargs", provider: "generic", model: "Qwen/Qwen3-32B",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"chat_template_kwargs": map[string]any{"enable_thinking": true}},
+ },
+ {
+ name: "nvidia uses chat_template_kwargs", provider: "nvidia", model: "some-nim-model",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"chat_template_kwargs": map[string]any{"enable_thinking": true}},
+ },
+ {
+ name: "moonshot v1 pins temperature to 1 and drops other sampling",
+ provider: "moonshot", model: "moonshot-v1-8k",
+ opts: &api.Options{Temperature: 0.2, TopP: 0.9},
+ want: map[string]any{"temperature": 1.0, "top_p": nil},
+ },
+ {
+ // deepseek-chat is catalogued as non-reasoning, so this also pins the
+ // precedence rule: an explicit legacy override outranks that gate.
+ name: "legacy extra_config.thinking_control still overrides the vendor default",
+ provider: "deepseek", model: "deepseek-chat",
+ extra: map[string]string{catalog.ExtraThinkingControl: "chat_template_kwargs"},
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{
+ "chat_template_kwargs": map[string]any{"enable_thinking": true}, "thinking": nil,
+ },
+ },
+ {
+ name: "legacy extra_config.thinking_control=none silences thinking",
+ provider: "volcengine", model: "doubao-seed-1-6-251015",
+ extra: map[string]string{catalog.ExtraThinkingControl: "none"},
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"thinking": nil, "reasoning_effort": nil},
+ },
+ {
+ name: "remote_model_name still overrides the wire model id",
+ provider: "deepseek", model: "deepseek-chat",
+ extra: map[string]string{catalog.ExtraRemoteModelName: "deepseek-v4-pro-internal"},
+ opts: &api.Options{},
+ want: map[string]any{"model": "deepseek-v4-pro-internal"},
+ },
+
+ {
+ name: "a catalogued non-reasoning model never receives thinking fields",
+ provider: "deepseek", model: "deepseek-chat",
+ opts: &api.Options{Thinking: ptrBool(true)},
+ want: map[string]any{"thinking": nil, "reasoning_effort": nil, "enable_thinking": nil},
+ divergence: "DeepSeek's non-thinking alias is marked reasoning:false in the catalog, so " +
+ "Resolve now silences the thinking switch even when the caller asks for it.",
+ },
+
+ // ---- deliberate divergences from the old behaviour ----
+ {
+ name: "deepseek now honours thinking=false instead of ignoring it",
+ provider: "deepseek", model: "deepseek-v4-pro",
+ opts: &api.Options{Thinking: ptrBool(false)},
+ want: map[string]any{"thinking": map[string]any{"type": "disabled"}},
+ divergence: "old code had no thinking strategy for DeepSeek, so an agent with thinking off " +
+ "still got the vendor default (thinking on). The vendor documents thinking.type, so the " +
+ "user's setting is now honoured.",
+ },
+ {
+ name: "zhipu now honours thinking=false", provider: "zhipu", model: "glm-4.7",
+ opts: &api.Options{Thinking: ptrBool(false)},
+ want: map[string]any{"thinking": map[string]any{"type": "disabled"}},
+ divergence: "same as DeepSeek: GLM documents thinking.type and the old code sent nothing.",
+ },
+ {
+ name: "openai first-party now uses the Responses protocol",
+ provider: "openai", model: "gpt-5.5",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_output_tokens": float64(100), "max_completion_tokens": nil},
+ divergence: "api.openai.com now speaks the Responses protocol (reasoning items and encrypted " +
+ "reasoning can be replayed); relays keep Chat Completions.",
+ },
+ {
+ name: "openai through a relay keeps Chat Completions",
+ provider: "openai", model: "gpt-5.5",
+ opts: &api.Options{MaxTokens: 100},
+ want: map[string]any{"max_completion_tokens": float64(100), "max_output_tokens": nil},
+ },
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ cfg := &chat.ChatConfig{
+ Provider: tc.provider, ModelName: tc.model, BaseURL: tc.baseURL, ExtraConfig: tc.extra,
+ }
+ if strings.Contains(tc.name, "through a relay") {
+ cfg.BaseURL = "http://127.0.0.1:9/v1"
+ }
+ body := buildBody(t, cfg, tc.opts, tc.stream)
+ for key, want := range tc.want {
+ got, present := body[key]
+ if want == nil {
+ assert.False(t, present, "field %q must be absent, got %v", key, got)
+ continue
+ }
+ assert.Equal(t, want, got, "field %q", key)
+ }
+ })
+ }
+}
+
+// TestLegacyProviderDetection pins the URL table of the old DetectProvider
+// switch: a stored model row without an explicit provider must still resolve
+// to the same vendor as before.
+func TestLegacyProviderDetection(t *testing.T) {
+ cases := map[string]string{
+ "https://dashscope.aliyuncs.com/compatible-mode/v1": "aliyun",
+ "https://open.bigmodel.cn/api/paas/v4": "zhipu",
+ "https://openrouter.ai/api/v1": "openrouter",
+ "https://router.requesty.ai/v1": "requesty",
+ "https://api.siliconflow.cn/v1": "siliconflow",
+ "https://api.jina.ai/v1": "jina",
+ "https://my-resource.openai.azure.com": "azure_openai",
+ "https://api.openai.com/v1": "openai",
+ "https://api.anthropic.com/v1": "anthropic",
+ "https://api.deepseek.com/v1": "deepseek",
+ "https://generativelanguage.googleapis.com/v1beta": "gemini",
+ "https://ark.cn-beijing.volces.com/api/v3": "volcengine",
+ "https://api.hunyuan.cloud.tencent.com/v1": "hunyuan",
+ "https://api.minimaxi.com/v1": "minimax",
+ "https://api.xiaomimimo.com/v1": "mimo",
+ "https://api-inference.modelscope.cn/v1": "modelscope",
+ "https://api.qnaigc.com/v1": "qiniu",
+ "https://api.moonshot.ai/v1": "moonshot",
+ "https://qianfan.baidubce.com/v2": "qianfan",
+ "https://api.longcat.chat/openai/v1": "longcat",
+ "https://api.lkeap.cloud.tencent.com/v1": "lkeap",
+ "https://integrate.api.nvidia.com/v1": "nvidia",
+ "https://api.novita.ai/openai/v1": "novita",
+ "https://weknora.weixin.qq.com": "weknoracloud",
+ "http://localhost:8000/v1": "generic",
+ "": "generic",
+ }
+ for url, want := range cases {
+ assert.Equal(t, want, catalog.DetectByURL(url), "DetectByURL(%q)", url)
+ }
+}
+
+// TestCatalogInvariants walks every registered vendor and model. It is the
+// net that catches a newly added vendor or model entry that is malformed,
+// contradictory, or unresolvable — without anyone updating this test.
+func TestCatalogInvariants(t *testing.T) {
+ vendors := catalog.List()
+ require.NotEmpty(t, vendors, "no vendors registered")
+ seenID := map[string]bool{}
+
+ for _, v := range vendors {
+ t.Run(v.ID, func(t *testing.T) {
+ assert.False(t, seenID[v.ID], "duplicate vendor id")
+ seenID[v.ID] = true
+ assert.Equal(t, strings.ToLower(v.ID), v.ID, "vendor id must be lowercase")
+ assert.NotEmpty(t, v.Name, "vendor needs a display name")
+ assert.NotEmpty(t, v.Description, "vendor needs a description for the picker")
+ assert.True(t, v.API.Known(), "unknown default API %q", v.API)
+ assert.NotEmpty(t, v.ModelTypes, "vendor supports no model type")
+ assert.True(t, strings.HasPrefix(strings.TrimSpace(string(v.Icon)), "<svg"), "icon must be an SVG")
+ assert.LessOrEqual(t, len(v.Icon), 6*1024, "icon over the 6 KB budget")
+ if v.RequiresAuth {
+ assert.NotEmpty(t, v.Auth, "RequiresAuth without an auth style")
+ }
+ if v.Auth == catalog.AuthSigned {
+ assert.NotNil(t, v.Signer, "signed auth without a Signer hook")
+ }
+
+ for _, field := range v.ExtraFields {
+ assert.NotEmpty(t, field.Key, "extra field without a key")
+ assert.NotEmpty(t, field.Label, "extra field %q without a label", field.Key)
+ assert.Contains(t, []string{"string", "number", "boolean", "select", "password"}, field.Type,
+ "extra field %q has an unsupported type", field.Key)
+ if field.Type == "select" {
+ assert.NotEmpty(t, field.Options, "select field %q without options", field.Key)
+ }
+ }
+
+ // Default URLs must be absolute and only declared for supported types.
+ for mt, url := range v.DefaultBaseURLs {
+ assert.True(t, strings.HasPrefix(url, "http://") || strings.HasPrefix(url, "https://"),
+ "%s default URL %q is not absolute", mt, url)
+ assert.True(t, v.SupportsType(mt), "default URL for unsupported model type %s", mt)
+ }
+
+ ids := map[string]bool{}
+ for _, m := range v.Models {
+ label := m.ID
+ if label == "" {
+ label = "match:" + m.Match
+ }
+ assert.True(t, m.ID != "" || m.Match != "", "model entry needs an id or a match pattern")
+ if m.ID != "" {
+ assert.False(t, ids[strings.ToLower(m.ID)], "duplicate model id %q", m.ID)
+ ids[strings.ToLower(m.ID)] = true
+ }
+ assert.GreaterOrEqual(t, m.ContextWindow, 0, "%s: negative context window", label)
+ assert.GreaterOrEqual(t, m.MaxOutputTokens, 0, "%s: negative max output", label)
+ if m.ContextWindow > 0 && m.MaxOutputTokens > 0 {
+ assert.LessOrEqual(t, m.MaxOutputTokens, m.ContextWindow,
+ "%s: max output exceeds the context window", label)
+ }
+ for _, in := range m.Input {
+ assert.Contains(t, []string{"text", "image", "audio", "video"}, in,
+ "%s: unknown input modality %q", label, in)
+ }
+ for level := range m.ThinkingLevels {
+ _, ok := api.ParseReasoningEffort(string(level))
+ assert.True(t, ok, "%s: unknown thinking level %q", label, level)
+ }
+ if len(m.ThinkingLevels) > 0 {
+ assert.True(t, m.Reasoning, "%s: thinking levels on a non-reasoning model", label)
+ }
+ if m.Cost != nil {
+ assert.GreaterOrEqual(t, m.Cost.Input, 0.0, "%s: negative input cost", label)
+ assert.GreaterOrEqual(t, m.Cost.Output, 0.0, "%s: negative output cost", label)
+ }
+ if m.ID != "" {
+ // Resolve validates the compat object against the model's
+ // protocol: an unknown or misspelled key fails here.
+ _, err := catalog.Resolve(catalog.Ref{Provider: v.ID, Model: m.ID, ModelType: m.Type})
+ assert.NoError(t, err, "%s: does not resolve", label)
+ }
+ }
+ })
+ }
+}
+
+// TestEveryChatModelRequestShape builds a real request for every catalog chat
+// model, with thinking on and off, and asserts the invariants that hold for
+// every vendor. A new model whose compat contradicts itself fails here.
+func TestEveryChatModelRequestShape(t *testing.T) {
+ for _, v := range catalog.List() {
+ if !v.SupportsType(types.ModelTypeKnowledgeQA) {
+ continue
+ }
+ for _, m := range v.ModelsByType(types.ModelTypeKnowledgeQA) {
+ m := m
+ t.Run(v.ID+"/"+m.ID, func(t *testing.T) {
+ resolved := resolve(t, v.ID, m.ID)
+ cfg := &chat.ChatConfig{
+ Provider: v.ID, ModelName: m.ID,
+ BaseURL: reachableBaseURL(v.GetDefaultURL(types.ModelTypeKnowledgeQA)),
+ AppID: "app", AppSecret: "secret", // only used by signing vendors
+ }
+ for _, thinking := range []bool{true, false} {
+ opts := &api.Options{MaxTokens: 256, Temperature: 0.5, Thinking: ptrBool(thinking)}
+ body := buildBody(t, cfg, opts, true)
+
+ _, hasMaxTokens := body["max_tokens"]
+ _, hasMaxCompletion := body["max_completion_tokens"]
+ _, hasMaxOutput := body["max_output_tokens"]
+ _, hasGenerationConfig := body["generationConfig"]
+ budgets := 0
+ for _, present := range []bool{hasMaxTokens, hasMaxCompletion, hasMaxOutput, hasGenerationConfig} {
+ if present {
+ budgets++
+ }
+ }
+ assert.Equal(t, 1, budgets,
+ "thinking=%v: exactly one completion-budget field expected, body=%v", thinking, body)
+
+ if resolved.API != api.APIOpenAICompletions {
+ continue
+ }
+ settings := resolved.OpenAICompletions
+ if !settings.SupportsTemperature {
+ assert.NotContains(t, body, "temperature",
+ "thinking=%v: model rejects sampling parameters", thinking)
+ }
+ if settings.ThinkingFormat == catalog.ThinkingFormatNone {
+ for _, field := range []string{"thinking", "enable_thinking", "reasoning_effort", "reasoning"} {
+ assert.NotContains(t, body, field,
+ "thinking=%v: %s must not be sent when the vendor has no thinking format",
+ thinking, field)
+ }
+ }
+ if !thinking && !resolved.ThinkingLevels.Supports(api.ReasoningOff) {
+ for _, field := range []string{"thinking", "enable_thinking"} {
+ if value, ok := body[field]; ok {
+ assert.NotEqual(t, map[string]any{"type": "disabled"}, value,
+ "always-on model must not be told to disable thinking")
+ assert.NotEqual(t, false, value,
+ "always-on model must not be told to disable thinking")
+ }
+ }
+ }
+ if !settings.SupportsReasoningEffort {
+ assert.NotContains(t, body, "reasoning_effort",
+ "thinking=%v: vendor does not accept reasoning_effort", thinking)
+ }
+ }
+ })
+ }
+ }
+}
+
+// TestWeKnoraCloudTransport pins the two things that vendor needs and no
+// other vendor does: a signed request to a non-standard path, and plain-text
+// content because the endpoint rejects multi-part messages.
+func TestWeKnoraCloudTransport(t *testing.T) {
+ v, ok := catalog.Get("weknoracloud")
+ require.True(t, ok)
+ require.NotNil(t, v.Endpoint, "WeKnora Cloud needs a custom endpoint")
+ url, _ := v.Endpoint(catalog.EndpointRequest{
+ BaseURL: "https://weknora.weixin.qq.com", ModelType: types.ModelTypeKnowledgeQA,
+ })
+ assert.Equal(t, "https://weknora.weixin.qq.com/api/v1/chat/completions", url)
+
+ resolved := resolve(t, "weknoracloud", "any-model")
+ assert.False(t, resolved.OpenAICompletions.SupportsMultiContent,
+ "WeKnora Cloud needs multi-content flattened to text")
+
+ cfg := &chat.ChatConfig{Provider: "weknoracloud", ModelName: "any-model", AppID: "app", AppSecret: "secret"}
+ body := buildBody(t, cfg, &api.Options{}, false)
+ messages, _ := json.Marshal(body["messages"])
+ assert.Contains(t, string(messages), `"content":"hi"`, "content must be a plain string")
+}
+
+// TestGeminiLegacyBaseURLKeepsOpenAIProtocol covers the rows that exist in
+// databases today: Gemini chat models were stored with the OpenAI-compatible
+// base URL, and those must keep speaking that protocol after the switch to
+// native generateContent as the default.
+func TestGeminiLegacyBaseURLKeepsOpenAIProtocol(t *testing.T) {
+ r, err := catalog.Resolve(catalog.Ref{
+ Provider: "gemini", Model: "gemini-2.5-pro",
+ BaseURL: "https://generativelanguage.googleapis.com/v1beta/openai",
+ })
+ require.NoError(t, err)
+ assert.Equal(t, api.APIOpenAICompletions, r.API)
+
+ native := resolve(t, "gemini", "gemini-2.5-pro")
+ assert.Equal(t, api.APIGoogleGenerativeAI, native.API, "new rows use the native protocol")
+}
+
+// TestGeminiCredentialFollowsTheProtocol pins the header each Gemini path
+// authenticates with. The two surfaces document different credentials —
+// x-goog-api-key for native generateContent, Authorization: Bearer for the
+// OpenAI-compatible facade (https://ai.google.dev/gemini-api/docs/openai) —
+// and the auth style is a vendor-wide setting, so without the per-protocol
+// override every row stored before the native protocol became the default
+// would silently change credential: they all carry the /v1beta/openai base
+// URL that the pre-catalog code paired with a bearer token.
+func TestGeminiCredentialFollowsTheProtocol(t *testing.T) {
+ var got http.Header
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ got = r.Header.Clone()
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}],` +
+ `"candidates":[{"content":{"parts":[{"text":"ok"}]}}]}`))
+ }))
+ defer server.Close()
+
+ for _, tc := range []struct {
+ name string
+ baseURL string
+ wantHeader string
+ otherEmpty string
+ }{
+ {
+ name: "openai facade keeps the bearer token", baseURL: server.URL + "/v1beta/openai",
+ wantHeader: "Authorization", otherEmpty: "x-goog-api-key",
+ },
+ {
+ name: "native protocol uses the google api key", baseURL: server.URL + "/v1beta",
+ wantHeader: "x-goog-api-key", otherEmpty: "Authorization",
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ client, err := chat.NewRemoteChat(&chat.ChatConfig{
+ Source: types.ModelSourceRemote, Provider: "gemini",
+ ModelName: "gemini-2.5-pro", BaseURL: tc.baseURL, APIKey: "KEY",
+ })
+ require.NoError(t, err)
+ _, _ = client.Chat(context.Background(), []chat.Message{{Role: "user", Content: "hi"}},
+ &chat.ChatOptions{})
+
+ assert.NotEmpty(t, got.Get(tc.wantHeader), "%s must carry the credential", tc.wantHeader)
+ assert.Empty(t, got.Get(tc.otherEmpty), "%s must not be sent on this protocol", tc.otherEmpty)
+ })
+ }
+}
+
+// TestConcurrentResolve runs the resolution path from many goroutines at
+// once, the way a busy server does: every chat call resolves the catalog
+// before building its request. Registration happens once at init, but the
+// registry map and the per-vendor slices are shared, so a resolver that
+// mutated them would corrupt another request. Run with -race.
+func TestConcurrentResolve(t *testing.T) {
+ vendors := catalog.List()
+ require.NotEmpty(t, vendors)
+
+ const goroutines = 32
+ done := make(chan struct{}, goroutines)
+ for i := 0; i < goroutines; i++ {
+ go func(i int) {
+ defer func() { done <- struct{}{} }()
+ for _, v := range vendors {
+ models := v.ModelsByType(types.ModelTypeKnowledgeQA)
+ name := "unknown-model"
+ if len(models) > 0 {
+ name = models[i%len(models)].ID
+ }
+ r, err := catalog.Resolve(catalog.Ref{Provider: v.ID, Model: name})
+ if err != nil {
+ t.Errorf("resolve %s/%s: %v", v.ID, name, err)
+ return
+ }
+ // Touch the derived views the handlers use.
+ _ = r.Capabilities()
+ _ = r.ThinkingLevels.SupportedLevels()
+ _ = catalog.DetectByURL(r.BaseURL)
+ }
+ }(i)
+ }
+ for i := 0; i < goroutines; i++ {
+ <-done
+ }
+}
+
+// TestEveryCatalogModelDocumentsItsSource pins that each entry can answer
+// "where is this documented".
+//
+// Two things depend on it. The facts in models.json are only auditable if the
+// page they came from is recorded next to them, and the model editor links an
+// operator straight to that page from the picker. models.json may state the
+// URL once at file level for the entries a single page covers, so this also
+// covers MustParseModels pushing it down — before that it was parsed and
+// dropped, and most entries had nothing to link to.
+func TestEveryCatalogModelDocumentsItsSource(t *testing.T) {
+ for _, vendor := range catalog.List() {
+ for _, model := range vendor.Models {
+ name := model.ID
+ if name == "" {
+ name = model.Match
+ }
+ t.Run(vendor.ID+"/"+name, func(t *testing.T) {
+ if model.Source == "" {
+ t.Fatalf("no source: add one to the entry, or a file-level source to models.json")
+ }
+ if !strings.HasPrefix(model.Source, "https://") && !strings.HasPrefix(model.Source, "http://") {
+ t.Errorf("source %q is not a URL the editor can link to", model.Source)
+ }
+ })
+ }
+ }
+}
diff --git a/internal/models/parity/reasoning_vocabulary_test.go b/internal/models/parity/reasoning_vocabulary_test.go
new file mode 100644
index 000000000..027cf6491
--- /dev/null
+++ b/internal/models/parity/reasoning_vocabulary_test.go
@@ -0,0 +1,61 @@
+package parity
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// internal/types cannot import internal/models/api (it would cycle), so
+// types.CustomAgent.EnsureDefaults restates the reasoning-effort
+// vocabulary by hand to derive the legacy Thinking bool. Two copies of a
+// vocabulary drift, and the last time they did the result was a fail-open:
+// an unparseable level meant "unknown, therefore thinking on", which turned
+// a typo into thinking enabled at the provider default with an undefined
+// level sent upstream.
+//
+// This package imports both sides, so it is the one place the two can be
+// compared. It walks every value api.ParseReasoningEffort accepts and
+// asserts EnsureDefaults agrees about whether thinking is on, then asserts
+// that a value that function rejects never enables it.
+func TestReasoningEffortVocabulariesAgree(t *testing.T) {
+ accepted := make([]string, 0, len(api.AllReasoningEfforts)+8)
+ for _, level := range api.AllReasoningEfforts {
+ accepted = append(accepted, string(level))
+ }
+ // The aliases ParseReasoningEffort documents for the legacy boolean UI
+ // and for provider wording.
+ accepted = append(accepted, "none", "false", "disabled", "true", "enabled", "default", "on")
+
+ for _, raw := range accepted {
+ t.Run("accepted/"+raw, func(t *testing.T) {
+ level, ok := api.ParseReasoningEffort(raw)
+ if !ok {
+ t.Fatalf("ParseReasoningEffort rejected %q, which this test lists as accepted", raw)
+ }
+ agent := types.CustomAgent{Config: types.CustomAgentConfig{ReasoningEffort: raw}}
+ agent.EnsureDefaults()
+ cfg := agent.Config
+ if cfg.Thinking == nil {
+ t.Fatalf("EnsureDefaults left Thinking unset for the known level %q", raw)
+ }
+ if got, want := *cfg.Thinking, level.Enabled(); got != want {
+ t.Errorf("EnsureDefaults(%q) derived Thinking=%v, the level means %v", raw, got, want)
+ }
+ })
+ }
+
+ for _, raw := range []string{"hgih", "ultra", "HIGH", " high ", "maximum", "0", "yes"} {
+ t.Run("rejected/"+raw, func(t *testing.T) {
+ if _, ok := api.ParseReasoningEffort(raw); ok {
+ t.Fatalf("ParseReasoningEffort accepted %q; this table assumes it does not", raw)
+ }
+ agent := types.CustomAgent{Config: types.CustomAgentConfig{ReasoningEffort: raw}}
+ agent.EnsureDefaults()
+ if cfg := agent.Config; cfg.Thinking != nil && *cfg.Thinking {
+ t.Errorf("an unparseable level must never enable thinking, %q did", raw)
+ }
+ })
+ }
+}
diff --git a/internal/models/provider/aliyun.go b/internal/models/provider/aliyun.go
deleted file mode 100644
index a6477412b..000000000
--- a/internal/models/provider/aliyun.go
+++ /dev/null
@@ -1,76 +0,0 @@
-package provider
-
-import (
- "fmt"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // AliyunChatBaseURL 阿里云 DashScope Chat/Embedding 的默认 BaseURL
- AliyunChatBaseURL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
- // AliyunRerankBaseURL 阿里云 DashScope Rerank 的默认 BaseURL
- AliyunRerankBaseURL = "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank"
-)
-
-// AliyunProvider 实现阿里云 DashScope 的 Provider 接口
-type AliyunProvider struct{}
-
-func init() {
- Register(&AliyunProvider{})
-}
-
-// Info 返回阿里云 provider 的元数据
-func (p *AliyunProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderAliyun,
- DisplayName: "阿里云 DashScope",
- Description: "qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: AliyunChatBaseURL,
- types.ModelTypeEmbedding: AliyunChatBaseURL,
- types.ModelTypeRerank: AliyunRerankBaseURL,
- types.ModelTypeVLLM: AliyunChatBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证阿里云 provider 配置
-func (p *AliyunProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Aliyun DashScope")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
-
-// IsQwenThinkingModel 检查模型名是否为支持思维链的 Qwen 模型
-// 支持思维链的模型需要特殊处理 enable_thinking 参数
-func IsQwenThinkingModel(modelName string) bool {
- lowerName := strings.ToLower(modelName)
- return strings.HasPrefix(lowerName, "qwen3") ||
- strings.HasPrefix(lowerName, "qwen-plus") ||
- strings.HasPrefix(lowerName, "qwen-max") ||
- strings.HasPrefix(lowerName, "qwen-turbo")
-}
-
-// IsQwen3Model checks whether the model belongs to the Qwen3 family only.
-func IsQwen3Model(modelName string) bool {
- return strings.HasPrefix(strings.ToLower(modelName), "qwen3")
-}
-
-// IsDeepSeekModel 检查模型名是否为 DeepSeek 模型
-// DeepSeek 模型不支持 tool_choice 参数
-func IsDeepSeekModel(modelName string) bool {
- return strings.Contains(strings.ToLower(modelName), "deepseek")
-}
diff --git a/internal/models/provider/anthropic.go b/internal/models/provider/anthropic.go
deleted file mode 100644
index 89590de83..000000000
--- a/internal/models/provider/anthropic.go
+++ /dev/null
@@ -1,41 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const AnthropicBaseURL = "https://api.anthropic.com/v1"
-
-// AnthropicProvider implements native Anthropic Messages API metadata.
-type AnthropicProvider struct{}
-
-func init() {
- Register(&AnthropicProvider{})
-}
-
-func (p *AnthropicProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderAnthropic,
- DisplayName: "Anthropic",
- Description: "Claude models via native Anthropic Messages API",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: AnthropicBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- },
- RequiresAuth: true,
- }
-}
-
-func (p *AnthropicProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Anthropic provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/azure_openai.go b/internal/models/provider/azure_openai.go
deleted file mode 100644
index 43641c4d7..000000000
--- a/internal/models/provider/azure_openai.go
+++ /dev/null
@@ -1,61 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-// AzureOpenAIProvider 实现 Azure OpenAI 的 Provider 接口
-type AzureOpenAIProvider struct{}
-
-func init() {
- Register(&AzureOpenAIProvider{})
-}
-
-// Info 返回 Azure OpenAI provider 的元数据
-func (p *AzureOpenAIProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderAzureOpenAI,
- DisplayName: "Azure OpenAI",
- Description: "gpt-4o, gpt-4, text-embedding-ada-002, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: "https://{resource}.openai.azure.com",
- types.ModelTypeEmbedding: "https://{resource}.openai.azure.com",
- types.ModelTypeRerank: "https://{resource}.openai.azure.com",
- types.ModelTypeVLLM: "https://{resource}.openai.azure.com",
- types.ModelTypeASR: "https://{resource}.openai.azure.com",
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeVLLM,
- types.ModelTypeASR,
- },
- RequiresAuth: true,
- ExtraFields: []ExtraFieldConfig{
- {
- Key: "api_version",
- Label: "API Version",
- Type: "string",
- Required: false,
- Default: "2024-10-21",
- Placeholder: "e.g. 2024-10-21",
- },
- },
- }
-}
-
-// ValidateConfig 验证 Azure OpenAI provider 配置
-func (p *AzureOpenAIProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Azure OpenAI provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("deployment name (model name) is required")
- }
- if config.BaseURL == "" {
- return fmt.Errorf("Azure resource endpoint (base URL) is required")
- }
- return nil
-}
diff --git a/internal/models/provider/deepseek.go b/internal/models/provider/deepseek.go
deleted file mode 100644
index 02057519d..000000000
--- a/internal/models/provider/deepseek.go
+++ /dev/null
@@ -1,46 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // DeepSeekBaseURL DeepSeek 官方 API BaseURL
- DeepSeekBaseURL = "https://api.deepseek.com/v1"
-)
-
-// DeepSeekProvider 实现 DeepSeek 的 Provider 接口
-type DeepSeekProvider struct{}
-
-func init() {
- Register(&DeepSeekProvider{})
-}
-
-// Info 返回 DeepSeek provider 的元数据
-func (p *DeepSeekProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderDeepSeek,
- DisplayName: "DeepSeek",
- Description: "deepseek-chat, deepseek-reasoner, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: DeepSeekBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 DeepSeek provider 配置
-func (p *DeepSeekProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for DeepSeek provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/gemini.go b/internal/models/provider/gemini.go
deleted file mode 100644
index e1dde9ab2..000000000
--- a/internal/models/provider/gemini.go
+++ /dev/null
@@ -1,50 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // GeminiBaseURL Google Gemini API BaseURL
- GeminiBaseURL = "https://generativelanguage.googleapis.com/v1beta"
- // GeminiOpenAICompatBaseURL Gemini OpenAI 兼容模式 BaseURL
- GeminiOpenAICompatBaseURL = "https://generativelanguage.googleapis.com/v1beta/openai"
-)
-
-// GeminiProvider 实现 Google Gemini 的 Provider 接口
-type GeminiProvider struct{}
-
-func init() {
- Register(&GeminiProvider{})
-}
-
-// Info 返回 Gemini provider 的元数据
-func (p *GeminiProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderGemini,
- DisplayName: "Google Gemini",
- Description: "gemini-3-flash-preview, gemini-2.5-pro, gemini-embedding-2, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: GeminiOpenAICompatBaseURL,
- types.ModelTypeEmbedding: GeminiBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 Gemini provider 配置
-func (p *GeminiProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Google Gemini provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/generic.go b/internal/models/provider/generic.go
deleted file mode 100644
index 570e6e93f..000000000
--- a/internal/models/provider/generic.go
+++ /dev/null
@@ -1,43 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-// GenericProvider 实现通用 OpenAI 兼容的 Provider 接口
-type GenericProvider struct{}
-
-func init() {
- Register(&GenericProvider{})
-}
-
-// Info 返回通用 provider 的元数据
-func (p *GenericProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderGeneric,
- DisplayName: "自定义 (OpenAI兼容接口)",
- Description: "Generic API endpoint (OpenAI-compatible)",
- DefaultURLs: map[types.ModelType]string{}, // 需要用户自行配置填写
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- types.ModelTypeASR,
- },
- RequiresAuth: false, // 可能需要也可能不需要
- }
-}
-
-// ValidateConfig 验证通用 provider 配置
-func (p *GenericProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for generic provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/gpustack.go b/internal/models/provider/gpustack.go
deleted file mode 100644
index 20ccf5311..000000000
--- a/internal/models/provider/gpustack.go
+++ /dev/null
@@ -1,59 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // GPUStackBaseURL GPUStack API BaseURL (OpenAI 兼容模式)
- GPUStackBaseURL = "http://your_gpustack_server_url/v1-openai"
- // GPUStackRerankBaseURL GPUStack Rerank API 虽然兼容OpenAI,但路径不同 (/v1/rerank 而非 /v1-openai/rerank)
- GPUStackRerankBaseURL = "http://your_gpustack_server_url/v1"
-)
-
-// GPUStackProvider 实现 GPUStack 的 Provider 接口
-type GPUStackProvider struct{}
-
-func init() {
- Register(&GPUStackProvider{})
-}
-
-// Info 返回 GPUStack provider 的元数据
-func (p *GPUStackProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderGPUStack,
- DisplayName: "GPUStack",
- Description: "Choose your deployed model on GPUStack",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: GPUStackBaseURL,
- types.ModelTypeEmbedding: GPUStackBaseURL,
- types.ModelTypeRerank: GPUStackRerankBaseURL,
- types.ModelTypeVLLM: GPUStackBaseURL,
- types.ModelTypeASR: GPUStackBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- types.ModelTypeASR,
- },
- RequiresAuth: true, // GPUStack 需要 API Key
- }
-}
-
-// ValidateConfig 验证 GPUStack provider 配置
-func (p *GPUStackProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for GPUStack provider")
- }
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for GPUStack provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/hunyuan.go b/internal/models/provider/hunyuan.go
deleted file mode 100644
index 410a2be34..000000000
--- a/internal/models/provider/hunyuan.go
+++ /dev/null
@@ -1,48 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // HunyuanBaseURL 腾讯混元 API BaseURL (OpenAI 兼容模式)
- HunyuanBaseURL = "https://api.hunyuan.cloud.tencent.com/v1"
-)
-
-// HunyuanProvider 实现腾讯混元的 Provider 接口
-type HunyuanProvider struct{}
-
-func init() {
- Register(&HunyuanProvider{})
-}
-
-// Info 返回腾讯混元 provider 的元数据
-func (p *HunyuanProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderHunyuan,
- DisplayName: "腾讯混元 Hunyuan",
- Description: "hunyuan-pro, hunyuan-standard, hunyuan-embedding, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: HunyuanBaseURL,
- types.ModelTypeEmbedding: HunyuanBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证腾讯混元 provider 配置
-func (p *HunyuanProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Hunyuan provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/jina.go b/internal/models/provider/jina.go
deleted file mode 100644
index 024f9545c..000000000
--- a/internal/models/provider/jina.go
+++ /dev/null
@@ -1,44 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- JinaBaseURL = "https://api.jina.ai/v1"
-)
-
-// JinaProvider 实现 Jina AI 的 Provider 接口
-type JinaProvider struct{}
-
-func init() {
- Register(&JinaProvider{})
-}
-
-// Info 返回 Jina AI provider 的元数据
-func (p *JinaProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderJina,
- DisplayName: "Jina",
- Description: "jina-clip-v1, jina-embeddings-v2-base-zh, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeEmbedding: JinaBaseURL,
- types.ModelTypeRerank: JinaBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 Jina AI provider 配置
-func (p *JinaProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Jina AI provider")
- }
- return nil
-}
diff --git a/internal/models/provider/litellm.go b/internal/models/provider/litellm.go
deleted file mode 100644
index c06ca6abb..000000000
--- a/internal/models/provider/litellm.go
+++ /dev/null
@@ -1,55 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // LiteLLMBaseURL is a placeholder the user must replace with a reachable
- // LiteLLM proxy. Loopback defaults (localhost:4000) are rejected by SSRF
- // unless the host is added to SSRF_WHITELIST; Docker also cannot reach a
- // proxy on the host via localhost. The hostname contains "litellm" so
- // DetectProvider recognises the catalog default.
- LiteLLMBaseURL = "http://your_litellm_proxy/v1"
-)
-
-// LiteLLMProvider implements the Provider interface for LiteLLM
-// (https://github.com/BerriAI/litellm). LiteLLM exposes a single
-// OpenAI-compatible endpoint that routes to 100+ providers (OpenAI, Anthropic,
-// Gemini, Bedrock, Vertex, Azure, ...) behind one base URL and key, so it plugs
-// into WeKnora's OpenAI-compatible transport like the other gateway providers.
-type LiteLLMProvider struct{}
-
-func init() {
- Register(&LiteLLMProvider{})
-}
-
-// Info returns the metadata for the LiteLLM provider.
-func (p *LiteLLMProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderLiteLLM,
- DisplayName: "LiteLLM",
- Description: "Self-hosted LiteLLM proxy: one OpenAI-compatible endpoint to 100+ providers.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: LiteLLMBaseURL,
- types.ModelTypeEmbedding: LiteLLMBaseURL,
- types.ModelTypeVLLM: LiteLLMBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig validates the LiteLLM provider configuration.
-func (p *LiteLLMProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for LiteLLM provider")
- }
- return nil
-}
diff --git a/internal/models/provider/lkeap.go b/internal/models/provider/lkeap.go
deleted file mode 100644
index 998eee0cc..000000000
--- a/internal/models/provider/lkeap.go
+++ /dev/null
@@ -1,69 +0,0 @@
-package provider
-
-import (
- "fmt"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // LKEAPBaseURL 腾讯云知识引擎原子能力 (LKEAP) 兼容 OpenAI 协议的 BaseURL
- LKEAPBaseURL = "https://api.lkeap.cloud.tencent.com/v1"
- // LKEAPRerankBaseURL 腾讯云知识引擎原子能力 Rerank API 域名(TC3 签名)
- LKEAPRerankBaseURL = "https://lkeap.tencentcloudapi.com"
-)
-
-// LKEAPProvider 实现腾讯云 LKEAP 的 Provider 接口
-// 支持 DeepSeek-R1, DeepSeek-V3 系列模型,具备思维链能力
-type LKEAPProvider struct{}
-
-func init() {
- Register(&LKEAPProvider{})
-}
-
-// Info 返回 LKEAP provider 的元数据
-func (p *LKEAPProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderLKEAP,
- DisplayName: "腾讯云 LKEAP",
- Description: "DeepSeek-R1, DeepSeek-V3, lke-reranker-base 等",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: LKEAPBaseURL,
- types.ModelTypeRerank: LKEAPRerankBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeRerank,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 LKEAP provider 配置
-func (p *LKEAPProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for LKEAP provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
-
-// IsLKEAPDeepSeekV3Model 检查是否为 DeepSeek V3.x 系列模型
-// V3.x 系列支持通过 Thinking 参数控制思维链开关
-func IsLKEAPDeepSeekV3Model(modelName string) bool {
- return strings.Contains(strings.ToLower(modelName), "deepseek-v3")
-}
-
-// IsLKEAPDeepSeekR1Model 检查是否为 DeepSeek R1 系列模型
-// R1 系列默认开启思维链
-func IsLKEAPDeepSeekR1Model(modelName string) bool {
- return strings.Contains(strings.ToLower(modelName), "deepseek-r1")
-}
-
-// IsLKEAPThinkingModel 检查是否为支持思维链的 LKEAP 模型
-func IsLKEAPThinkingModel(modelName string) bool {
- return IsLKEAPDeepSeekR1Model(modelName) || IsLKEAPDeepSeekV3Model(modelName)
-}
diff --git a/internal/models/provider/longcat.go b/internal/models/provider/longcat.go
deleted file mode 100644
index 0273463ae..000000000
--- a/internal/models/provider/longcat.go
+++ /dev/null
@@ -1,48 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- LongCatBaseURL = "https://api.longcat.chat/openai/v1"
-)
-
-// LongCatProvider 实现 LongCat AI 的 Provider 接口
-type LongCatProvider struct{}
-
-func init() {
- Register(&LongCatProvider{})
-}
-
-// Info 返回 LongCat provider 的元数据
-func (p *LongCatProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderLongCat,
- DisplayName: "LongCat AI",
- Description: "LongCat-Flash-Chat, LongCat-Flash-Thinking, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: LongCatBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 LongCat provider 配置
-func (p *LongCatProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for LongCat provider")
- }
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for LongCat provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/mimo.go b/internal/models/provider/mimo.go
deleted file mode 100644
index c9a393b38..000000000
--- a/internal/models/provider/mimo.go
+++ /dev/null
@@ -1,46 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // MimoBaseURL 小米 Mimo API BaseURL
- MimoBaseURL = "https://api.xiaomimimo.com/v1"
-)
-
-// MimoProvider 实现小米 Mimo 的 Provider 接口
-type MimoProvider struct{}
-
-func init() {
- Register(&MimoProvider{})
-}
-
-// Info 返回小米 Mimo provider 的元数据
-func (p *MimoProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderMimo,
- DisplayName: "小米 MiMo",
- Description: "mimo-v2-flash",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: MimoBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证小米 Mimo provider 配置
-func (p *MimoProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Mimo provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/minimax.go b/internal/models/provider/minimax.go
deleted file mode 100644
index 679802135..000000000
--- a/internal/models/provider/minimax.go
+++ /dev/null
@@ -1,48 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // MiniMaxBaseURL MiniMax 国际版 API BaseURL
- MiniMaxBaseURL = "https://api.minimax.io/v1"
- // MiniMaxCNBaseURL MiniMax 国内版 API BaseURL
- MiniMaxCNBaseURL = "https://api.minimaxi.com/v1"
-)
-
-// MiniMaxProvider 实现 MiniMax 的 Provider 接口
-type MiniMaxProvider struct{}
-
-func init() {
- Register(&MiniMaxProvider{})
-}
-
-// Info 返回 MiniMax provider 的元数据
-func (p *MiniMaxProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderMiniMax,
- DisplayName: "MiniMax",
- Description: "MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: MiniMaxCNBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 MiniMax provider 配置
-func (p *MiniMaxProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for MiniMax provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/modelscope.go b/internal/models/provider/modelscope.go
deleted file mode 100644
index aaa407090..000000000
--- a/internal/models/provider/modelscope.go
+++ /dev/null
@@ -1,53 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // ModelScopeBaseURL ModelScope API BaseURL (OpenAI 兼容模式)
- ModelScopeBaseURL = "https://api-inference.modelscope.cn/v1"
-)
-
-// ModelScopeProvider 实现 ModelScope (魔搭) 的 Provider 接口
-type ModelScopeProvider struct{}
-
-func init() {
- Register(&ModelScopeProvider{})
-}
-
-// Info 返回 ModelScope provider 的元数据
-func (p *ModelScopeProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderModelScope,
- DisplayName: "魔搭 ModelScope",
- Description: "Qwen/Qwen3-8B, Qwen/Qwen3-Embedding-8B, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: ModelScopeBaseURL,
- types.ModelTypeEmbedding: ModelScopeBaseURL,
- types.ModelTypeVLLM: ModelScopeBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 ModelScope provider 配置
-func (p *ModelScopeProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for ModelScope provider")
- }
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for ModelScope provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/moonshot.go b/internal/models/provider/moonshot.go
deleted file mode 100644
index bff1c17e3..000000000
--- a/internal/models/provider/moonshot.go
+++ /dev/null
@@ -1,71 +0,0 @@
-package provider
-
-import (
- "fmt"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- MoonshotBaseURL = "https://api.moonshot.ai/v1"
-)
-
-// IsMoonshotFixedTempModel reports whether the given Moonshot/Kimi model
-// only accepts temperature=1. The following models reject any temperature
-// value other than 1:
-// - moonshot-v1 series (moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k)
-// - kimi-k2.5 and kimi-k2.6 (no temperature param in API docs)
-//
-// kimi-k2 / kimi-k2-turbo / kimi-k2-thinking models accept the full [0,1]
-// range and are NOT affected.
-func IsMoonshotFixedTempModel(modelName string) bool {
- name := strings.ToLower(strings.TrimSpace(modelName))
- if strings.HasPrefix(name, "moonshot-v1") {
- return true
- }
- // kimi-k2.5, kimi-k2.6 — no temperature parameter supported
- if name == "kimi-k2.5" || name == "kimi-k2.6" {
- return true
- }
- return false
-}
-
-// MoonshotProvider 实现 Moonshot AI (Kimi) 的 Provider 接口
-type MoonshotProvider struct{}
-
-func init() {
- Register(&MoonshotProvider{})
-}
-
-// Info 返回 Moonshot provider 的元数据
-func (p *MoonshotProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderMoonshot,
- DisplayName: "月之暗面 Moonshot",
- Description: "kimi-k2-turbo-preview, moonshot-v1-8k-vision-preview, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: MoonshotBaseURL,
- types.ModelTypeVLLM: MoonshotBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 Moonshot provider 配置
-func (p *MoonshotProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for Moonshot provider")
- }
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Moonshot provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/novita.go b/internal/models/provider/novita.go
deleted file mode 100644
index 6d4515c35..000000000
--- a/internal/models/provider/novita.go
+++ /dev/null
@@ -1,50 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // NovitaOpenAIBaseURL Novita OpenAI-compatible API BaseURL
- NovitaOpenAIBaseURL = "https://api.novita.ai/openai/v1"
-)
-
-// NovitaProvider 实现 Novita AI 的 Provider 接口
-type NovitaProvider struct{}
-
-func init() {
- Register(&NovitaProvider{})
-}
-
-// Info 返回 Novita provider 的元数据
-func (p *NovitaProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderNovita,
- DisplayName: "Novita AI",
- Description: "moonshotai/kimi-k2.5, zai-org/glm-5, minimax/minimax-m2.7, qwen/qwen3-embedding-0.6b, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: NovitaOpenAIBaseURL,
- types.ModelTypeEmbedding: NovitaOpenAIBaseURL,
- types.ModelTypeVLLM: NovitaOpenAIBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 Novita provider 配置
-func (p *NovitaProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Novita provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/nvidia.go b/internal/models/provider/nvidia.go
deleted file mode 100644
index 9fb87c0de..000000000
--- a/internal/models/provider/nvidia.go
+++ /dev/null
@@ -1,54 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // NvidiaChatBaseURL NVIDIA Chat 的默认 BaseURL
- NvidiaChatBaseURL = "https://integrate.api.nvidia.com/v1"
- // NvidiaRerankBaseURL NVIDIA Rerank 的默认 BaseURL
- NvidiaRerankBaseURL = "https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking"
-)
-
-// NvidiaProvider 实现NVIDIA AI 的 Provider 接口
-type NvidiaProvider struct{}
-
-func init() {
- Register(&NvidiaProvider{})
-}
-
-// Info 返回NVIDIA provider 的元数据
-func (p *NvidiaProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderNvidia,
- DisplayName: "NVIDIA",
- Description: "deepseek-ai-deepseek-v3_1, nv-embed-v1, rerank-qa-mistral-4b, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: NvidiaChatBaseURL,
- types.ModelTypeEmbedding: NvidiaChatBaseURL,
- types.ModelTypeRerank: NvidiaRerankBaseURL,
- types.ModelTypeVLLM: NvidiaChatBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证NVIDIA provider 配置
-func (p *NvidiaProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for NVIDIA")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/openai.go b/internal/models/provider/openai.go
deleted file mode 100644
index ba0497c77..000000000
--- a/internal/models/provider/openai.go
+++ /dev/null
@@ -1,86 +0,0 @@
-package provider
-
-import (
- "fmt"
- "strings"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- OpenAIBaseURL = "https://api.openai.com/v1"
-)
-
-// OpenAIProvider 实现 OpenAI 的 Provider 接口
-type OpenAIProvider struct{}
-
-func init() {
- Register(&OpenAIProvider{})
-}
-
-// Info 返回 OpenAI provider 的元数据
-func (p *OpenAIProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderOpenAI,
- DisplayName: "OpenAI",
- Description: "gpt-5.2, gpt-5-mini, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: OpenAIBaseURL,
- types.ModelTypeEmbedding: OpenAIBaseURL,
- types.ModelTypeRerank: OpenAIBaseURL,
- types.ModelTypeVLLM: OpenAIBaseURL,
- types.ModelTypeASR: OpenAIBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- types.ModelTypeASR,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 OpenAI provider 配置
-func (p *OpenAIProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for OpenAI provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
-
-// IsOpenAIReasoningOrGPT5Model 判断模型是否为 OpenAI / Azure OpenAI 的
-// 推理类(o-series)或 GPT-5 系列模型。
-//
-// 这些模型在 OpenAI Chat Completions API 中:
-// - 不再支持 `max_tokens`,必须使用 `max_completion_tokens`;
-// - 仅支持默认的 `temperature=1`、`top_p=1`,且不支持 `frequency_penalty` /
-// `presence_penalty` 等采样参数(传非默认值会被拒绝)。
-//
-// 参考:
-// - https://platform.openai.com/docs/api-reference/chat
-// - https://learn.microsoft.com/azure/ai-services/openai/how-to/reasoning
-//
-// 仅基于模型名做启发式匹配;对于 Azure OpenAI,因为模型名实际上是 deployment 名,
-// 用户若用了自定义部署名我们无法识别,此时仍会按普通模型处理(保持原行为)。
-func IsOpenAIReasoningOrGPT5Model(modelName string) bool {
- name := strings.ToLower(strings.TrimSpace(modelName))
- if name == "" {
- return false
- }
- if strings.HasPrefix(name, "gpt-5") {
- return true
- }
- // o1 / o1-mini / o1-preview / o3 / o3-mini / o4-mini ...
- // 必须精确匹配,避免误命中 "openai-..." 之类。
- for _, prefix := range []string{"o1", "o3", "o4"} {
- if name == prefix || strings.HasPrefix(name, prefix+"-") {
- return true
- }
- }
- return false
-}
diff --git a/internal/models/provider/openai_test.go b/internal/models/provider/openai_test.go
deleted file mode 100644
index 3fdc47454..000000000
--- a/internal/models/provider/openai_test.go
+++ /dev/null
@@ -1,46 +0,0 @@
-package provider
-
-import "testing"
-
-// TestIsOpenAIReasoningOrGPT5Model 验证 GPT-5 / o-series 模型识别逻辑。
-// 见 issue #1283:这些模型必须使用 max_completion_tokens 替代 max_tokens。
-func TestIsOpenAIReasoningOrGPT5Model(t *testing.T) {
- cases := []struct {
- name string
- input string
- want bool
- }{
- {"empty", "", false},
-
- {"gpt-5", "gpt-5", true},
- {"gpt-5-mini", "gpt-5-mini", true},
- {"gpt-5.2", "gpt-5.2", true},
- {"gpt-5.5-pro", "gpt-5.5-pro", true},
- {"gpt-5 mixed case", "GPT-5.4-Mini", true},
-
- {"o1", "o1", true},
- {"o1-mini", "o1-mini", true},
- {"o1-preview", "o1-preview", true},
- {"o3", "o3", true},
- {"o3-mini", "o3-mini", true},
- {"o4-mini", "o4-mini", true},
-
- {"gpt-4", "gpt-4", false},
- {"gpt-4o", "gpt-4o", false},
- {"gpt-4o-mini", "gpt-4o-mini", false},
- {"gpt-3.5-turbo", "gpt-3.5-turbo", false},
-
- {"name starting with 'o1' but not o-series", "olympus-1", false},
- {"name starting with 'openai-'", "openai-gpt-4", false},
- {"name starting with 'o3' but not o-series", "o3xtra", false},
- {"random", "qwen-max", false},
- }
- for _, tc := range cases {
- t.Run(tc.name, func(t *testing.T) {
- got := IsOpenAIReasoningOrGPT5Model(tc.input)
- if got != tc.want {
- t.Errorf("IsOpenAIReasoningOrGPT5Model(%q) = %v, want %v", tc.input, got, tc.want)
- }
- })
- }
-}
diff --git a/internal/models/provider/openrouter.go b/internal/models/provider/openrouter.go
deleted file mode 100644
index b2533aa4e..000000000
--- a/internal/models/provider/openrouter.go
+++ /dev/null
@@ -1,46 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- OpenRouterBaseURL = "https://openrouter.ai/api/v1"
-)
-
-// OpenRouterProvider 实现 OpenRouter 的 Provider 接口
-type OpenRouterProvider struct{}
-
-func init() {
- Register(&OpenRouterProvider{})
-}
-
-// Info 返回 OpenRouter provider 的元数据
-func (p *OpenRouterProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderOpenRouter,
- DisplayName: "OpenRouter",
- Description: "openai/gpt-5.2-chat, google/gemini-3-flash-preview, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: OpenRouterBaseURL,
- types.ModelTypeEmbedding: OpenRouterBaseURL,
- types.ModelTypeVLLM: OpenRouterBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 OpenRouter provider 配置
-func (p *OpenRouterProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for OpenRouter provider")
- }
- return nil
-}
diff --git a/internal/models/provider/provider.go b/internal/models/provider/provider.go
index d96036621..d645ef562 100644
--- a/internal/models/provider/provider.go
+++ b/internal/models/provider/provider.go
@@ -1,313 +1,58 @@
-// Package provider defines the unified interface and registry for multi-vendor model API adapters.
+// Package provider is the legacy façade over internal/models/catalog. It keeps
+// the ProviderName constants and the two helpers older call sites still use
+// (DetectProvider and the base URL constants) so those sites keep compiling
+// while the catalog is the single source of vendor facts. New code should
+// import the catalog directly.
package provider
-import (
- "fmt"
- "strings"
- "sync"
+import "github.com/Tencent/WeKnora/internal/models/catalog"
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-// ProviderName 模型服务商名称
+// ProviderName 模型服务商名称(catalog vendor id)。
+//
+//nolint:revive // historical name used across the code base
type ProviderName string
+// Vendor ids; the values match the catalog registrations.
const (
- // OpenAI
- ProviderOpenAI ProviderName = "openai"
- // Anthropic Claude
- ProviderAnthropic ProviderName = "anthropic"
- // 阿里云 DashScope
- ProviderAliyun ProviderName = "aliyun"
- // 智谱AI (GLM 系列)
- ProviderZhipu ProviderName = "zhipu"
- // OpenRouter
- ProviderOpenRouter ProviderName = "openrouter"
- // ProviderLiteLLM is the LiteLLM self-hosted proxy (OpenAI-compatible gateway to 100+ providers).
- ProviderLiteLLM ProviderName = "litellm"
- // Requesty
- ProviderRequesty ProviderName = "requesty"
- // 硅基流动
- ProviderSiliconFlow ProviderName = "siliconflow"
- // Jina AI (Embedding and Rerank)
- ProviderJina ProviderName = "jina"
- // Generic 兼容OpenAI (自定义部署)
- ProviderGeneric ProviderName = "generic"
- // DeepSeek
- ProviderDeepSeek ProviderName = "deepseek"
- // Google Gemini
- ProviderGemini ProviderName = "gemini"
- // 火山引擎 Ark
- ProviderVolcengine ProviderName = "volcengine"
- // 腾讯混元
- ProviderHunyuan ProviderName = "hunyuan"
- // MiniMax
- ProviderMiniMax ProviderName = "minimax"
- // 小米 Mimo
- ProviderMimo ProviderName = "mimo"
- // GPUStack (私有化部署)
- ProviderGPUStack ProviderName = "gpustack"
- // 月之暗面 Moonshot (Kimi)
- ProviderMoonshot ProviderName = "moonshot"
- // 魔搭 ModelScope
- ProviderModelScope ProviderName = "modelscope"
- // 百度千帆
- ProviderQianfan ProviderName = "qianfan"
- // 七牛云
- ProviderQiniu ProviderName = "qiniu"
- // 美团 LongCat AI
- ProviderLongCat ProviderName = "longcat"
- // 腾讯云 LKEAP (知识引擎原子能力)
- ProviderLKEAP ProviderName = "lkeap"
- // NVIDIA
- ProviderNvidia ProviderName = "nvidia"
- // Novita AI
- ProviderNovita ProviderName = "novita"
- // Azure OpenAI
- ProviderAzureOpenAI ProviderName = "azure_openai"
+ ProviderOpenAI ProviderName = "openai"
+ ProviderAnthropic ProviderName = "anthropic"
+ ProviderAliyun ProviderName = "aliyun"
+ ProviderZhipu ProviderName = "zhipu"
+ ProviderOpenRouter ProviderName = "openrouter"
+ ProviderLiteLLM ProviderName = "litellm"
+ ProviderRequesty ProviderName = "requesty"
+ ProviderSiliconFlow ProviderName = "siliconflow"
+ ProviderJina ProviderName = "jina"
+ ProviderGeneric ProviderName = "generic"
+ ProviderDeepSeek ProviderName = "deepseek"
+ ProviderGemini ProviderName = "gemini"
+ ProviderVolcengine ProviderName = "volcengine"
+ ProviderHunyuan ProviderName = "hunyuan"
+ ProviderMiniMax ProviderName = "minimax"
+ ProviderMimo ProviderName = "mimo"
+ ProviderGPUStack ProviderName = "gpustack"
+ ProviderMoonshot ProviderName = "moonshot"
+ ProviderModelScope ProviderName = "modelscope"
+ ProviderQianfan ProviderName = "qianfan"
+ ProviderQiniu ProviderName = "qiniu"
+ ProviderLongCat ProviderName = "longcat"
+ ProviderLKEAP ProviderName = "lkeap"
+ ProviderNvidia ProviderName = "nvidia"
+ ProviderNovita ProviderName = "novita"
+ ProviderAzureOpenAI ProviderName = "azure_openai"
+ ProviderWeKnoraCloud ProviderName = "weknoracloud"
)
-// AllProviders 返回所有注册的提供者名称
-func AllProviders() []ProviderName {
- return []ProviderName{
- ProviderGeneric,
- ProviderWeKnoraCloud,
- ProviderAliyun,
- ProviderZhipu,
- ProviderVolcengine,
- ProviderHunyuan,
- ProviderSiliconFlow,
- ProviderDeepSeek,
- ProviderMiniMax,
- ProviderMoonshot,
- ProviderModelScope,
- ProviderQianfan,
- ProviderQiniu,
- ProviderOpenAI,
- ProviderAnthropic,
- ProviderGemini,
- ProviderOpenRouter,
- ProviderLiteLLM,
- ProviderRequesty,
- ProviderJina,
- ProviderMimo,
- ProviderLongCat,
- ProviderLKEAP,
- ProviderGPUStack,
- ProviderNvidia,
- ProviderNovita,
- ProviderAzureOpenAI,
- }
-}
-
-// ProviderInfo 包含提供者的元数据
-type ProviderInfo struct {
- Name ProviderName // 提供者标识
- DisplayName string // 可读名称
- Description string // 提供者描述
- DefaultURLs map[types.ModelType]string // 按模型类型区分的默认 BaseURL
- ModelTypes []types.ModelType // 支持的模型类型
- RequiresAuth bool // 是否需要 API key
- ExtraFields []ExtraFieldConfig // 额外配置字段
-}
-
-// GetDefaultURL 获取指定模型类型的默认 URL
-func (p ProviderInfo) GetDefaultURL(modelType types.ModelType) string {
- if url, ok := p.DefaultURLs[modelType]; ok {
- return url
- }
- // 回退到 Chat URL
- if url, ok := p.DefaultURLs[types.ModelTypeKnowledgeQA]; ok {
- return url
- }
- return ""
-}
-
-// ExtraFieldConfig 定义提供者的额外配置字段
-type ExtraFieldConfig struct {
- Key string `json:"key"`
- Label string `json:"label"`
- Type string `json:"type"` // "string", "number", "boolean", "select"
- Required bool `json:"required"`
- Default string `json:"default"`
- Placeholder string `json:"placeholder"`
- Options []struct {
- Label string `json:"label"`
- Value string `json:"value"`
- } `json:"options,omitempty"`
-}
-
-// Config 表示模型提供者的配置
-type Config struct {
- Provider ProviderName `json:"provider"`
- BaseURL string `json:"base_url"`
- APIKey string `json:"api_key"`
- ModelName string `json:"model_name"`
- ModelID string `json:"model_id"`
- Extra map[string]any `json:"extra,omitempty"`
-}
-
-type Provider interface {
- // Info 返回服务商的元数据
- Info() ProviderInfo
-
- // ValidateConfig 验证服务商的配置
- ValidateConfig(config *Config) error
-}
-
-// registry 存储所有注册的提供者
-var (
- registryMu sync.RWMutex
- registry = make(map[ProviderName]Provider)
+// Base URLs still referenced by embedding / rerank / service code.
+const (
+ WeKnoraCloudBaseURL = "https://weknora.weixin.qq.com"
+ ZhipuEmbeddingBaseURL = "https://open.bigmodel.cn/api/paas/v4"
+ VolcengineRerankBaseURL = "https://api-knowledgebase.mlp.cn-beijing.volces.com"
+ DeepSeekBaseURL = "https://api.deepseek.com/v1"
)
-// Register 添加一个提供者到全局注册表
-func Register(p Provider) {
- registryMu.Lock()
- defer registryMu.Unlock()
- registry[p.Info().Name] = p
-}
-
-// Get 通过名称从注册表中获取提供者
-func Get(name ProviderName) (Provider, bool) {
- registryMu.RLock()
- defer registryMu.RUnlock()
- p, ok := registry[name]
- return p, ok
-}
-
-// GetOrDefault 通过名称从注册表中获取提供者,如果未找到则返回默认提供者
-func GetOrDefault(name ProviderName) Provider {
- p, ok := Get(name)
- if ok {
- return p
- }
- // 如果未找到则返回默认提供者
- p, _ = Get(ProviderGeneric)
- return p
-}
-
-// List 返回所有注册的提供者(按 AllProviders 定义的顺序)
-func List() []ProviderInfo {
- registryMu.RLock()
- defer registryMu.RUnlock()
-
- result := make([]ProviderInfo, 0, len(registry))
- for _, name := range AllProviders() {
- if p, ok := registry[name]; ok {
- result = append(result, p.Info())
- }
- }
- return result
-}
-
-// ListByModelType 返回所有支持指定模型类型的提供者(按 AllProviders 定义的顺序)
-func ListByModelType(modelType types.ModelType) []ProviderInfo {
- registryMu.RLock()
- defer registryMu.RUnlock()
-
- result := make([]ProviderInfo, 0)
- for _, name := range AllProviders() {
- if p, ok := registry[name]; ok {
- info := p.Info()
- for _, t := range info.ModelTypes {
- if t == modelType {
- result = append(result, info)
- break
- }
- }
- }
- }
- return result
-}
-
-// DetectProvider 通过 BaseURL 检测服务商
+// DetectProvider identifies a vendor from a base URL (legacy rows without a
+// stored provider id).
func DetectProvider(baseURL string) ProviderName {
- switch {
- case containsAny(baseURL, "dashscope.aliyuncs.com"):
- return ProviderAliyun
- case containsAny(baseURL, "open.bigmodel.cn", "zhipu"):
- return ProviderZhipu
- case containsAny(baseURL, "openrouter.ai"):
- return ProviderOpenRouter
- // Hostname/path containing "litellm" (including the catalog placeholder
- // your_litellm_proxy). Loopback URLs such as localhost:4000 stay generic
- // because they are SSRF-blocked unless explicitly whitelisted.
- case containsAny(baseURL, "litellm"):
- return ProviderLiteLLM
- case containsAny(baseURL, "router.requesty.ai", "requesty.ai"):
- return ProviderRequesty
- case containsAny(baseURL, "siliconflow.cn"):
- return ProviderSiliconFlow
- case containsAny(baseURL, "api.jina.ai"):
- return ProviderJina
- case containsAny(baseURL, "openai.azure.com"):
- return ProviderAzureOpenAI
- case containsAny(baseURL, "api.openai.com"):
- return ProviderOpenAI
- case containsAny(baseURL, "api.anthropic.com"):
- return ProviderAnthropic
- case containsAny(baseURL, "api.deepseek.com"):
- return ProviderDeepSeek
- case containsAny(baseURL, "generativelanguage.googleapis.com"):
- return ProviderGemini
- case containsAny(baseURL, "volces.com", "volcengine"):
- return ProviderVolcengine
- case containsAny(baseURL, "hunyuan.cloud.tencent.com"):
- return ProviderHunyuan
- case containsAny(baseURL, "minimax.io", "minimaxi.com"):
- return ProviderMiniMax
- case containsAny(baseURL, "xiaomimimo.com"):
- return ProviderMimo
- case containsAny(baseURL, "gpustack"):
- return ProviderGPUStack
- case containsAny(baseURL, "modelscope.cn"):
- return ProviderModelScope
- case containsAny(baseURL, "qiniuapi.com", "qiniu"):
- return ProviderQiniu
- case containsAny(baseURL, "moonshot.ai"):
- return ProviderMoonshot
- case containsAny(baseURL, "qianfan.baidubce.com", "baidubce.com"):
- return ProviderQianfan
- case containsAny(baseURL, "longcat.chat"):
- return ProviderLongCat
- case containsAny(baseURL, "lkeap.cloud.tencent.com", "api.lkeap", "lkeap.tencentcloudapi.com"):
- return ProviderLKEAP
- case containsAny(baseURL, "nvidia.com"):
- return ProviderNvidia
- case containsAny(baseURL, "api.novita.ai", "novita.ai"):
- return ProviderNovita
- case containsAny(baseURL, "weknora.weixin.qq.com"):
- return ProviderWeKnoraCloud
- default:
- return ProviderGeneric
- }
-}
-
-func containsAny(s string, substrs ...string) bool {
- for _, sub := range substrs {
- if strings.Contains(s, sub) {
- return true
- }
- }
- return false
-}
-
-func NewConfigFromModel(model *types.Model) (*Config, error) {
- if model == nil {
- return nil, fmt.Errorf("model is nil")
- }
-
- providerName := ProviderName(model.Parameters.Provider)
- if providerName == "" {
- providerName = DetectProvider(model.Parameters.BaseURL)
- }
-
- return &Config{
- Provider: providerName,
- BaseURL: model.Parameters.BaseURL,
- APIKey: model.Parameters.APIKey,
- ModelName: model.Name,
- ModelID: model.ID,
- }, nil
+ return ProviderName(catalog.DetectByURL(baseURL))
}
diff --git a/internal/models/provider/provider_test.go b/internal/models/provider/provider_test.go
deleted file mode 100644
index a0a9320e4..000000000
--- a/internal/models/provider/provider_test.go
+++ /dev/null
@@ -1,381 +0,0 @@
-package provider
-
-import (
- "testing"
-
- "github.com/Tencent/WeKnora/internal/types"
- "github.com/stretchr/testify/assert"
- "github.com/stretchr/testify/require"
-)
-
-func TestProviderRegistry(t *testing.T) {
- // Test that all default providers are registered
- t.Run("default providers registered", func(t *testing.T) {
- providers := List()
- assert.NotEmpty(t, providers, "should have registered providers")
-
- // Check specific providers exist
- for _, name := range []ProviderName{ProviderOpenAI, ProviderAliyun, ProviderZhipu, ProviderGeneric} {
- p, ok := Get(name)
- assert.True(t, ok, "provider %s should be registered", name)
- assert.NotNil(t, p, "provider %s should not be nil", name)
- }
- })
-
- t.Run("GetOrDefault fallback", func(t *testing.T) {
- // Non-existent provider should fall back to generic
- p := GetOrDefault("nonexistent")
- require.NotNil(t, p)
- assert.Equal(t, ProviderGeneric, p.Info().Name)
- })
-}
-
-func TestDetectProvider(t *testing.T) {
- tests := []struct {
- url string
- expected ProviderName
- }{
- {"https://api.openai.com/v1", ProviderOpenAI},
- {"https://api.anthropic.com/v1", ProviderAnthropic},
- {"https://openrouter.ai/api/v1", ProviderOpenRouter},
- {"https://litellm.example.com/v1", ProviderLiteLLM},
- {LiteLLMBaseURL, ProviderLiteLLM},
- {"http://localhost:4000/v1", ProviderGeneric},
- {"https://router.requesty.ai/v1", ProviderRequesty},
- {"https://dashscope.aliyuncs.com/compatible-mode/v1", ProviderAliyun},
- {"https://open.bigmodel.cn/api/paas/v4", ProviderZhipu},
- {"https://api.deepseek.com/v1", ProviderDeepSeek},
- {"https://generativelanguage.googleapis.com/v1beta/openai", ProviderGemini},
- {"https://ark.cn-beijing.volces.com/api/v3", ProviderVolcengine},
- {"https://api.hunyuan.cloud.tencent.com/v1", ProviderHunyuan},
- {"https://api.minimaxi.com/v1", ProviderMiniMax},
- {"https://api.minimax.io/v1", ProviderMiniMax},
- {"https://api.xiaomimimo.com/v1", ProviderMimo},
- {"https://custom-endpoint.example.com/v1", ProviderGeneric},
- {"http://localhost:11434/v1", ProviderGeneric},
- {"https://integrate.api.nvidia.com/v1", ProviderNvidia},
- {"https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking", ProviderNvidia},
- }
-
- for _, tt := range tests {
- t.Run(tt.url, func(t *testing.T) {
- result := DetectProvider(tt.url)
- assert.Equal(t, tt.expected, result)
- })
- }
-}
-
-func TestAnthropicProviderValidation(t *testing.T) {
- p := &AnthropicProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "sk-ant-test",
- ModelName: "claude-sonnet-4-5",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("missing API key", func(t *testing.T) {
- config := &Config{
- ModelName: "claude-sonnet-4-5",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "API key")
- })
-
- t.Run("info", func(t *testing.T) {
- info := p.Info()
- assert.Equal(t, ProviderAnthropic, info.Name)
- assert.Equal(t, AnthropicBaseURL, info.GetDefaultURL(types.ModelTypeKnowledgeQA))
- assert.Contains(t, info.ModelTypes, types.ModelTypeKnowledgeQA)
- assert.True(t, info.RequiresAuth)
- })
-}
-
-func TestOpenAIProviderValidation(t *testing.T) {
- p := &OpenAIProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "sk-test",
- ModelName: "gpt-4",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("missing API key", func(t *testing.T) {
- config := &Config{
- ModelName: "gpt-4",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "API key")
- })
-
- t.Run("missing model name", func(t *testing.T) {
- config := &Config{
- APIKey: "sk-test",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "model name")
- })
-}
-
-func TestAliyunProviderValidation(t *testing.T) {
- p := &AliyunProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "sk-test",
- ModelName: "qwen-max",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("info", func(t *testing.T) {
- info := p.Info()
- assert.Equal(t, ProviderAliyun, info.Name)
- assert.Contains(t, info.ModelTypes, types.ModelTypeKnowledgeQA)
- assert.Contains(t, info.ModelTypes, types.ModelTypeEmbedding)
- assert.Contains(t, info.ModelTypes, types.ModelTypeRerank)
- })
-}
-
-func TestAliyunModelDetection(t *testing.T) {
- t.Run("Qwen3 model detection", func(t *testing.T) {
- assert.True(t, IsQwen3Model("qwen3-32b"))
- assert.True(t, IsQwen3Model("qwen3-72b"))
- assert.False(t, IsQwen3Model("qwen-max"))
- assert.False(t, IsQwen3Model("qwen2.5-72b"))
- })
-
- t.Run("DeepSeek model detection", func(t *testing.T) {
- assert.True(t, IsDeepSeekModel("deepseek-chat"))
- assert.True(t, IsDeepSeekModel("deepseek-v3.1"))
- assert.True(t, IsDeepSeekModel("DeepSeek-Chat"))
- assert.False(t, IsDeepSeekModel("qwen-max"))
- })
-}
-
-func TestMiniMaxProviderValidation(t *testing.T) {
- p := &MiniMaxProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "test-key",
- ModelName: "MiniMax-M2.7",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("missing API key", func(t *testing.T) {
- config := &Config{
- ModelName: "MiniMax-M2.7",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "API key")
- })
-
- t.Run("missing model name", func(t *testing.T) {
- config := &Config{
- APIKey: "test-key",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "model name")
- })
-
- t.Run("info", func(t *testing.T) {
- info := p.Info()
- assert.Equal(t, ProviderMiniMax, info.Name)
- assert.Equal(t, "MiniMax", info.DisplayName)
- assert.Contains(t, info.ModelTypes, types.ModelTypeKnowledgeQA)
- assert.True(t, info.RequiresAuth)
- assert.Contains(t, info.Description, "M2.7")
- })
-}
-
-func TestZhipuProviderValidation(t *testing.T) {
- p := &ZhipuProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "test-key",
- ModelName: "glm-4",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("info", func(t *testing.T) {
- info := p.Info()
- assert.Equal(t, ProviderZhipu, info.Name)
- assert.Equal(t, ZhipuChatBaseURL, info.GetDefaultURL(types.ModelTypeKnowledgeQA))
- assert.Equal(t, ZhipuEmbeddingBaseURL, info.GetDefaultURL(types.ModelTypeEmbedding))
- })
-}
-
-func TestRequestyProviderValidation(t *testing.T) {
- p := &RequestyProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "test-key",
- ModelName: "openai/gpt-4o-mini",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("missing API key", func(t *testing.T) {
- config := &Config{
- ModelName: "openai/gpt-4o-mini",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "API key")
- })
-
- t.Run("info", func(t *testing.T) {
- info := p.Info()
- assert.Equal(t, ProviderRequesty, info.Name)
- assert.Equal(t, "Requesty", info.DisplayName)
- assert.Equal(t, RequestyBaseURL, info.GetDefaultURL(types.ModelTypeKnowledgeQA))
- assert.Equal(t, RequestyBaseURL, info.GetDefaultURL(types.ModelTypeEmbedding))
- assert.Contains(t, info.ModelTypes, types.ModelTypeKnowledgeQA)
- assert.True(t, info.RequiresAuth)
- })
-}
-
-func TestListByModelType(t *testing.T) {
- t.Run("chat models", func(t *testing.T) {
- providers := ListByModelType(types.ModelTypeKnowledgeQA)
- assert.NotEmpty(t, providers)
- // Multiple providers support chat
- assert.GreaterOrEqual(t, len(providers), 9)
- })
-
- t.Run("rerank models", func(t *testing.T) {
- providers := ListByModelType(types.ModelTypeRerank)
- assert.NotEmpty(t, providers)
- // Check that Aliyun supports rerank
- foundAliyun := false
- foundLKEAP := false
- foundVolcengine := false
- for _, p := range providers {
- if p.Name == ProviderAliyun {
- foundAliyun = true
- }
- if p.Name == ProviderLKEAP {
- foundLKEAP = true
- assert.Equal(t, LKEAPRerankBaseURL, p.GetDefaultURL(types.ModelTypeRerank))
- }
- if p.Name == ProviderVolcengine {
- foundVolcengine = true
- assert.Equal(t, VolcengineRerankBaseURL, p.GetDefaultURL(types.ModelTypeRerank))
- }
- }
- assert.True(t, foundAliyun, "Aliyun should support rerank")
- assert.True(t, foundLKEAP, "LKEAP should support rerank")
- assert.True(t, foundVolcengine, "Volcengine should support rerank")
- })
-
- t.Run("embedding models include openrouter", func(t *testing.T) {
- providers := ListByModelType(types.ModelTypeEmbedding)
- assert.NotEmpty(t, providers)
-
- found := false
- for _, p := range providers {
- if p.Name == ProviderOpenRouter {
- found = true
- assert.Equal(t, OpenRouterBaseURL, p.GetDefaultURL(types.ModelTypeEmbedding))
- break
- }
- }
-
- assert.True(t, found, "OpenRouter should support embedding")
- })
-
- t.Run("embedding models include gemini", func(t *testing.T) {
- providers := ListByModelType(types.ModelTypeEmbedding)
- assert.NotEmpty(t, providers)
-
- found := false
- for _, p := range providers {
- if p.Name == ProviderGemini {
- found = true
- assert.Equal(t, GeminiBaseURL, p.GetDefaultURL(types.ModelTypeEmbedding))
- break
- }
- }
-
- assert.True(t, found, "Gemini should support embedding via the native Gemini API")
- })
-}
-
-func TestLiteLLMProviderValidation(t *testing.T) {
- p := &LiteLLMProvider{}
-
- t.Run("valid config", func(t *testing.T) {
- config := &Config{
- APIKey: "test-key",
- ModelName: "gpt-4.1-mini",
- }
- err := p.ValidateConfig(config)
- assert.NoError(t, err)
- })
-
- t.Run("missing API key", func(t *testing.T) {
- config := &Config{
- ModelName: "gpt-4.1-mini",
- }
- err := p.ValidateConfig(config)
- assert.Error(t, err)
- assert.Contains(t, err.Error(), "API key")
- })
-
- t.Run("info", func(t *testing.T) {
- info := p.Info()
- assert.Equal(t, ProviderLiteLLM, info.Name)
- assert.Equal(t, "LiteLLM", info.DisplayName)
- assert.True(t, info.RequiresAuth)
- assert.Equal(t, LiteLLMBaseURL, info.DefaultURLs[types.ModelTypeKnowledgeQA])
- assert.Equal(t, LiteLLMBaseURL, info.DefaultURLs[types.ModelTypeEmbedding])
- assert.Equal(t, LiteLLMBaseURL, info.DefaultURLs[types.ModelTypeVLLM])
- assert.Contains(t, info.ModelTypes, types.ModelTypeKnowledgeQA)
- assert.Contains(t, info.ModelTypes, types.ModelTypeEmbedding)
- assert.Contains(t, info.ModelTypes, types.ModelTypeVLLM)
- })
-
- t.Run("registered and listed", func(t *testing.T) {
- got, ok := Get(ProviderLiteLLM)
- require.True(t, ok)
- require.NotNil(t, got)
-
- foundChat := false
- for _, info := range ListByModelType(types.ModelTypeKnowledgeQA) {
- if info.Name == ProviderLiteLLM {
- foundChat = true
- break
- }
- }
- assert.True(t, foundChat, "LiteLLM should appear for chat models")
-
- foundEmbed := false
- for _, info := range ListByModelType(types.ModelTypeEmbedding) {
- if info.Name == ProviderLiteLLM {
- foundEmbed = true
- break
- }
- }
- assert.True(t, foundEmbed, "LiteLLM should appear for embedding models")
- })
-}
diff --git a/internal/models/provider/qianfan.go b/internal/models/provider/qianfan.go
deleted file mode 100644
index aac918822..000000000
--- a/internal/models/provider/qianfan.go
+++ /dev/null
@@ -1,54 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- QianfanBaseURL = "https://qianfan.baidubce.com/v2"
-)
-
-// QianfanProvider 实现百度千帆的 Provider 接口
-type QianfanProvider struct{}
-
-func init() {
- Register(&QianfanProvider{})
-}
-
-// Info 返回百度千帆 provider 的元数据
-func (p *QianfanProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderQianfan,
- DisplayName: "百度千帆 Baidu Cloud",
- Description: "ernie-5.0-thinking-preview, embedding-v1, bce-reranker-base, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: QianfanBaseURL,
- types.ModelTypeEmbedding: QianfanBaseURL,
- types.ModelTypeRerank: QianfanBaseURL,
- types.ModelTypeVLLM: QianfanBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证百度千帆 provider 配置
-func (p *QianfanProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for Qianfan provider")
- }
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Qianfan provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/qiniu.go b/internal/models/provider/qiniu.go
deleted file mode 100644
index 816e59945..000000000
--- a/internal/models/provider/qiniu.go
+++ /dev/null
@@ -1,49 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // QiniuBaseURL 七牛云 API BaseURL (OpenAI 兼容模式)
- QiniuBaseURL = "https://api.qnaigc.com/v1"
-)
-
-// QiniuProvider 实现七牛云的 Provider 接口
-type QiniuProvider struct{}
-
-func init() {
- Register(&QiniuProvider{})
-}
-
-// Info 返回七牛云 provider 的元数据
-func (p *QiniuProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderQiniu,
- DisplayName: "七牛云 Qiniu",
- Description: "deepseek/deepseek-v3.2-251201, z-ai/glm-4.7, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: QiniuBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证七牛云 provider 配置
-func (p *QiniuProvider) ValidateConfig(config *Config) error {
- if config.BaseURL == "" {
- return fmt.Errorf("base URL is required for Qiniu provider")
- }
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Qiniu provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/requesty.go b/internal/models/provider/requesty.go
deleted file mode 100644
index a03bc119c..000000000
--- a/internal/models/provider/requesty.go
+++ /dev/null
@@ -1,46 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- RequestyBaseURL = "https://router.requesty.ai/v1"
-)
-
-// RequestyProvider 实现 Requesty 的 Provider 接口
-type RequestyProvider struct{}
-
-func init() {
- Register(&RequestyProvider{})
-}
-
-// Info 返回 Requesty provider 的元数据
-func (p *RequestyProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderRequesty,
- DisplayName: "Requesty",
- Description: "openai/gpt-4o-mini, anthropic/claude-sonnet-4-5, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: RequestyBaseURL,
- types.ModelTypeEmbedding: RequestyBaseURL,
- types.ModelTypeVLLM: RequestyBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证 Requesty provider 配置
-func (p *RequestyProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Requesty provider")
- }
- return nil
-}
diff --git a/internal/models/provider/siliconflow.go b/internal/models/provider/siliconflow.go
deleted file mode 100644
index f1b3f328b..000000000
--- a/internal/models/provider/siliconflow.go
+++ /dev/null
@@ -1,50 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- SiliconFlowBaseURL = "https://api.siliconflow.cn/v1"
-)
-
-// SiliconFlowProvider 实现硅基流动的 Provider 接口
-type SiliconFlowProvider struct{}
-
-func init() {
- Register(&SiliconFlowProvider{})
-}
-
-// Info 返回硅基流动 provider 的元数据
-func (p *SiliconFlowProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderSiliconFlow,
- DisplayName: "硅基流动 SiliconFlow",
- Description: "deepseek-ai/DeepSeek-V3.1, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: SiliconFlowBaseURL,
- types.ModelTypeEmbedding: SiliconFlowBaseURL,
- types.ModelTypeRerank: SiliconFlowBaseURL,
- types.ModelTypeVLLM: SiliconFlowBaseURL,
- types.ModelTypeASR: SiliconFlowBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- types.ModelTypeASR,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证硅基流动 provider 配置
-func (p *SiliconFlowProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for SiliconFlow provider")
- }
- return nil
-}
diff --git a/internal/models/provider/volcengine.go b/internal/models/provider/volcengine.go
deleted file mode 100644
index b20a8122e..000000000
--- a/internal/models/provider/volcengine.go
+++ /dev/null
@@ -1,56 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // VolcengineChatBaseURL 火山引擎 Ark Chat API BaseURL (OpenAI 兼容模式)
- VolcengineChatBaseURL = "https://ark.cn-beijing.volces.com/api/v3"
- // VolcengineEmbeddingBaseURL 火山引擎 Ark Multimodal Embedding API BaseURL
- VolcengineEmbeddingBaseURL = "https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal"
- // VolcengineRerankBaseURL 火山引擎知识库托管 Rerank API BaseURL
- VolcengineRerankBaseURL = "https://api-knowledgebase.mlp.cn-beijing.volces.com"
-)
-
-// VolcengineProvider 实现火山引擎 Ark 的 Provider 接口
-type VolcengineProvider struct{}
-
-func init() {
- Register(&VolcengineProvider{})
-}
-
-// Info 返回火山引擎 provider 的元数据
-func (p *VolcengineProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderVolcengine,
- DisplayName: "火山引擎 Volcengine",
- Description: "doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615, doubao-seed-rerank, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: VolcengineChatBaseURL,
- types.ModelTypeEmbedding: VolcengineEmbeddingBaseURL,
- types.ModelTypeRerank: VolcengineRerankBaseURL,
- types.ModelTypeVLLM: VolcengineChatBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证火山引擎 provider 配置
-func (p *VolcengineProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Volcengine Ark provider")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/provider/weknoracloud.go b/internal/models/provider/weknoracloud.go
deleted file mode 100644
index a84ea8ed7..000000000
--- a/internal/models/provider/weknoracloud.go
+++ /dev/null
@@ -1,43 +0,0 @@
-package provider
-
-import "github.com/Tencent/WeKnora/internal/types"
-
-const (
- ProviderWeKnoraCloud ProviderName = "weknoracloud"
-
- // WeKnoraCloudBaseURL WeKnoraCloud 服务硬编码 Base URL(统一入口,路径由各实现拼接)
- WeKnoraCloudBaseURL = "https://weknora.weixin.qq.com"
-)
-
-type WeKnoraCloudProvider struct{}
-
-func init() {
- Register(&WeKnoraCloudProvider{})
-}
-
-func (p *WeKnoraCloudProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderWeKnoraCloud,
- DisplayName: "WeKnoraCloud",
- Description: "WeKnora云服务,模型:chat, embedding, rerank, vlm",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: WeKnoraCloudBaseURL,
- types.ModelTypeEmbedding: WeKnoraCloudBaseURL,
- types.ModelTypeRerank: WeKnoraCloudBaseURL,
- types.ModelTypeVLLM: WeKnoraCloudBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-func (p *WeKnoraCloudProvider) ValidateConfig(config *Config) error {
- // AppID/AppSecret 通过专用初始化接口写入,此处仅做结构校验。
- // 其中 AppSecret 字段当前实际承载上游 API Key。
- return nil
-}
diff --git a/internal/models/provider/zhipu.go b/internal/models/provider/zhipu.go
deleted file mode 100644
index aecdc8da0..000000000
--- a/internal/models/provider/zhipu.go
+++ /dev/null
@@ -1,56 +0,0 @@
-package provider
-
-import (
- "fmt"
-
- "github.com/Tencent/WeKnora/internal/types"
-)
-
-const (
- // ZhipuChatBaseURL 智谱 AI Chat 的默认 BaseURL
- ZhipuChatBaseURL = "https://open.bigmodel.cn/api/paas/v4"
- // ZhipuEmbeddingBaseURL 智谱 AI Embedding 的默认 BaseURL
- ZhipuEmbeddingBaseURL = "https://open.bigmodel.cn/api/paas/v4"
- // ZhipuRerankBaseURL 智谱 AI Rerank 的默认 BaseURL
- ZhipuRerankBaseURL = "https://open.bigmodel.cn/api/paas/v4/rerank"
-)
-
-// ZhipuProvider 实现智谱 AI 的 Provider 接口
-type ZhipuProvider struct{}
-
-func init() {
- Register(&ZhipuProvider{})
-}
-
-// Info 返回智谱 AI provider 的元数据
-func (p *ZhipuProvider) Info() ProviderInfo {
- return ProviderInfo{
- Name: ProviderZhipu,
- DisplayName: "智谱 BigModel",
- Description: "glm-4.7, embedding-3, rerank, etc.",
- DefaultURLs: map[types.ModelType]string{
- types.ModelTypeKnowledgeQA: ZhipuChatBaseURL,
- types.ModelTypeEmbedding: ZhipuEmbeddingBaseURL,
- types.ModelTypeRerank: ZhipuRerankBaseURL,
- types.ModelTypeVLLM: ZhipuChatBaseURL,
- },
- ModelTypes: []types.ModelType{
- types.ModelTypeKnowledgeQA,
- types.ModelTypeEmbedding,
- types.ModelTypeRerank,
- types.ModelTypeVLLM,
- },
- RequiresAuth: true,
- }
-}
-
-// ValidateConfig 验证智谱 AI provider 配置
-func (p *ZhipuProvider) ValidateConfig(config *Config) error {
- if config.APIKey == "" {
- return fmt.Errorf("API key is required for Zhipu AI")
- }
- if config.ModelName == "" {
- return fmt.Errorf("model name is required")
- }
- return nil
-}
diff --git a/internal/models/rerank/langfuse_wrapper.go b/internal/models/rerank/langfuse_wrapper.go
index 1905cb3a0..a61580f6f 100644
--- a/internal/models/rerank/langfuse_wrapper.go
+++ b/internal/models/rerank/langfuse_wrapper.go
@@ -6,8 +6,10 @@ import (
"github.com/Tencent/WeKnora/internal/tracing/langfuse"
)
-const langfuseRerankPreviewDocs = 8
-const langfuseRerankMaxScores = 50
+const (
+ langfuseRerankPreviewDocs = 8
+ langfuseRerankMaxScores = 50
+)
// langfuseReranker wraps a Reranker and reports each rerank call as a
// Langfuse generation observation. Rerankers don't return token usage, but
diff --git a/internal/models/rerank/provider_detection_test.go b/internal/models/rerank/provider_detection_test.go
new file mode 100644
index 000000000..9a9987d0e
--- /dev/null
+++ b/internal/models/rerank/provider_detection_test.go
@@ -0,0 +1,32 @@
+package rerank
+
+import (
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/provider"
+)
+
+// TestDetectProviderSeesVendorCatalog guards the blank import of
+// internal/models/vendors in reranker.go.
+//
+// provider.DetectProvider is a thin wrapper over catalog.DetectByURL, which
+// returns "generic" for every URL while the catalog is empty. Without the
+// vendor packages linked in, a stored rerank row that carries no explicit
+// provider id (the legacy shape DetectProvider exists for) would silently be
+// built as a plain OpenAI-compatible reranker: LKEAP and Volcengine rows would
+// stop being TC3/AK-SK signed and fail at call time instead.
+func TestDetectProviderSeesVendorCatalog(t *testing.T) {
+ cases := map[string]provider.ProviderName{
+ "https://api.lkeap.cloud.tencent.com/v1": provider.ProviderLKEAP,
+ "https://api-knowledgebase.mlp.cn-beijing.volces.com": provider.ProviderVolcengine,
+ "https://api.jina.ai/v1": provider.ProviderJina,
+ "https://open.bigmodel.cn/api/paas/v4": provider.ProviderZhipu,
+ "https://dashscope.aliyuncs.com/compatible-mode/v1": provider.ProviderAliyun,
+ "https://some-self-hosted-gateway.example.internal/v1": provider.ProviderGeneric,
+ }
+ for baseURL, want := range cases {
+ if got := provider.DetectProvider(baseURL); got != want {
+ t.Errorf("DetectProvider(%q) = %q, want %q", baseURL, got, want)
+ }
+ }
+}
diff --git a/internal/models/rerank/reranker.go b/internal/models/rerank/reranker.go
index f944ad6e6..cf382c09d 100644
--- a/internal/models/rerank/reranker.go
+++ b/internal/models/rerank/reranker.go
@@ -7,6 +7,12 @@ import (
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/provider"
+ // provider.DetectProvider answers from the vendor catalog, which is empty
+ // until the vendor packages have run their init. Without this import every
+ // URL detects as "generic" and newReranker below falls through to the
+ // OpenAI-compatible reranker for LKEAP / Volcengine / Jina / … rows that
+ // carry no explicit provider id.
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
"github.com/Tencent/WeKnora/internal/types"
)
diff --git a/internal/models/vendors/aliyun/icon.svg b/internal/models/vendors/aliyun/icon.svg
new file mode 100644
index 000000000..56c20781e
--- /dev/null
+++ b/internal/models/vendors/aliyun/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>AlibabaCloud</title><path d="M14.752 4.64h5.274C22.242 4.64 24 6.475 24 8.691V15.8a3.947 3.947 0 01-3.974 3.975h-5.274l1.299-1.835 3.822-1.222c.688-.23 1.146-.918 1.146-1.605v-5.81c0-.687-.458-1.375-1.146-1.605L16.05 6.475l-1.3-1.835zM2.98 15.111c0 .688.46 1.376 1.147 1.606l3.822 1.146 1.3 1.835H3.974A3.947 3.947 0 010 15.723V8.69c0-2.216 1.758-4.05 3.975-4.05h5.273L7.95 6.474 4.127 7.697c-.688.23-1.146.918-1.146 1.606v5.808z" fill="#FF6A00"></path><path d="M16.051 11.213H8.025v1.835h8.026v-1.835z" fill="#FF6A00"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/aliyun/models.json b/internal/models/vendors/aliyun/models.json
new file mode 100644
index 000000000..506413ca2
--- /dev/null
+++ b/internal/models/vendors/aliyun/models.json
@@ -0,0 +1,53 @@
+{
+ "vendor": "aliyun",
+ "source": "https://help.aliyun.com/zh/model-studio/deep-thinking",
+ "models": [
+ {"name": "Qwen3 family (hybrid thinking)", "match": "qwen3*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "Qwen3.5 family (hybrid thinking)", "match": "qwen3.5*", "reasoning": true, "input": ["text", "image"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "Qwen3.6 family (hybrid thinking)", "match": "qwen3.6*", "reasoning": true, "input": ["text", "image"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "Qwen3.7 family (hybrid thinking)", "match": "qwen3.7*", "reasoning": true, "input": ["text", "image"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "Qwen3.8 family (hybrid thinking)", "match": "qwen3.8*", "reasoning": true, "input": ["text", "image"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true, "supports_reasoning_effort": true}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "medium", "xhigh": "xhigh", "max": "xhigh"}},
+ {"name": "qwen-plus family (hybrid thinking)", "match": "qwen-plus*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "qwen-max family (hybrid thinking)", "match": "qwen-max*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "qwen-turbo family (hybrid thinking)", "match": "qwen-turbo*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "qwen-flash family (hybrid thinking)", "match": "qwen-flash*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "DeepSeek V3 family on DashScope (hybrid thinking)", "match": "deepseek-v3*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "DeepSeek V4 family on DashScope (hybrid thinking)", "match": "deepseek-v4*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "Kimi K2 family on DashScope (hybrid thinking)", "match": "kimi-k2*", "reasoning": true, "input": ["text", "image"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"name": "GLM-5 family on DashScope (hybrid thinking)", "match": "glm-5*", "reasoning": true, "input": ["text"], "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+
+ {"id": "qwen3.8-max", "name": "Qwen3.8 Max", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 1.77744, "output": 5.33231, "cache_read": 0.22218, "cache_write": 2.22179}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true, "supports_reasoning_effort": true}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "medium", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "qwen3.8-flash", "name": "Qwen3.8 Flash", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 0.11875, "output": 0.40073, "cache_read": 0.01187, "cache_write": 0.14844}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true, "supports_reasoning_effort": true}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "medium", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "qwen3.7-max", "name": "Qwen3.7 Max", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 2.5, "output": 7.5, "cache_read": 0.5, "cache_write": 3.125}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3.7-plus", "name": "Qwen3.7 Plus", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 64000, "cost": {"input": 0.5, "output": 3, "cache_read": 0.05, "cache_write": 0.625}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3.7-flash", "name": "Qwen3.7 Flash", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 0.02962, "output": 0.1185, "cache_read": 0.002962, "cache_write": 0.03703}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3.6-plus", "name": "Qwen3.6 Plus", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 0.5, "output": 3, "cache_read": 0.05, "cache_write": 0.625}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3.6-flash", "name": "Qwen3.6 Flash", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 0.1875, "output": 1.125, "cache_write": 0.234375}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3.5-plus", "name": "Qwen3.5 Plus", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 0.287, "output": 1.722}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3.5-flash", "name": "Qwen3.5 Flash", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 0.172, "output": 1.033}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3-max", "name": "Qwen3 Max", "reasoning": true, "input": ["text"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 1.291, "output": 7.749}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen3-vl-plus", "name": "Qwen3 VL Plus", "reasoning": true, "input": ["text", "image"], "context_window": 262144, "max_output_tokens": 32768, "cost": {"input": 0.143353, "output": 1.433525}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen-plus", "name": "Qwen Plus", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 32768, "cost": {"input": 0.115, "output": 0.287, "cache_read": 0.012, "cache_write": 0.144}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen-max", "name": "Qwen Max", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 8192, "cost": {"input": 0.345, "output": 1.377}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen-turbo", "name": "Qwen Turbo", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 16384, "cost": {"input": 0.044, "output": 0.087}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen-flash", "name": "Qwen Flash", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 32768, "cost": {"input": 0.022, "output": 0.216}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "qwen-vl-max", "name": "Qwen VL Max", "reasoning": false, "input": ["text", "image"], "context_window": 131072, "max_output_tokens": 8192, "cost": {"input": 0.23, "output": 0.574}},
+ {"id": "qwen-vl-plus", "name": "Qwen VL Plus", "reasoning": false, "input": ["text", "image"], "context_window": 131072, "max_output_tokens": 8192, "cost": {"input": 0.115, "output": 0.287}},
+ {"id": "qwq-plus", "name": "QwQ Plus", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 8192, "cost": {"input": 0.23, "output": 0.574}, "thinking_levels": {"off": null}, "source": "https://help.aliyun.com/zh/model-studio/deep-thinking"},
+ {"id": "qwq-32b", "name": "QwQ 32B", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 8192, "cost": {"input": 0.287, "output": 0.861}, "thinking_levels": {"off": null}},
+ {"id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 393216, "cost": {"input": 0.435, "output": 0.87, "cache_read": 0.003625}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true, "supports_reasoning_effort": true}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://help.aliyun.com/zh/model-studio/deepseek-api"},
+ {"id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 393216, "cost": {"input": 0.14, "output": 0.28, "cache_read": 0.0028}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true, "supports_reasoning_effort": true}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://help.aliyun.com/zh/model-studio/deepseek-api"},
+ {"id": "deepseek-r1", "name": "DeepSeek R1", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 16384, "cost": {"input": 0.574, "output": 2.294}, "thinking_levels": {"off": null}, "source": "https://help.aliyun.com/zh/model-studio/deepseek-api"},
+ {"id": "kimi-k3", "name": "Kimi K3", "reasoning": true, "input": ["text", "image"], "context_window": 1048576, "max_output_tokens": 1048576, "cost": {"input": 2.827, "output": 14.133, "cache_read": 0.283}, "thinking_levels": {"off": null}},
+ {"id": "kimi-k2.6", "name": "Kimi K2.6", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 16384, "cost": {"input": 0.929, "output": 3.858}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true}},
+ {"id": "glm-5.3", "name": "GLM-5.3", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 1.1, "output": 3.851, "cache_read": 0.275}, "compat": {"thinking_always_send": true, "thinking_disable_on_non_stream": true, "supports_reasoning_effort": true}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3"},
+
+ {"id": "qwen3.7-text-embedding", "name": "Qwen3.7 Text Embedding", "type": "Embedding", "dimension": 1024, "source": "https://help.aliyun.com/zh/model-studio/embedding"},
+ {"id": "qwen3.7-text-embedding-flash", "name": "Qwen3.7 Text Embedding Flash", "type": "Embedding", "dimension": 1024, "source": "https://help.aliyun.com/zh/model-studio/embedding"},
+ {"id": "text-embedding-v4", "name": "Tongyi text-embedding-v4", "type": "Embedding", "dimension": 1024, "source": "https://help.aliyun.com/zh/model-studio/embedding"},
+ {"id": "text-embedding-v3", "name": "Tongyi text-embedding-v3", "type": "Embedding", "dimension": 1024, "source": "https://help.aliyun.com/zh/model-studio/embedding"},
+ {"id": "tongyi-embedding-vision-plus", "name": "Tongyi Embedding Vision Plus", "type": "Embedding", "dimension": 1152, "source": "https://help.aliyun.com/zh/model-studio/multimodal-embedding-api"},
+ {"id": "qwen3-rerank", "name": "Qwen3 Rerank", "type": "Rerank", "source": "https://help.aliyun.com/zh/model-studio/text-rerank-api"},
+ {"id": "gte-rerank-v2", "name": "GTE Rerank v2", "type": "Rerank", "source": "https://help.aliyun.com/zh/model-studio/text-rerank-api"}
+ ]
+}
diff --git a/internal/models/vendors/aliyun/vendor.go b/internal/models/vendors/aliyun/vendor.go
new file mode 100644
index 000000000..cc9734764
--- /dev/null
+++ b/internal/models/vendors/aliyun/vendor.go
@@ -0,0 +1,148 @@
+// Package aliyun registers Alibaba Cloud Model Studio (Bailian / DashScope)
+// through its OpenAI-compatible mode.
+//
+// Facts (https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-chat-completions,
+// https://help.aliyun.com/zh/model-studio/deep-thinking and
+// https://help.aliyun.com/zh/model-studio/base-url):
+// - the OpenAI-compatible Beijing base URL is
+// https://dashscope.aliyuncs.com/compatible-mode/v1. The Base URL page
+// still lists it and adds region twins (dashscope-intl / dashscope-us /
+// cn-hongkong.dashscope) plus workspace-exclusive hosts
+// ({WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1) that it
+// recommends for production. The workspace hosts need an id we do not
+// have, so the dashscope host stays the default;
+// - the same hosts expose an Anthropic Messages facade under
+// /apps/anthropic and the DashScope-native API under /api/v1. This
+// package configures OpenAI Chat Completions, which is what the model
+// pages document first;
+// - output cap is `max_completion_tokens` ("模型输出的最大长度,包含思维链和
+// 模型回答"). The parameter table marks `max_tokens` 即将废弃 and names
+// this field its successor. `max_tokens` is still accepted today, but
+// following a vendor that has announced a replacement is the cheaper
+// side of the bet: the deprecated field disappears on DashScope's
+// schedule, the successor does not;
+// - hybrid-thinking models (Qwen3 / Qwen3.x, qwen-plus / -max / -turbo /
+// -flash, DeepSeek V3 / V4, Kimi K2, GLM-5) are switched with
+// `enable_thinking` and budgeted with `thinking_budget` (max token count
+// of the chain of thought; the default is the model's own maximum).
+// Per-model defaults differ, and the docs require the switch to be sent
+// explicitly whenever it deviates from that default, so those families
+// carry thinking_always_send in models.json;
+// - with `enable_thinking: true` the commercial Qwen models only support
+// streaming ("模型开启思考模式时仅支持增量流式输出"), so the hybrid
+// families also carry thinking_disable_on_non_stream;
+// - always-on reasoners (仅思考模式): qwq-plus, deepseek-r1 /
+// deepseek-r1-0528, qwen3.8-2.4t-a95b, qwen3.7-max-preview,
+// qwen3.7-max-2026-05-17, qwen3-next-80b-a3b-thinking. Those carry
+// "off": null;
+// - `reasoning_effort` IS accepted in the compatible mode, but only on some
+// families: qwen3.8 takes low | medium | xhigh (default xhigh, and it may
+// not be combined with `thinking_budget`), DeepSeek-V4 takes high | max
+// (plus low on the dated -0813 / -0731 snapshots), glm-5.3 takes
+// low | high | max. It is therefore off at the vendor level and enabled
+// per entry;
+// - explicit prompt caching uses Anthropic-style `cache_control`
+// ({"type": "ephemeral"}) and usage reports
+// `prompt_tokens_details.cached_tokens` plus
+// `cache_creation.ephemeral_5m_input_tokens`;
+// - tool_choice takes the full OpenAI set (none / auto / required / named
+// function), and parallel_tool_calls, response_format
+// (text | json_object | json_schema), stream_options.include_usage, seed,
+// temperature and top_p are all documented, so the protocol defaults
+// stand;
+// - embeddings are OpenAI-compatible under the same base
+// (/compatible-mode/v1/embeddings); text-embedding-v4 and -v3 default to
+// 1024 dimensions (https://help.aliyun.com/zh/model-studio/embedding);
+// - rerank is a separate DashScope-native endpoint
+// (/api/v1/services/rerank/text-rerank/text-rerank).
+//
+// unverified: the docs place qwen3-rerank on a different path than every
+// other rerank model (/compatible-api/v1/reranks instead of the native
+// text-rerank path this package defaults to), and WeKnora's DashScope rerank
+// client only speaks the native request shape. The single RerankBaseURL is
+// kept; qwen3-rerank needs an operator-supplied base URL until the client
+// learns the second shape
+// (https://help.aliyun.com/zh/model-studio/text-rerank-api).
+//
+// unverified: no page states whether `prompt_cache_key` is accepted, so the
+// protocol default (not sent) is kept.
+//
+// unverified: the context windows, max output tokens and prices of the Qwen
+// entries in models.json come from the Model Studio model pages, which the
+// public docs render behind a console table we cannot quote; they are left as
+// they were. The same holds for kimi-k3 / kimi-k2.6 / glm-5.3 hosted here and
+// for qwq-32b's "off": null, which the 仅思考模式 list does not spell out.
+package aliyun
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "aliyun"
+
+// BaseURL is the OpenAI-compatible mode used for chat, embedding and VLM.
+const BaseURL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+
+// RerankBaseURL is the DashScope-native text rerank endpoint.
+const RerankBaseURL = "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank"
+
+// AnthropicBaseURL is the documented Anthropic Messages facade. It is not the
+// default for this vendor; operators who want it configure it explicitly.
+const AnthropicBaseURL = "https://dashscope.aliyuncs.com/apps/anthropic"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Alibaba Cloud DashScope",
+ Names: map[string]string{"zh-CN": "阿里云 DashScope"},
+ Description: "qwen-plus, qwen3.8-max, deepseek-v4-pro, text-embedding-v4, qwen3-rerank, etc.",
+ Website: "https://bailian.console.aliyun.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 10,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"dashscope.aliyuncs.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: RerankBaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ // Explicit although it matches the protocol default, because
+ // this vendor's own parameter table deprecates the other
+ // field and the choice should be visible here.
+ MaxTokensField: catalog.Ptr("max_completion_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatEnableThinking),
+ ThinkingBudgetField: catalog.Ptr("thinking_budget"),
+ CacheControlFormat: catalog.Ptr("anthropic"),
+ // usage carries prompt_tokens_details.cached_tokens and
+ // cache_creation.ephemeral_5m_input_tokens.
+ PromptCacheAccounting: catalog.Ptr(true),
+ // reasoning_effort exists but only on the families that enable
+ // it per entry (qwen3.8, DeepSeek-V4, glm-5.3).
+ SupportsReasoningEffort: catalog.Ptr(false),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/all.go b/internal/models/vendors/all.go
new file mode 100644
index 000000000..2fa77dc76
--- /dev/null
+++ b/internal/models/vendors/all.go
@@ -0,0 +1,35 @@
+// Package vendors links every built-in vendor package so their init
+// functions register with the catalog. Import it for side effects from the
+// binary's entry point (and from tests that need the full catalog).
+package vendors
+
+import (
+ // Each vendor registers itself with the catalog in init.
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/aliyun"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/anthropic"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/azure_openai"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/deepseek"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/gemini"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/generic"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/gpustack"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/hunyuan"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/jina"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/litellm"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/lkeap"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/longcat"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/mimo"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/minimax"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/modelscope"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/moonshot"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/novita"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/nvidia"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/openai"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/openrouter"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/qianfan"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/qiniu"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/requesty"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/siliconflow"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/volcengine"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/weknoracloud"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors/zhipu"
+)
diff --git a/internal/models/vendors/anthropic/icon.svg b/internal/models/vendors/anthropic/icon.svg
new file mode 100644
index 000000000..62dc0db12
--- /dev/null
+++ b/internal/models/vendors/anthropic/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Claude</title><path d="M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z" fill="#D97757" fill-rule="nonzero"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/anthropic/models.json b/internal/models/vendors/anthropic/models.json
new file mode 100644
index 000000000..e1e684f23
--- /dev/null
+++ b/internal/models/vendors/anthropic/models.json
@@ -0,0 +1,17 @@
+{
+ "vendor": "anthropic",
+ "source": "https://docs.anthropic.com/en/docs/about-claude/models",
+ "models": [
+ {"id": "claude-fable-5-1", "name": "Claude Fable 5.1", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 10, "output": 50, "cache_read": 0.25, "cache_write": 12.5}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max"}},
+ {"id": "claude-opus-5", "name": "Claude Opus 5", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "source": "https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models", "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max"}},
+ {"id": "claude-sonnet-5", "name": "Claude Sonnet 5", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 2, "output": 10, "cache_read": 0.2, "cache_write": 2.5}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max"}},
+ {"id": "claude-fable-5", "name": "Claude Fable 5", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 10, "output": 50, "cache_read": 1, "cache_write": 12.5}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max"}},
+ {"id": "claude-opus-4-8", "name": "Claude Opus 4.8", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "source": "https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models", "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max"}},
+ {"id": "claude-opus-4-7", "name": "Claude Opus 4.7", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "source": "https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models", "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "xhigh", "max": "max"}},
+ {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "max", "max": "max"}},
+ {"id": "claude-opus-4-6", "name": "Claude Opus 4.6", "api": "anthropic-messages", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}, "compat": {"thinking_mode": "adaptive", "supports_effort": true}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "max", "max": "max"}},
+ {"id": "claude-opus-4-5", "name": "Claude Opus 4.5", "api": "anthropic-messages", "aliases": ["claude-opus-4-5-20251101"], "reasoning": true, "input": ["text", "image"], "context_window": 200000, "max_output_tokens": 64000, "cost": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}, "compat": {"supports_effort": true}, "source": "https://platform.claude.com/docs/en/build-with-claude/effort"},
+ {"id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5", "api": "anthropic-messages", "aliases": ["claude-sonnet-4-5-20250929"], "reasoning": true, "input": ["text", "image"], "context_window": 200000, "max_output_tokens": 64000, "cost": {"input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75}, "source": "https://platform.claude.com/docs/en/models/sonnet-4-5/overview"},
+ {"id": "claude-haiku-4-5", "name": "Claude Haiku 4.5", "api": "anthropic-messages", "aliases": ["claude-haiku-4-5-20251001"], "reasoning": true, "input": ["text", "image"], "context_window": 200000, "max_output_tokens": 64000, "cost": {"input": 1, "output": 5, "cache_read": 0.1, "cache_write": 1.25}}
+ ]
+}
diff --git a/internal/models/vendors/anthropic/vendor.go b/internal/models/vendors/anthropic/vendor.go
new file mode 100644
index 000000000..2c6c8f974
--- /dev/null
+++ b/internal/models/vendors/anthropic/vendor.go
@@ -0,0 +1,90 @@
+// Package anthropic registers Anthropic's native Messages API.
+//
+// Facts (https://platform.claude.com/docs/en/api/messages — docs.anthropic.com
+// now redirects there):
+// - authentication is the `x-api-key` header plus `anthropic-version`,
+// still 2023-06-01 in every current example;
+// - `max_tokens` is mandatory (the protocol default of 4096 applies when
+// the caller sets no budget);
+// - `output_config.effort` takes low | medium | high | xhigh | max and
+// nothing else — there is no "minimal" rung, so the vendor level map
+// folds minimal onto low
+// (https://platform.claude.com/docs/en/build-with-claude/effort).
+// `max` is listed for Fable 5.1 / Fable 5 / Opus 5 / Opus 4.8 / Opus 4.7 /
+// Opus 4.6 / Sonnet 5 / Sonnet 4.6; `xhigh` for the same set minus
+// Opus 4.6 and Sonnet 4.6, which is why those two map xhigh onto max;
+// - Claude 4.7 and later reject `thinking: {"type": "enabled"}` with a 400
+// and must use `{"type": "adaptive"}`; it is deprecated but still
+// accepted on the 4.6 generation, and it is the only mode on 4.5 and
+// earlier
+// (https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models);
+// - only Fable 5.1 / Fable 5 (and the limited-availability Mythos models)
+// are "always on" and reject `thinking: {"type": "disabled"}`, so only
+// those entries carry "off": null. Opus 5, Opus 4.8 and Opus 4.7 accept
+// "disabled" (Opus 5 at effort high or below, which is what a caller
+// asking for "off" gets because effort and off are mutually exclusive
+// here);
+// - Claude Opus 4.5 is the one extended-thinking-only model that also
+// accepts `output_config.effort`, so it carries supports_effort with
+// budget mode;
+// - temperature and top_p cannot be sent alongside thinking; prompt
+// caching uses `cache_control` breakpoints (including on tools), offers
+// a 1h TTL and reports cache usage;
+// - interleaved thinking still uses the `interleaved-thinking-2025-05-14`
+// beta header, and only in manual budget mode: adaptive models interleave
+// on their own and the Claude API ignores the header there.
+//
+// Unverified: Claude Mythos 5.1 / Mythos 5 / Mythos Preview are documented
+// but limited-availability, so they are left out of the catalog.
+package anthropic
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "anthropic"
+
+// BaseURL is the documented first-party endpoint.
+const BaseURL = "https://api.anthropic.com/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Anthropic",
+ Names: map[string]string{"zh-CN": "Anthropic"},
+ Description: "Claude models via the native Anthropic Messages API: " +
+ "claude-opus-5, claude-sonnet-5, claude-haiku-4-5, etc.",
+ Website: "https://console.anthropic.com",
+ Icon: icon,
+ API: api.APIAnthropicMessages,
+ Order: 32,
+ RequiresAuth: true,
+ Auth: catalog.AuthXAPIKey,
+ URLPatterns: []string{"api.anthropic.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ },
+ // Protocol defaults (budget-mode thinking, 2023-06-01 version) apply
+ // at vendor level; adaptive-effort models override per entry.
+ Compat: catalog.VendorCompat{},
+ // Anthropic's effort ladder has no "minimal" rung; fold it onto low
+ // for every model so a caller asking for minimal never sends a value
+ // the Messages API rejects.
+ ThinkingLevels: api.ThinkingLevelMap{api.ReasoningMinimal: api.StringPtr("low")},
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/azure_openai/icon.svg b/internal/models/vendors/azure_openai/icon.svg
new file mode 100644
index 000000000..b3df86558
--- /dev/null
+++ b/internal/models/vendors/azure_openai/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Azure</title><path d="M7.242 1.613A1.11 1.11 0 018.295.857h6.977L8.03 22.316a1.11 1.11 0 01-1.052.755h-5.43a1.11 1.11 0 01-1.053-1.466L7.242 1.613z" fill="url(#lobe-icons-azure-0-_R_0_)"></path><path d="M18.397 15.296H7.4a.51.51 0 00-.347.882l7.066 6.595c.206.192.477.298.758.298h6.226l-2.706-7.775z" fill="#0078D4"></path><path d="M15.272.857H7.497L0 23.071h7.775l1.596-4.73 5.068 4.73h6.665l-2.707-7.775h-7.998L15.272.857z" fill="url(#lobe-icons-azure-1-_R_0_)"></path><path d="M17.193 1.613a1.11 1.11 0 00-1.052-.756h-7.81.035c.477 0 .9.304 1.052.756l6.748 19.992a1.11 1.11 0 01-1.052 1.466h-.12 7.895a1.11 1.11 0 001.052-1.466L17.193 1.613z" fill="url(#lobe-icons-azure-2-_R_0_)"></path><defs><linearGradient gradientUnits="userSpaceOnUse" id="lobe-icons-azure-0-_R_0_" x1="8.247" x2="1.002" y1="1.626" y2="23.03"><stop stop-color="#114A8B"></stop><stop offset="1" stop-color="#0669BC"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id="lobe-icons-azure-1-_R_0_" x1="14.042" x2="12.324" y1="15.302" y2="15.888"><stop stop-opacity=".3"></stop><stop offset=".071" stop-opacity=".2"></stop><stop offset=".321" stop-opacity=".1"></stop><stop offset=".623" stop-opacity=".05"></stop><stop offset="1" stop-opacity="0"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id="lobe-icons-azure-2-_R_0_" x1="12.841" x2="20.793" y1="1.626" y2="22.814"><stop stop-color="#3CCBF4"></stop><stop offset="1" stop-color="#2892DF"></stop></linearGradient></defs></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/azure_openai/models.json b/internal/models/vendors/azure_openai/models.json
new file mode 100644
index 000000000..b21cd60f4
--- /dev/null
+++ b/internal/models/vendors/azure_openai/models.json
@@ -0,0 +1,17 @@
+{
+ "vendor": "azure_openai",
+ "source": "https://learn.microsoft.com/azure/ai-foundry/openai/how-to/reasoning",
+ "models": [
+ {"name": "GPT-6 deployments (reasoning, thinking always on)", "match": "gpt-6*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"name": "GPT-5 deployments (reasoning, no sampling parameters)", "match": "gpt-5*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low"}},
+ {"id": "gpt-5", "name": "GPT-5 deployment (thinking cannot be disabled)", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "xhigh": "high", "max": "high"}, "source": "https://developers.openai.com/api/docs/models/gpt-5"},
+ {"id": "gpt-5-mini", "name": "GPT-5 Mini deployment (thinking cannot be disabled)", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "xhigh": "high", "max": "high"}, "source": "https://developers.openai.com/api/docs/models/gpt-5-mini"},
+ {"id": "gpt-5-nano", "name": "GPT-5 Nano deployment (thinking cannot be disabled)", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "xhigh": "high", "max": "high"}, "source": "https://developers.openai.com/api/docs/models/gpt-5-nano"},
+ {"name": "o1 deployments (always-on reasoning)", "match": "o1*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"name": "o3 deployments (always-on reasoning)", "match": "o3*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"name": "o4 deployments (always-on reasoning)", "match": "o4*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"name": "GPT-4o deployments", "match": "gpt-4o*", "reasoning": false, "input": ["text", "image"]},
+ {"name": "GPT-4.1 deployments", "match": "gpt-4.1*", "reasoning": false, "input": ["text", "image"]},
+ {"name": "text-embedding-3 deployments", "match": "text-embedding-3*", "type": "Embedding"}
+ ]
+}
diff --git a/internal/models/vendors/azure_openai/vendor.go b/internal/models/vendors/azure_openai/vendor.go
new file mode 100644
index 000000000..b903d5af4
--- /dev/null
+++ b/internal/models/vendors/azure_openai/vendor.go
@@ -0,0 +1,192 @@
+// Package azureopenai registers Azure OpenAI (Azure AI Foundry).
+//
+// Facts (https://learn.microsoft.com/azure/ai-foundry/openai/api-version-lifecycle
+// and https://learn.microsoft.com/azure/ai-foundry/openai/how-to/reasoning):
+// - there are two request shapes. The v1 shape,
+// https://{resource}.openai.azure.com/openai/v1/chat/completions with the
+// deployment name in the body's `model` field, is the current GA data
+// plane and takes no api-version at all: "api-version is no longer a
+// required parameter with the v1 GA API". Every example on the reasoning
+// how-to page (last updated 2026-09-16) uses it. The legacy shape,
+// .../openai/deployments/{deployment}/chat/completions?api-version=...,
+// is still served but its newest GA api-version is 2024-10-21, which
+// predates `max_completion_tokens` (2024-09-01-preview) and
+// `reasoning_effort` (2024-12-01-preview) — so a reasoning deployment
+// cannot work on it. The Endpoint hook therefore emits the v1 shape by
+// default and only falls back to the legacy shape when the operator
+// explicitly fills the api_version extra field;
+// - authentication is the `api-key` header, not a bearer token (Entra ID
+// bearer tokens are the other documented option and are not modelled);
+// - the model name stored on the row is the deployment name, so the
+// catalog only carries family patterns (gpt-6*, gpt-5*, o1*, o3*, o4*,
+// ...) that mirror the OpenAI vendor: reasoning deployments use
+// `max_completion_tokens`, `reasoning_effort`, the developer role, and
+// reject temperature, top_p, presence_penalty, frequency_penalty,
+// logprobs, top_logprobs, logit_bias and max_tokens;
+// - `reasoning_effort` accepts none | minimal | low | medium | high |
+// xhigh | max, model-dependent; `xhigh` is limited to GPT-6, GPT-5.6,
+// GPT-5.5, GPT-5.4 and gpt-5.1-codex-max, `max` to GPT-6 and GPT-5.6 on
+// the Responses API only, and `minimal` to the original GPT-5 models.
+// Because a deployment name says nothing about which model backs it, the
+// family patterns stay on the conservative subset. The exception is a
+// deployment named exactly gpt-5, gpt-5-mini or gpt-5-nano, which is
+// overwhelmingly the model of that name: those three carry their own
+// entries mirroring the openai vendor, because the original GPT-5 trio
+// supports "Reasoning.effort ... minimal, low, medium, and high"
+// (https://developers.openai.com/api/docs/models/gpt-5) and rejects
+// `none`, unlike GPT-5.1 and later, which the gpt-5* pattern covers;
+// - `store: false`, `prompt_cache_key` and cached-token usage behave as
+// on api.openai.com.
+//
+// # The one path rule
+//
+// A stored row picks its data plane from `extra_config.api_version` alone,
+// and chat, VLM and embedding all apply the same rule to the same row:
+//
+// api_version empty -> {base}/openai/v1{path}, no api-version, the
+// deployment name travelling in the body's
+// `model` field;
+// api_version non-empty -> {base}/openai/deployments/{deployment}{path}
+// ?api-version={value}.
+//
+// Chat and VLM reach this through the Endpoint hook below (VLM is built on
+// the chat client); embedding applies it in azureEmbeddingURL in
+// internal/models/embedding/azure_openai.go, which calls this same hook.
+//
+// The v1 default is not a guess. The v1 API reference is published at
+// "API Version: v1" with server {endpoint}/openai/v1 and covers the paths
+// this vendor uses, embeddings included
+// (https://learn.microsoft.com/rest/api/microsoft-foundry/azureopenai/embeddings:
+// "POST {endpoint}/openai/v1/embeddings", with `api-version` marked
+// "Required: No" and defaulting to v1). The lifecycle page's prerequisites
+// for the v1 API are only a subscription, a Foundry or Azure OpenAI resource
+// in a supported region, and at least one model deployment — there is no
+// resource-level switch to flip, and `base_url` is documented to accept the
+// https://{resource}.openai.azure.com/openai/v1/ form. The dated path is not
+// a parallel modern option: 2024-10-21 is still the newest GA api-version
+// there, so the reasoning surface this vendor advertises
+// (`max_completion_tokens`, 2024-09-01-preview; `reasoning_effort`,
+// 2024-12-01-preview) exists on no GA dated version at all.
+//
+// Behaviour change for existing rows: before the catalog, a row with no
+// api_version used the dated deployments path (the Go SDK's built-in Azure
+// default for chat and VLM, a hard-coded 2024-10-21 for embedding). Those
+// rows now use /openai/v1. This is deliberate and documented in
+// website-docs/03-features/06-models.md; an operator whose gateway only
+// serves the dated path (an API Management front end, a sovereign cloud)
+// restores the exact previous shape by filling the api_version extra field.
+package azureopenai
+
+import (
+ _ "embed"
+ "net/url"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "azure_openai"
+
+// BaseURL is the resource endpoint template; the operator replaces
+// {resource} with their own resource name.
+const BaseURL = "https://{resource}.openai.azure.com"
+
+// LegacyAPIVersion is the newest GA api-version of the dated data-plane
+// inference spec. It is only used when the operator explicitly asks for the
+// legacy deployments path; it predates reasoning_effort, so reasoning
+// deployments need a preview version such as 2025-04-01-preview instead.
+const LegacyAPIVersion = "2024-10-21"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Azure OpenAI",
+ Names: map[string]string{"zh-CN": "Azure OpenAI"},
+ Description: "gpt-4o, gpt-5, o3, text-embedding-3-large deployments, etc.",
+ Website: "https://ai.azure.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 31,
+ RequiresAuth: true,
+ Auth: catalog.AuthAPIKeyHeader,
+ URLPatterns: []string{"openai.azure.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ // ASR is deliberately absent: Azure serves Whisper, but
+ // internal/models/asr builds every remote client with a plain
+ // OpenAI config (Bearer auth, {base}/audio/transcriptions) and has
+ // no provider or extra-config field to route through this vendor's
+ // api-key header and deployments path. Advertising the type would
+ // let the picker create a row that fails at first use. The Endpoint
+ // hook below already knows the ASR path, so re-adding the type is a
+ // one-line change once asr.Config carries the provider.
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeVLLM,
+ },
+ ExtraFields: []catalog.ExtraField{
+ {
+ Key: catalog.ExtraAPIVersion,
+ Label: "API Version (legacy deployments path)",
+ Labels: map[string]string{"zh-CN": "API 版本(旧版 deployments 路径)"},
+ Type: "string",
+ Required: false,
+ // Empty means the v1 GA data plane, which takes no
+ // api-version. A value switches back to the dated
+ // /openai/deployments/... path.
+ Placeholder: "leave empty for /openai/v1, or e.g. 2025-04-01-preview",
+ },
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatOpenAI),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ SupportsDeveloperRole: catalog.Ptr(true),
+ SupportsStore: catalog.Ptr(true),
+ PromptCacheKey: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ Endpoint: func(r catalog.EndpointRequest) (string, map[string]string) {
+ var path string
+ switch r.ModelType {
+ case types.ModelTypeEmbedding:
+ path = "/embeddings"
+ case types.ModelTypeASR:
+ path = "/audio/transcriptions"
+ default:
+ if r.API == api.APIOpenAIResponses {
+ path = "/responses"
+ } else {
+ path = "/chat/completions"
+ }
+ }
+ root := strings.TrimRight(r.BaseURL, "/")
+ // An explicit api-version selects the legacy deployments path;
+ // otherwise use the v1 GA data plane, which carries the
+ // deployment name in the body instead of the URL.
+ if version := strings.TrimSpace(r.Extra[catalog.ExtraAPIVersion]); version != "" {
+ legacy := root + "/openai/deployments/" + url.PathEscape(r.Model) + path
+ return legacy, map[string]string{"api-version": version}
+ }
+ if strings.HasSuffix(root, "/openai/v1") {
+ return root + path, nil
+ }
+ return root + "/openai/v1" + path, nil
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/deepseek/icon.svg b/internal/models/vendors/deepseek/icon.svg
new file mode 100644
index 000000000..3fc230240
--- /dev/null
+++ b/internal/models/vendors/deepseek/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>DeepSeek</title><path d="M23.748 4.482c-.254-.124-.364.113-.512.234-.051.039-.094.09-.137.136-.372.397-.806.657-1.373.626-.829-.046-1.537.214-2.163.848-.133-.782-.575-1.248-1.247-1.548-.352-.156-.708-.311-.955-.65-.172-.241-.219-.51-.305-.774-.055-.16-.11-.323-.293-.35-.2-.031-.278.136-.356.276-.313.572-.434 1.202-.422 1.84.027 1.436.633 2.58 1.838 3.393.137.093.172.187.129.323-.082.28-.18.552-.266.833-.055.179-.137.217-.329.14a5.526 5.526 0 01-1.736-1.18c-.857-.828-1.631-1.742-2.597-2.458a11.365 11.365 0 00-.689-.471c-.985-.957.13-1.743.388-1.836.27-.098.093-.432-.779-.428-.872.004-1.67.295-2.687.684a3.055 3.055 0 01-.465.137 9.597 9.597 0 00-2.883-.102c-1.885.21-3.39 1.102-4.497 2.623C.082 8.606-.231 10.684.152 12.85c.403 2.284 1.569 4.175 3.36 5.653 1.858 1.533 3.997 2.284 6.438 2.14 1.482-.085 3.133-.284 4.994-1.86.47.234.962.327 1.78.397.63.059 1.236-.03 1.705-.128.735-.156.684-.837.419-.961-2.155-1.004-1.682-.595-2.113-.926 1.096-1.296 2.746-2.642 3.392-7.003.05-.347.007-.565 0-.845-.004-.17.035-.237.23-.256a4.173 4.173 0 001.545-.475c1.396-.763 1.96-2.015 2.093-3.517.02-.23-.004-.467-.247-.588zM11.581 18c-2.089-1.642-3.102-2.183-3.52-2.16-.392.024-.321.471-.235.763.09.288.207.486.371.739.114.167.192.416-.113.603-.673.416-1.842-.14-1.897-.167-1.361-.802-2.5-1.86-3.301-3.307-.774-1.393-1.224-2.887-1.298-4.482-.02-.386.093-.522.477-.592a4.696 4.696 0 011.529-.039c2.132.312 3.946 1.265 5.468 2.774.868.86 1.525 1.887 2.202 2.891.72 1.066 1.494 2.082 2.48 2.914.348.292.625.514.891.677-.802.09-2.14.11-3.054-.614zm1-6.44a.306.306 0 01.415-.287.302.302 0 01.2.288.306.306 0 01-.31.307.303.303 0 01-.304-.308zm3.11 1.596c-.2.081-.399.151-.59.16a1.245 1.245 0 01-.798-.254c-.274-.23-.47-.358-.552-.758a1.73 1.73 0 01.016-.588c.07-.327-.008-.537-.239-.727-.187-.156-.426-.199-.688-.199a.559.559 0 01-.254-.078c-.11-.054-.2-.19-.114-.358.028-.054.16-.186.192-.21.356-.202.767-.136 1.146.016.352.144.618.408 1.001.782.391.451.462.576.685.914.176.265.336.537.445.848.067.195-.019.354-.25.452z" fill="#4D6BFE"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/deepseek/models.json b/internal/models/vendors/deepseek/models.json
new file mode 100644
index 000000000..bb92aabd3
--- /dev/null
+++ b/internal/models/vendors/deepseek/models.json
@@ -0,0 +1,59 @@
+{
+ "vendor": "deepseek",
+ "source": "https://api-docs.deepseek.com/quick_start/pricing",
+ "models": [
+ {
+ "id": "deepseek-v4-pro",
+ "name": "DeepSeek V4 Pro",
+ "reasoning": true,
+ "input": ["text"],
+ "context_window": 1000000,
+ "max_output_tokens": 384000,
+ "cost": {"input": 0.66, "output": 1.98, "cache_read": 0.022},
+ "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"},
+ "source": "https://api-docs.deepseek.com/quick_start/pricing"
+ },
+ {
+ "id": "deepseek-flash",
+ "name": "DeepSeek V4.1 Flash",
+ "reasoning": true,
+ "input": ["text", "image"],
+ "context_window": 1000000,
+ "max_output_tokens": 384000,
+ "cost": {"input": 0.15, "output": 0.6, "cache_read": 0.003},
+ "source": "https://api-docs.deepseek.com/quick_start/pricing"
+ },
+ {
+ "id": "deepseek-v4-flash",
+ "name": "DeepSeek V4 Flash (retired name, served by V4.1 Flash)",
+ "deprecated": true,
+ "reasoning": true,
+ "input": ["text", "image"],
+ "context_window": 1000000,
+ "max_output_tokens": 384000,
+ "cost": {"input": 0.15, "output": 0.6, "cache_read": 0.003},
+ "source": "https://api-docs.deepseek.com/quick_start/pricing"
+ },
+ {
+ "id": "deepseek-chat",
+ "name": "DeepSeek Chat (retired 2026-07-24, non-thinking alias)",
+ "deprecated": true,
+ "reasoning": false,
+ "input": ["text"],
+ "context_window": 128000,
+ "max_output_tokens": 8192,
+ "source": "https://api-docs.deepseek.com/news/news260424/"
+ },
+ {
+ "id": "deepseek-reasoner",
+ "name": "DeepSeek Reasoner (retired 2026-07-24, thinking alias)",
+ "deprecated": true,
+ "reasoning": true,
+ "input": ["text"],
+ "context_window": 128000,
+ "max_output_tokens": 65536,
+ "thinking_levels": {"off": null},
+ "source": "https://api-docs.deepseek.com/news/news260424/"
+ }
+ ]
+}
diff --git a/internal/models/vendors/deepseek/vendor.go b/internal/models/vendors/deepseek/vendor.go
new file mode 100644
index 000000000..792e30f28
--- /dev/null
+++ b/internal/models/vendors/deepseek/vendor.go
@@ -0,0 +1,109 @@
+// Package deepseek registers DeepSeek's first-party API.
+//
+// Facts (https://api-docs.deepseek.com/api/create-chat-completion and
+// https://api-docs.deepseek.com/guides/thinking_mode):
+// - output cap is `max_tokens`, "between 1 and 384K (393216)"; the default
+// is 8K without thinking, 64K with it, 128K at `reasoning_effort: max`.
+// `max_completion_tokens` is not part of the reference;
+// - thinking is switched with `thinking: {"type": "enabled"|"disabled"}`
+// (the documented default is `enabled`) and graded with
+// `reasoning_effort`, whose values are none | low | high | max. `none`
+// is the effort spelling of "off"; on this OpenAI surface the protocol
+// switches thinking off with `thinking.type = disabled` instead, which
+// is what the reference documents;
+// - temperature (0..2) "has no effect in thinking mode" but is still
+// accepted, so sampling parameters keep being sent; `top_p` only takes
+// effect in thinking mode, where values below 0.95 are treated as 0.95;
+// presence_penalty / frequency_penalty are "no longer supported" and are
+// silently dropped by the vendor;
+// - tool_choice accepts none / auto / required / a named function, i.e. the
+// plain OpenAI set, so no restriction is configured here;
+// - assistant turns must replay `reasoning_content` when the request
+// carries `tools`; without `tools` the vendor ignores it;
+// - usage reports `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
+// next to `prompt_tokens_details.cached_tokens`;
+// - DeepSeek also serves an Anthropic Messages surface at
+// https://api.deepseek.com/anthropic and a Responses surface on the same
+// host (https://api-docs.deepseek.com/guides/anthropic_api and
+// .../guides/responses_api). The documented default, and what this
+// package configures, is OpenAI Chat Completions.
+//
+// unverified: the current docs give the base URL as https://api.deepseek.com
+// with no version segment; the /v1 alias this package uses (and that
+// provider.DeepSeekBaseURL and stored model rows carry) is no longer spelled
+// out in them, and nothing documents it being rejected, so it is kept.
+//
+// Prices in models.json are the USD off-peak rates of
+// https://api-docs.deepseek.com/quick_start/pricing (peak is exactly 2x);
+// `cost.input` is the cache-miss rate and `cost.cache_read` the cache-hit one.
+//
+// unverified: `parallel_tool_calls`, `prompt_cache_key` and
+// `stream_options.include_usage` semantics beyond the field itself are not
+// described in the reference; the protocol defaults are kept.
+//
+// unverified: deepseek-v4-pro carries a per-model override that lifts
+// minimal / low to `high`. The reference enumerates low / high / max for the
+// API as a whole without restricting them per model, so the override is kept
+// but nothing documents it.
+package deepseek
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "deepseek"
+
+// BaseURL is the documented first-party endpoint.
+const BaseURL = "https://api.deepseek.com/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "DeepSeek",
+ Names: map[string]string{"zh-CN": "DeepSeek 深度求索"},
+ Description: "deepseek-flash, deepseek-v4-pro",
+ Website: "https://platform.deepseek.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 30,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"api.deepseek.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ },
+ ModelTypes: []types.ModelType{types.ModelTypeKnowledgeQA},
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ SupportsStore: catalog.Ptr(false),
+ },
+ },
+ // DeepSeek grades effort as low / high / max (plus `none`, which the
+ // protocol expresses as thinking.type=disabled): medium clamps up to
+ // high, minimal down to low, xhigh up to max.
+ ThinkingLevels: api.ThinkingLevelMap{
+ api.ReasoningMinimal: api.StringPtr("low"),
+ api.ReasoningLow: api.StringPtr("low"),
+ api.ReasoningMedium: api.StringPtr("high"),
+ api.ReasoningHigh: api.StringPtr("high"),
+ api.ReasoningXHigh: api.StringPtr("max"),
+ api.ReasoningMax: api.StringPtr("max"),
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/gemini/icon.svg b/internal/models/vendors/gemini/icon.svg
new file mode 100644
index 000000000..62681dfa7
--- /dev/null
+++ b/internal/models/vendors/gemini/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Gemini</title><path d="M20.616 10.835a14.147 14.147 0 01-4.45-3.001 14.111 14.111 0 01-3.678-6.452.503.503 0 00-.975 0 14.134 14.134 0 01-3.679 6.452 14.155 14.155 0 01-4.45 3.001c-.65.28-1.318.505-2.002.678a.502.502 0 000 .975c.684.172 1.35.397 2.002.677a14.147 14.147 0 014.45 3.001 14.112 14.112 0 013.679 6.453.502.502 0 00.975 0c.172-.685.397-1.351.677-2.003a14.145 14.145 0 013.001-4.45 14.113 14.113 0 016.453-3.678.503.503 0 000-.975 13.245 13.245 0 01-2.003-.678z" fill="#3186FF"></path><path d="M20.616 10.835a14.147 14.147 0 01-4.45-3.001 14.111 14.111 0 01-3.678-6.452.503.503 0 00-.975 0 14.134 14.134 0 01-3.679 6.452 14.155 14.155 0 01-4.45 3.001c-.65.28-1.318.505-2.002.678a.502.502 0 000 .975c.684.172 1.35.397 2.002.677a14.147 14.147 0 014.45 3.001 14.112 14.112 0 013.679 6.453.502.502 0 00.975 0c.172-.685.397-1.351.677-2.003a14.145 14.145 0 013.001-4.45 14.113 14.113 0 016.453-3.678.503.503 0 000-.975 13.245 13.245 0 01-2.003-.678z" fill="url(#lobe-icons-gemini-0-_R_0_)"></path><path d="M20.616 10.835a14.147 14.147 0 01-4.45-3.001 14.111 14.111 0 01-3.678-6.452.503.503 0 00-.975 0 14.134 14.134 0 01-3.679 6.452 14.155 14.155 0 01-4.45 3.001c-.65.28-1.318.505-2.002.678a.502.502 0 000 .975c.684.172 1.35.397 2.002.677a14.147 14.147 0 014.45 3.001 14.112 14.112 0 013.679 6.453.502.502 0 00.975 0c.172-.685.397-1.351.677-2.003a14.145 14.145 0 013.001-4.45 14.113 14.113 0 016.453-3.678.503.503 0 000-.975 13.245 13.245 0 01-2.003-.678z" fill="url(#lobe-icons-gemini-1-_R_0_)"></path><path d="M20.616 10.835a14.147 14.147 0 01-4.45-3.001 14.111 14.111 0 01-3.678-6.452.503.503 0 00-.975 0 14.134 14.134 0 01-3.679 6.452 14.155 14.155 0 01-4.45 3.001c-.65.28-1.318.505-2.002.678a.502.502 0 000 .975c.684.172 1.35.397 2.002.677a14.147 14.147 0 014.45 3.001 14.112 14.112 0 013.679 6.453.502.502 0 00.975 0c.172-.685.397-1.351.677-2.003a14.145 14.145 0 013.001-4.45 14.113 14.113 0 016.453-3.678.503.503 0 000-.975 13.245 13.245 0 01-2.003-.678z" fill="url(#lobe-icons-gemini-2-_R_0_)"></path><defs><linearGradient gradientUnits="userSpaceOnUse" id="lobe-icons-gemini-0-_R_0_" x1="7" x2="11" y1="15.5" y2="12"><stop stop-color="#08B962"></stop><stop offset="1" stop-color="#08B962" stop-opacity="0"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id="lobe-icons-gemini-1-_R_0_" x1="8" x2="11.5" y1="5.5" y2="11"><stop stop-color="#F94543"></stop><stop offset="1" stop-color="#F94543" stop-opacity="0"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id="lobe-icons-gemini-2-_R_0_" x1="3.5" x2="17.5" y1="13.5" y2="12"><stop stop-color="#FABC12"></stop><stop offset=".46" stop-color="#FABC12" stop-opacity="0"></stop></linearGradient></defs></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/gemini/models.json b/internal/models/vendors/gemini/models.json
new file mode 100644
index 000000000..028129309
--- /dev/null
+++ b/internal/models/vendors/gemini/models.json
@@ -0,0 +1,20 @@
+{
+ "vendor": "gemini",
+ "source": "https://ai.google.dev/gemini-api/docs/thinking",
+ "models": [
+ {"name": "Gemini 3 family (thinkingLevel)", "match": "gemini-3*", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.8-flash", "name": "Gemini 3.8 Flash", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.75, "output": 3.75, "cache_read": 0.075}, "compat": {"thinking_mode": "level"}, "source": "https://ai.google.dev/gemini-api/docs/thinking", "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.7-flash", "name": "Gemini 3.7 Flash", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.75, "output": 3.75, "cache_read": 0.075}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.6-flash", "name": "Gemini 3.6 Flash", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.75, "output": 3.75, "cache_read": 0.075}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "minimal", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.5-flash", "name": "Gemini 3.5 Flash", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 1.5, "output": 9, "cache_read": 0.15}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "minimal", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.5-flash-lite", "name": "Gemini 3.5 Flash Lite", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.3, "output": 2.5, "cache_read": 0.03}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "minimal", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro Preview", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 2, "output": 12, "cache_read": 0.2}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3.1-flash-lite", "name": "Gemini 3.1 Flash Lite", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.25, "output": 1.5, "cache_read": 0.025}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "minimal", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-3-flash-preview", "name": "Gemini 3 Flash Preview", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.5, "output": 3, "cache_read": 0.05}, "compat": {"thinking_mode": "level"}, "thinking_levels": {"off": null, "minimal": "minimal", "low": "low", "medium": "medium", "high": "high", "xhigh": "high", "max": "high"}},
+ {"id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 1.25, "output": 10, "cache_read": 0.125}, "compat": {"thinking_mode": "budget"}, "thinking_levels": {"off": null}},
+ {"id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.3, "output": 2.5, "cache_read": 0.03}, "compat": {"thinking_mode": "budget"}},
+ {"id": "gemini-2.5-flash-lite", "name": "Gemini 2.5 Flash Lite", "api": "google-generative-ai", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.1, "output": 0.4, "cache_read": 0.01}, "compat": {"thinking_mode": "budget"}},
+ {"id": "gemini-embedding-001", "name": "Gemini Embedding 001", "type": "Embedding", "dimension": 3072, "context_window": 2048, "cost": {"input": 0.15, "output": 0}, "source": "https://ai.google.dev/gemini-api/docs/embeddings"},
+ {"id": "gemini-embedding-2", "name": "Gemini Embedding 2", "aliases": ["gemini-embedding-2-preview"], "type": "Embedding", "input": ["text", "image", "audio", "video"], "dimension": 3072, "context_window": 8192, "cost": {"input": 0.2, "output": 0}, "source": "https://ai.google.dev/gemini-api/docs/embeddings"}
+ ]
+}
diff --git a/internal/models/vendors/gemini/vendor.go b/internal/models/vendors/gemini/vendor.go
new file mode 100644
index 000000000..fb36f668f
--- /dev/null
+++ b/internal/models/vendors/gemini/vendor.go
@@ -0,0 +1,119 @@
+// Package gemini registers Google's Gemini API.
+//
+// Facts (https://ai.google.dev/gemini-api/docs/thinking):
+// - the native protocol is generateContent under
+// https://generativelanguage.googleapis.com/v1beta with the
+// `x-goog-api-key` header;
+// - the two thinking knobs are generation-specific and mutually
+// exclusive: Gemini 3.x takes `thinkingConfig.thinkingLevel`, Gemini 2.5
+// takes `thinkingConfig.thinkingBudget` and ignores/rejects
+// thinkingLevel; sending both in one call is a 400. The per-model level
+// sets differ too — 3.8 Flash, 3.7 Flash and 3.1 Pro accept
+// low | medium | high, 3.6 Flash, 3.5 Flash, 3.5 Flash Lite, 3.1 Flash
+// Lite and 3 Flash Preview add minimal, and 3 Pro Preview accepts only
+// low | high, which is what the conservative gemini-3* family entry
+// assumes;
+// - no thinkingLevel value turns thinking off, so every Gemini 3 entry is
+// "off": null. On 2.5, Pro is the exception that cannot be switched off
+// (its budget must be 128..32768, or -1 for dynamic) while Flash and
+// Flash Lite accept budget 0; the vendor budget ladder starts at 128 for
+// that reason and tops out at 32768;
+// - pointing base_url at https://generativelanguage.googleapis.com/v1beta/openai
+// keeps the OpenAI-compatible Chat Completions protocol (Resolve detects
+// the /openai suffix) and switches the credential to
+// `Authorization: Bearer`, the only form that facade documents
+// (https://ai.google.dev/gemini-api/docs/openai). Every row created
+// before the native protocol became the default carries exactly that base
+// URL, so this is the auth those rows have always used; on that facade
+// `reasoning_effort` is translated to
+// thinking_level or thinking_budget per model,
+// `extra_body.google.thinking_config` carries include_thoughts, and usage
+// reports cached tokens (the OpenAICompletions vendor compat below);
+// - embeddings are served natively and on the facade:
+// gemini-embedding-001 defaults to 3072 dimensions over 2048 input
+// tokens, gemini-embedding-2 to 3072 over 8192 and accepts multimodal
+// input (https://ai.google.dev/gemini-api/docs/embeddings).
+//
+// Unverified:
+// - `extra_content` on tool calls is not named anywhere in the current
+// OpenAI-compat guide; the tool_call_extra_fields entry is kept because
+// dropping an opaque round-trip field is the riskier direction.
+// - gemini-embedding-2 is listed as `gemini-embedding-2` in the embeddings
+// guide but as `gemini-embedding-2-preview` on the models page and in the
+// OpenAI-compat samples, so both spellings resolve to one entry.
+// - gemini-3.1-flash-lite is on the models page but absent from the
+// thinking guide's level table, so its minimal rung is an assumption
+// carried over from the other Flash Lite tiers.
+package gemini
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "gemini"
+
+// BaseURL is the native Gemini API endpoint.
+const BaseURL = "https://generativelanguage.googleapis.com/v1beta"
+
+// OpenAICompatBaseURL keeps the OpenAI Chat Completions protocol.
+const OpenAICompatBaseURL = BaseURL + "/openai"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Google Gemini",
+ Names: map[string]string{"zh-CN": "Google Gemini"},
+ Description: "gemini-3.8-flash, gemini-3.1-pro-preview, gemini-2.5-pro, gemini-embedding-2, etc. " +
+ "Native generateContent by default; set base_url to " + OpenAICompatBaseURL +
+ " to keep the OpenAI-compatible protocol.",
+ Descriptions: map[string]string{
+ "zh-CN": "gemini-3.8-flash, gemini-3.1-pro-preview, gemini-2.5-pro, gemini-embedding-2 等。" +
+ "默认走原生 generateContent 协议;将 base_url 指向 " + OpenAICompatBaseURL + " 可继续使用 OpenAI 兼容协议。",
+ },
+ Website: "https://aistudio.google.com",
+ Icon: icon,
+ API: api.APIGoogleGenerativeAI,
+ Order: 33,
+ RequiresAuth: true,
+ Auth: catalog.AuthGoogleAPIKey,
+ // The OpenAI-compatible facade documents only Authorization: Bearer.
+ // Sending x-goog-api-key there would change the credential of every
+ // row stored before the native protocol became the default — they all
+ // carry the .../v1beta/openai base URL.
+ AuthByAPI: map[api.API]catalog.AuthStyle{
+ api.APIOpenAICompletions: catalog.AuthBearer,
+ },
+ URLPatterns: []string{"generativelanguage.googleapis.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ },
+ Compat: catalog.VendorCompat{
+ // Used when the operator points base_url at the /openai facade.
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ToolCallExtraFields: []string{"extra_content"},
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatOpenAI),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ // Native protocol keeps the generativelanguage defaults.
+ GoogleGenerativeAI: catalog.GoogleGenerativeAICompat{},
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/generic/icon.svg b/internal/models/vendors/generic/icon.svg
new file mode 100644
index 000000000..47333fdf1
--- /dev/null
+++ b/internal/models/vendors/generic/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="#64748B" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8.5 7.5 3.5 12l5 4.5"/><path d="M15.5 7.5 20.5 12l-5 4.5"/><path d="M13.5 5.5 10.5 18.5"/></svg>
diff --git a/internal/models/vendors/generic/models.json b/internal/models/vendors/generic/models.json
new file mode 100644
index 000000000..172c361b5
--- /dev/null
+++ b/internal/models/vendors/generic/models.json
@@ -0,0 +1,29 @@
+{
+ "vendor": "generic",
+ "source": "https://platform.openai.com/docs/guides/reasoning",
+ "models": [
+ {
+ "match": "gpt-5*",
+ "reasoning": true,
+ "compat": {"max_tokens_field": "max_completion_tokens", "supports_temperature": false, "thinking_format": "openai", "supports_reasoning_effort": true}
+ },
+ {
+ "match": "o1*",
+ "reasoning": true,
+ "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"},
+ "compat": {"max_tokens_field": "max_completion_tokens", "supports_temperature": false, "thinking_format": "openai", "supports_reasoning_effort": true}
+ },
+ {
+ "match": "o3*",
+ "reasoning": true,
+ "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"},
+ "compat": {"max_tokens_field": "max_completion_tokens", "supports_temperature": false, "thinking_format": "openai", "supports_reasoning_effort": true}
+ },
+ {
+ "match": "o4*",
+ "reasoning": true,
+ "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"},
+ "compat": {"max_tokens_field": "max_completion_tokens", "supports_temperature": false, "thinking_format": "openai", "supports_reasoning_effort": true}
+ }
+ ]
+}
diff --git a/internal/models/vendors/generic/vendor.go b/internal/models/vendors/generic/vendor.go
new file mode 100644
index 000000000..e6a881c69
--- /dev/null
+++ b/internal/models/vendors/generic/vendor.go
@@ -0,0 +1,94 @@
+// Package generic registers the catch-all vendor for any OpenAI-compatible
+// endpoint (vLLM, SGLang, Xinference, Ollama's OpenAI facade, ...).
+//
+// Facts (no single upstream; the settings follow the vLLM / SGLang
+// conventions, https://docs.vllm.ai/en/latest/features/reasoning_outputs.html
+// and https://docs.sglang.io/basic_usage/openai_api_completions.html):
+// - output cap stays `max_tokens`. vLLM now marks it deprecated in favour
+// of `max_completion_tokens` but still accepts it, while SGLang,
+// GPUStack and Xinference document only `max_tokens`, so it remains the
+// one field every runtime behind this vendor understands;
+// - thinking is switched through `chat_template_kwargs.enable_thinking`,
+// which both servers document as the per-request override. vLLM also
+// accepts a top-level `reasoning_effort` with exactly this project's
+// ladder (none | minimal | low | medium | high | xhigh | max) and
+// injects enable_thinking from it, but SGLang only says effort "follows
+// a separate normalization path", so the chat-template switch is the
+// portable choice and operators on vLLM can opt into effort per model;
+// - the gpt-5*/o1*/o3*/o4* family entries stay: a relay parked behind this
+// vendor is the common way to front OpenAI, and those families need
+// max_completion_tokens, reasoning_effort and no sampling parameters
+// whatever the hop count;
+// - no default base URL: the operator must supply one (Validate enforces
+// it) and a key is optional because local deployments run without one;
+// - no URL patterns: DetectByURL falls back to this vendor when nothing
+// else matches.
+//
+// Unverified: `enable_thinking` is not a portable key. vLLM documents
+// `{"thinking": true}` for IBM Granite and SGLang documents the same for
+// DeepSeek-V3, so a non-Qwen template will ignore the switch this vendor
+// sends rather than reject it. Per-model chat-template keys are not
+// expressible in the compat model.
+package generic
+
+import (
+ _ "embed"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows. It must equal
+// catalog.GenericID because Resolve degrades unknown vendors to it.
+const ID = catalog.GenericID
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Custom (OpenAI-compatible)",
+ Names: map[string]string{"zh-CN": "自定义 (OpenAI兼容接口)"},
+ Description: "Any OpenAI-compatible endpoint (vLLM, SGLang, Xinference, Ollama, ...)",
+ Descriptions: map[string]string{"zh-CN": "任意 OpenAI 兼容接口(vLLM、SGLang、Xinference、Ollama 等)"},
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 0,
+ RequiresAuth: false,
+ Auth: catalog.AuthBearer,
+ DefaultBaseURLs: map[types.ModelType]string{},
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ types.ModelTypeASR,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatChatTemplateKwargs),
+ },
+ },
+ Validate: func(cfg *catalog.Config) error {
+ if cfg == nil {
+ return fmt.Errorf("config is nil")
+ }
+ if strings.TrimSpace(cfg.BaseURL) == "" {
+ return fmt.Errorf("base URL is required for generic provider")
+ }
+ if strings.TrimSpace(cfg.ModelName) == "" {
+ return fmt.Errorf("model name is required")
+ }
+ return nil
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/gpustack/icon.svg b/internal/models/vendors/gpustack/icon.svg
new file mode 100644
index 000000000..71cffc890
--- /dev/null
+++ b/internal/models/vendors/gpustack/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><rect width="24" height="24" rx="5" fill="#0F766E"/><text x="12" y="16" font-family="sans-serif" font-weight="700" font-size="10" fill="#FFFFFF" text-anchor="middle">GS</text></svg>
diff --git a/internal/models/vendors/gpustack/models.json b/internal/models/vendors/gpustack/models.json
new file mode 100644
index 000000000..937a43280
--- /dev/null
+++ b/internal/models/vendors/gpustack/models.json
@@ -0,0 +1,4 @@
+{
+ "vendor": "gpustack",
+ "models": []
+}
diff --git a/internal/models/vendors/gpustack/vendor.go b/internal/models/vendors/gpustack/vendor.go
new file mode 100644
index 000000000..1d3ea2bff
--- /dev/null
+++ b/internal/models/vendors/gpustack/vendor.go
@@ -0,0 +1,107 @@
+// Package gpustack registers a self-hosted GPUStack cluster
+// (https://github.com/gpustack/gpustack).
+//
+// Facts (https://docs.gpustack.ai/latest/integrations/inference-apis/):
+// - the OpenAI-compatible surface is mounted at /v1: "GPUStack serves
+// OpenAI-compatible APIs using the `/v1` path." The 0.x/1.x line served
+// them at /v1-openai and documented /v1 as an alias for everything but
+// the models endpoint, so /v1 is the one path that works on both lines;
+// the 2.x page no longer mentions /v1-openai at all. Rerank is served at
+// /v1/rerank as well — "the OpenAI-compatible APIs does not provide a
+// `rerank` API, so GPUStack serves Jina compatible Rerank API using the
+// `/v1/rerank` path" — so chat, embeddings, transcriptions and rerank now
+// share one base URL;
+// - authentication is `Authorization: Bearer <api key>`;
+// - output cap is `max_tokens`: every GPUStack example uses it and
+// `max_completion_tokens` is never mentioned, so acceptance of the newer
+// field is the backend's business, not the gateway's;
+// - built-in backends are vLLM, SGLang, Ascend MindIE and VoxBox (llama-box
+// was dropped from the 2.x built-in list), so thinking is switched with
+// `chat_template_kwargs.enable_thinking`;
+// - the default base URL is a placeholder the operator must replace
+// (Validate requires it); the hostname contains "gpustack" so
+// DetectByURL recognises catalog rows;
+// - the catalog ships no models: deployments name their own.
+//
+// Unverified: whether GPUStack 2.x still answers on the old /v1-openai path.
+// The 2.x docs neither document it nor announce its removal, which is why
+// the default moved to /v1 rather than keeping a path only one line
+// documents.
+package gpustack
+
+import (
+ _ "embed"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "gpustack"
+
+// BaseURL is the OpenAI-compatible placeholder. Since GPUStack 2.x every
+// surface — chat, embeddings, transcriptions and the Jina-style rerank —
+// hangs off /v1.
+const BaseURL = "http://your_gpustack_server_url/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "GPUStack",
+ Names: map[string]string{"zh-CN": "GPUStack"},
+ Description: "Choose your deployed model on GPUStack",
+ Descriptions: map[string]string{"zh-CN": "选择你在 GPUStack 上部署的模型"},
+ Website: "https://gpustack.ai",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 60,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"gpustack"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ types.ModelTypeASR: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ types.ModelTypeASR,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatChatTemplateKwargs),
+ },
+ },
+ Validate: func(cfg *catalog.Config) error {
+ if cfg == nil {
+ return fmt.Errorf("config is nil")
+ }
+ if strings.TrimSpace(cfg.BaseURL) == "" {
+ return fmt.Errorf("base URL is required for GPUStack provider")
+ }
+ if strings.TrimSpace(cfg.APIKey) == "" {
+ return fmt.Errorf("API key is required for GPUStack provider")
+ }
+ if strings.TrimSpace(cfg.ModelName) == "" {
+ return fmt.Errorf("model name is required")
+ }
+ return nil
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/hunyuan/icon.svg b/internal/models/vendors/hunyuan/icon.svg
new file mode 100644
index 000000000..42edd6cd9
--- /dev/null
+++ b/internal/models/vendors/hunyuan/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Hunyuan</title><circle cx="12" cy="12" fill="#0055E9" r="12"></circle><path d="M12 0c.518 0 1.028.033 1.528.096A6.188 6.188 0 0112.12 12.28l-.12.001c-2.99 0-5.242 2.179-5.554 5.11-.223 2.086.353 4.412 2.242 6.146C3.672 22.1 0 17.479 0 12 0 5.373 5.373 0 12 0z" fill="#A8DFF5"></path><path d="M5.286 5a2.438 2.438 0 01.682 3.38c-3.962 5.966-3.215 10.743 2.648 15.136C3.636 22.056 0 17.452 0 12c0-1.787.39-3.482 1.09-5.006.253-.435.525-.872.817-1.311A2.438 2.438 0 015.286 5z" fill="#0055E9"></path><path d="M12.98.04c.272.021.543.053.81.093.583.106 1.117.254 1.538.44 6.638 2.927 8.07 10.052 1.748 15.642a4.125 4.125 0 01-5.822-.358c-1.51-1.706-1.3-4.184.357-5.822.858-.848 3.108-1.223 4.045-2.441 1.257-1.634 2.122-6.009-2.523-7.506L12.98.039z" fill="#00BCFF"></path><path d="M13.528.096A6.187 6.187 0 0112 12.281a5.75 5.75 0 00-1.71.255c.147-.905.595-1.784 1.321-2.501.858-.848 3.108-1.223 4.045-2.441 1.27-1.651 2.14-6.104-2.676-7.554.184.014.367.033.548.056z" fill="#ECECEE"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/hunyuan/models.json b/internal/models/vendors/hunyuan/models.json
new file mode 100644
index 000000000..e41bcf76a
--- /dev/null
+++ b/internal/models/vendors/hunyuan/models.json
@@ -0,0 +1,18 @@
+{
+ "vendor": "hunyuan",
+ "source": "https://cloud.tencent.com/document/product/1729/104753",
+ "models": [
+ {"name": "Hunyuan T1 family (always-on reasoning)", "match": "hunyuan-t1*", "reasoning": true, "input": ["text"], "thinking_levels": {"off": null}},
+ {"id": "hunyuan-t1-latest", "name": "Hunyuan T1", "reasoning": true, "input": ["text"], "context_window": 32000, "thinking_levels": {"off": null}},
+ {"id": "hunyuan-t1-vision-20250916", "name": "Hunyuan T1 Vision (deep thinking)", "reasoning": true, "input": ["text", "image"], "context_window": 28000, "max_output_tokens": 20000, "thinking_levels": {"off": null}, "source": "https://cloud.tencent.com/document/product/1729/104753"},
+ {"id": "hunyuan-turbos-latest", "name": "Hunyuan TurboS", "reasoning": false, "input": ["text"], "context_window": 32000, "max_output_tokens": 8000, "cost": {"input": 0.11, "output": 0.28}},
+ {"id": "hunyuan-a13b", "name": "Hunyuan A13B (hybrid thinking)", "reasoning": true, "input": ["text"], "context_window": 224000, "max_output_tokens": 32000, "source": "https://cloud.tencent.com/document/product/1729/104753"},
+ {"id": "hunyuan-2.0-thinking-20251109", "name": "Hunyuan 2.0 Thinking", "reasoning": true, "input": ["text"], "source": "https://cloud.tencent.com/document/product/1729/127293"},
+ {"id": "hunyuan-2.0-instruct-20251111", "name": "Hunyuan 2.0 Instruct", "reasoning": false, "input": ["text"], "source": "https://cloud.tencent.com/document/product/1729/127293"},
+ {"id": "hunyuan-vision-1.5-instruct", "name": "Hunyuan Vision 1.5 Instruct (fast thinking)", "reasoning": false, "input": ["text", "image"], "context_window": 24000, "max_output_tokens": 16000, "source": "https://cloud.tencent.com/document/product/1729/104753"},
+ {"id": "hunyuan-turbos-vision-video", "name": "Hunyuan TurboS Vision Video", "reasoning": false, "input": ["text", "image", "video"], "context_window": 24000, "max_output_tokens": 8000, "source": "https://cloud.tencent.com/document/product/1729/104753"},
+ {"id": "hunyuan-turbos-vision", "name": "Hunyuan TurboS Vision", "reasoning": false, "input": ["text", "image"], "context_window": 32000, "max_output_tokens": 8000},
+ {"id": "hunyuan-lite", "name": "Hunyuan Lite", "reasoning": false, "input": ["text"], "context_window": 256000, "max_output_tokens": 6000, "cost": {"input": 0, "output": 0}},
+ {"id": "hunyuan-embedding", "name": "Hunyuan Embedding", "type": "Embedding", "dimension": 1024, "source": "https://cloud.tencent.com/document/product/1729/111007"}
+ ]
+}
diff --git a/internal/models/vendors/hunyuan/vendor.go b/internal/models/vendors/hunyuan/vendor.go
new file mode 100644
index 000000000..9ab41cd64
--- /dev/null
+++ b/internal/models/vendors/hunyuan/vendor.go
@@ -0,0 +1,109 @@
+// Package hunyuan registers Tencent Hunyuan through its OpenAI-compatible
+// endpoint.
+//
+// Facts (https://cloud.tencent.com/document/product/1729/111007):
+// - https://api.hunyuan.cloud.tencent.com/v1 serves both chat
+// (/chat/completions) and embeddings (/embeddings); the only credential
+// is a console API key sent as Authorization: Bearer, so this vendor
+// needs no ExtraFields (the TC3-signed native API is a different host);
+// - the output cap is `max_tokens` (default 4096); the reference does not
+// document `max_completion_tokens`;
+// - `tool_choice` 可选值包括 none、auto、custom and "仅对 hunyuan-turbos、
+// hunyuan-functioncall 模型生效", so `required` is never sent; "custom" is
+// a Hunyuan-specific shape rather than OpenAI's named-function object,
+// so the "function" mode is withheld as well;
+// - temperature is [0.0, 2.0] and top_p [0.0, 1.0], neither restricted;
+// - stream_options.include_usage is supported;
+// - hunyuan-embedding returns a fixed 1024-dimension vector.
+//
+// Thinking (https://cloud.tencent.com/document/product/1729/105701): the
+// native API exposes `EnableThinking`, "未传值时默认开启" and the switch
+// "仅对 hunyuan-a13b 模型生效". The T1 series reasons unconditionally, so
+// models.json marks it "off": null, and hunyuan-a13b additionally accepts a
+// `/no_think` prompt prefix
+// (https://cloud.tencent.com/document/product/1729/104753).
+//
+// Second protocol: an Anthropic Messages facade at
+// https://api.hunyuan.cloud.tencent.com/anthropic (path
+// /anthropic/v1/messages) documents hunyuan-2.0-thinking-20251109 and
+// hunyuan-2.0-instruct-20251111 with thinking {type, budget_tokens}
+// (https://cloud.tencent.com/document/product/1729/127293). The
+// OpenAI-compatible surface stays this vendor's default.
+//
+// unverified: the OpenAI-compatible reference documents no thinking field at
+// all, so the snake_case `enable_thinking` spelling used here is carried over
+// from the native API and is unconfirmed for this endpoint;
+// unverified: response_format, parallel_tool_calls and prompt-cache
+// accounting are absent from the compatible-interface reference, so the
+// protocol defaults (supported, no cache counters) stand untested;
+// unverified: Tencent's model list (1729/104753) and pricing page
+// (1729/97731) document limits for hunyuan-a13b (224k in / 32k out) and the
+// vision models only. hunyuan-t1-latest, hunyuan-turbos-latest, hunyuan-lite
+// and hunyuan-turbos-vision appear in neither table (new models are
+// migrating to TokenHub), so their context windows, output caps and prices
+// are carried over unconfirmed; no retirement notice was found either, so
+// the entries stay. hunyuan-t1-latest used to claim a 64K output cap above
+// its own 32K context window; since no doc supports either number, the cap
+// was dropped rather than corrected, leaving the context window as the only
+// (still unconfirmed) limit. Treat it as a placeholder that the per-model
+// field in the UI overrides, and do not raise it without a documented
+// source: an overstated context window stops history compaction from firing
+// and the upstream rejects the request instead;
+// unverified: the hunyuan-2.0-* ids are documented only on the Anthropic
+// facade, so their availability on this OpenAI-compatible host, their
+// context windows and their output caps are unconfirmed.
+package hunyuan
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "hunyuan"
+
+// BaseURL is the OpenAI-compatible endpoint (chat and embedding).
+const BaseURL = "https://api.hunyuan.cloud.tencent.com/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Tencent Hunyuan",
+ Names: map[string]string{"zh-CN": "腾讯混元 Hunyuan"},
+ Description: "hunyuan-t1-latest, hunyuan-turbos-latest, hunyuan-a13b, hunyuan-embedding, etc.",
+ Website: "https://cloud.tencent.com/product/hunyuan",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 13,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"hunyuan.cloud.tencent.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatEnableThinking),
+ // 可选值包括 none、auto、custom: neither "required" nor OpenAI's
+ // named-function object is documented.
+ ToolChoiceModes: []string{"none", "auto"},
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/jina/icon.svg b/internal/models/vendors/jina/icon.svg
new file mode 100644
index 000000000..fc996bf90
--- /dev/null
+++ b/internal/models/vendors/jina/icon.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Jina</title><path d="M6.608 21.416a4.608 4.608 0 100-9.217 4.608 4.608 0 000 9.217zM20.894 2.015c.614 0 1.106.492 1.106 1.106v9.002c0 5.13-4.148 9.309-9.217 9.37v-9.355l-.03-9.032c0-.614.491-1.106 1.106-1.106h7.158l-.123.015z"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/jina/models.json b/internal/models/vendors/jina/models.json
new file mode 100644
index 000000000..2f41475ba
--- /dev/null
+++ b/internal/models/vendors/jina/models.json
@@ -0,0 +1,18 @@
+{
+ "vendor": "jina",
+ "source": "https://jina.ai/models/",
+ "models": [
+ {"id": "jina-embeddings-v5-omni-small", "name": "Jina Embeddings v5 Omni Small (multimodal)", "type": "Embedding", "input": ["text", "image"], "dimension": 1024, "context_window": 32768},
+ {"id": "jina-embeddings-v5-omni-nano", "name": "Jina Embeddings v5 Omni Nano (multimodal)", "type": "Embedding", "input": ["text", "image"], "dimension": 768, "context_window": 8192},
+ {"id": "jina-embeddings-v5-text-small", "name": "Jina Embeddings v5 Text Small", "type": "Embedding", "dimension": 1024, "context_window": 32768},
+ {"id": "jina-embeddings-v5-text-nano", "name": "Jina Embeddings v5 Text Nano", "type": "Embedding", "dimension": 768, "context_window": 8192},
+ {"id": "jina-embeddings-v4", "name": "Jina Embeddings v4", "type": "Embedding", "dimension": 2048, "context_window": 32768, "source": "https://jina.ai/models/jina-embeddings-v4/"},
+ {"id": "jina-embeddings-v3", "name": "Jina Embeddings v3", "type": "Embedding", "dimension": 1024, "context_window": 8192, "source": "https://jina.ai/models/jina-embeddings-v3/"},
+ {"id": "jina-code-embeddings-1.5b", "name": "Jina Code Embeddings 1.5B", "type": "Embedding", "dimension": 1536, "context_window": 32768},
+ {"id": "jina-code-embeddings-0.5b", "name": "Jina Code Embeddings 0.5B", "type": "Embedding", "dimension": 896, "context_window": 32768},
+ {"id": "jina-reranker-v3.5", "name": "Jina Reranker v3.5", "type": "Rerank", "context_window": 131072, "source": "https://jina.ai/reranker/"},
+ {"id": "jina-reranker-v3", "name": "Jina Reranker v3", "type": "Rerank", "context_window": 131072, "source": "https://jina.ai/models/jina-reranker-v3/"},
+ {"id": "jina-reranker-m0", "name": "Jina Reranker m0 (multimodal)", "type": "Rerank", "context_window": 10000, "source": "https://jina.ai/reranker/"},
+ {"id": "jina-reranker-v2-base-multilingual", "name": "Jina Reranker v2 Base Multilingual", "type": "Rerank", "context_window": 1024, "source": "https://jina.ai/reranker/"}
+ ]
+}
diff --git a/internal/models/vendors/jina/vendor.go b/internal/models/vendors/jina/vendor.go
new file mode 100644
index 000000000..57269c35f
--- /dev/null
+++ b/internal/models/vendors/jina/vendor.go
@@ -0,0 +1,68 @@
+// Package jina registers Jina AI's embedding and rerank APIs.
+//
+// Facts (https://jina.ai/embeddings and https://jina.ai/reranker):
+// - both endpoints live under https://api.jina.ai/v1 and authenticate with
+// `Authorization: Bearer`;
+// - /v1/embeddings matches the input and output JSON schema of OpenAI's
+// text-embedding-3-large (it is a superset: `task`, `normalized`,
+// `embedding_type` and `dimensions` are Jina-only additions);
+// /v1/rerank takes the Cohere-style {model, query, documents, top_n}
+// body;
+// - the v5 generation is a family of four rather than one id:
+// omni (multimodal) and text, each in small (1024 dims, 32K tokens) and
+// nano (768 dims, 8K tokens). jina-embeddings-v4 still defaults to 2048
+// dimensions over 32K tokens and v3 to 1024 over 8K; v4 supports
+// Matryoshka truncation down to 128 through `dimensions`;
+// - jina-reranker-v3.5 and v3 take 131K tokens and are the current
+// recommendations; m0 (10K) and v2-base-multilingual (1K) remain listed;
+// - there is no chat model, so ModelTypes lists embedding and rerank only.
+//
+// Unverified: api.jina.ai does not serve a fetchable OpenAPI document, so
+// the OpenAI-schema compatibility claim rests on the wording of the
+// embeddings FAQ rather than a spec.
+package jina
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "jina"
+
+// BaseURL serves embeddings and rerank.
+const BaseURL = "https://api.jina.ai/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Jina AI",
+ Names: map[string]string{"zh-CN": "Jina"},
+ Description: "jina-embeddings-v5-text-small, jina-embeddings-v4, jina-reranker-v3.5, jina-reranker-m0, etc.",
+ Website: "https://jina.ai",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 50,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"api.jina.ai"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/litellm/icon.svg b/internal/models/vendors/litellm/icon.svg
new file mode 100644
index 000000000..d627c08b4
--- /dev/null
+++ b/internal/models/vendors/litellm/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><rect width="24" height="24" rx="5" fill="#2B6CB0"/><text x="12" y="16" font-family="sans-serif" font-weight="700" font-size="10" fill="#FFFFFF" text-anchor="middle">LL</text></svg>
diff --git a/internal/models/vendors/litellm/models.json b/internal/models/vendors/litellm/models.json
new file mode 100644
index 000000000..4d95c662e
--- /dev/null
+++ b/internal/models/vendors/litellm/models.json
@@ -0,0 +1,4 @@
+{
+ "vendor": "litellm",
+ "models": []
+}
diff --git a/internal/models/vendors/litellm/vendor.go b/internal/models/vendors/litellm/vendor.go
new file mode 100644
index 000000000..0d40bf8fd
--- /dev/null
+++ b/internal/models/vendors/litellm/vendor.go
@@ -0,0 +1,89 @@
+// Package litellm registers a self-hosted LiteLLM proxy
+// (https://github.com/BerriAI/litellm).
+//
+// Facts (https://docs.litellm.ai/docs/reasoning_content):
+// - the proxy speaks plain OpenAI Chat Completions and translates
+// `reasoning_effort` for every upstream it fronts, so the OpenAI
+// thinking format is used and graded effort is supported. The documented
+// vocabulary is minimal | low | medium | high | xhigh | max (mapped onto
+// Anthropic budgets of 1024/1024/2048/4096/8192/16384), plus `none` to
+// turn thinking off — which is why the vendor level map spells "off" as
+// "none" and keeps xhigh and max enabled;
+// - both `max_tokens` and `max_completion_tokens` are listed as supported
+// input params (https://docs.litellm.ai/docs/completion/input) with no
+// stated preference, so the protocol default max_completion_tokens
+// stands;
+// - the default base URL is a placeholder the operator must replace; its
+// hostname contains "litellm" so DetectByURL recognises catalog rows,
+// while loopback URLs stay generic (they are SSRF-blocked unless
+// whitelisted). The proxy's own default is port 4000, and both
+// /v1/chat/completions and /chat/completions are documented;
+// - the catalog ships no models: deployments name their own routes.
+//
+// Unverified: `chat_template_kwargs` is not named in the LiteLLM docs. It
+// should reach a vLLM/SGLang upstream under the general rule that "LiteLLM
+// treats any non-openai param as a provider-specific param, and passes it to
+// the provider in the request body", but a proxy configured with
+// allowed_openai_params may drop it, so operators fronting open-weight
+// models may need thinking_control=chat_template_kwargs plus that allowlist.
+package litellm
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "litellm"
+
+// BaseURL is a placeholder the operator replaces with a reachable proxy.
+const BaseURL = "http://your_litellm_proxy/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "LiteLLM",
+ Names: map[string]string{"zh-CN": "LiteLLM"},
+ Description: "Self-hosted LiteLLM proxy: one OpenAI-compatible endpoint to 100+ providers.",
+ Descriptions: map[string]string{"zh-CN": "自建 LiteLLM 代理:一个 OpenAI 兼容入口对接 100+ 模型服务。"},
+ Website: "https://docs.litellm.ai",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 41,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"litellm"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatOpenAI),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ },
+ },
+ // LiteLLM documents the whole ladder plus "none" as the off switch.
+ ThinkingLevels: api.ThinkingLevelMap{
+ api.ReasoningOff: api.StringPtr("none"),
+ api.ReasoningXHigh: api.StringPtr("xhigh"),
+ api.ReasoningMax: api.StringPtr("max"),
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/lkeap/icon.svg b/internal/models/vendors/lkeap/icon.svg
new file mode 100644
index 000000000..4e7d033e8
--- /dev/null
+++ b/internal/models/vendors/lkeap/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>TencentCloud</title><path d="M20.0483 17.1416C19.6945 17.4914 18.987 18.0161 17.7488 18.0161C17.2182 18.0161 16.5991 18.0161 16.3338 18.0161C15.98 18.0161 13.3268 18.0161 10.143 18.0161C12.4424 15.8298 14.3881 13.9932 14.565 13.8183C14.7419 13.6434 15.1841 13.2061 15.6263 12.8563C16.5107 12.0692 17.2182 11.9817 17.8373 11.9817C18.7217 11.9817 19.4292 12.3316 20.0483 12.8563C21.2864 13.9932 21.2864 16.0047 20.0483 17.1416ZM21.5518 11.457C20.6674 10.495 19.3408 9.88281 17.9257 9.88281C16.6875 9.88281 15.6263 10.3201 14.6534 11.0197C14.2997 11.3695 13.769 11.7194 13.3268 12.2441C12.9731 12.5939 5.36719 19.9401 5.36719 19.9401C5.80939 20.0276 6.34003 20.0276 6.78223 20.0276C7.22443 20.0276 16.0685 20.0276 16.4222 20.0276C17.1298 20.0276 17.6604 20.0276 18.191 19.9401C19.3408 19.8527 20.4905 19.4154 21.4633 18.5409C23.4975 16.6168 23.4975 13.381 21.5518 11.457Z" fill="#00A3FF"></path><path d="M9.1701 10.9323C8.19726 10.2326 7.22442 9.88281 6.07469 9.88281C4.65965 9.88281 3.33304 10.495 2.44864 11.457C0.502952 13.4685 0.502952 16.6168 2.53708 18.6283C3.42148 19.4154 4.30589 19.8527 5.36717 19.9401L7.4013 18.0161C7.04754 18.0161 6.60533 18.0161 6.25157 18.0161C5.10185 17.9287 4.39433 17.5789 3.95212 17.1416C2.71396 15.9172 2.71396 13.9932 3.86368 12.7688C4.48277 12.1566 5.19029 11.8943 6.07469 11.8943C6.60533 11.8943 7.4013 11.9817 8.19726 12.7688C8.55102 13.1186 9.52386 13.8183 9.87763 14.1681H9.96607L11.2927 12.8563V12.7688C10.6736 12.1566 9.70075 11.3695 9.1701 10.9323Z" fill="#00C8DC"></path><path d="M18.4564 8.74536C17.4836 6.12171 14.9188 4.28516 12.0003 4.28516C8.5511 4.28516 5.80945 6.82135 5.27881 9.96973C5.54413 9.96973 5.80945 9.88228 6.16321 9.88228C6.51697 9.88228 6.95917 9.96973 7.31294 9.96973C7.75514 7.78336 9.70082 6.20917 12.0003 6.20917C13.946 6.20917 15.6263 7.34608 16.4223 9.00773C16.4223 9.00773 16.5107 9.09518 16.5107 9.00773C17.1298 8.92027 17.8373 8.74536 18.4564 8.74536C18.4564 8.83282 18.4564 8.83282 18.4564 8.74536Z" fill="#006EFF"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/lkeap/models.json b/internal/models/vendors/lkeap/models.json
new file mode 100644
index 000000000..e511f4afe
--- /dev/null
+++ b/internal/models/vendors/lkeap/models.json
@@ -0,0 +1,16 @@
+{
+ "vendor": "lkeap",
+ "source": "https://cloud.tencent.com/document/product/1772/115963",
+ "models": [
+ {"name": "DeepSeek R1 family (always-on reasoning)", "match": "*deepseek-r1*", "reasoning": true, "input": ["text"], "thinking_levels": {"off": null}},
+ {"name": "DeepSeek V3 family (thinking switch)", "match": "*deepseek-v3*", "reasoning": true, "input": ["text"]},
+ {"id": "deepseek-v3.2", "name": "DeepSeek V3.2", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 32768, "source": "https://cloud.tencent.com/document/product/1772/115963"},
+ {"id": "deepseek-v3.1-terminus", "name": "DeepSeek V3.1 Terminus", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 32768, "source": "https://cloud.tencent.com/document/product/1772/115963"},
+ {"id": "deepseek-r1-0528", "name": "DeepSeek R1 (0528)", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 16384, "thinking_levels": {"off": null}, "source": "https://cloud.tencent.com/document/product/1772/115963"},
+ {"id": "deepseek-v3-0324", "name": "DeepSeek V3 (0324)", "reasoning": false, "input": ["text"], "context_window": 131072, "max_output_tokens": 16384, "source": "https://cloud.tencent.com/document/product/1772/115963"},
+ {"id": "deepseek-r1", "name": "DeepSeek R1", "reasoning": true, "input": ["text"], "context_window": 65536, "max_output_tokens": 16384, "thinking_levels": {"off": null}},
+ {"id": "deepseek-v3", "name": "DeepSeek V3", "reasoning": false, "input": ["text"], "context_window": 65536, "max_output_tokens": 16384},
+ {"id": "deepseek-v3.1", "name": "DeepSeek V3.1", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 32768},
+ {"id": "lke-reranker-base", "name": "LKE Reranker Base", "type": "Rerank", "source": "https://cloud.tencent.com/document/product/1772/115339"}
+ ]
+}
diff --git a/internal/models/vendors/lkeap/vendor.go b/internal/models/vendors/lkeap/vendor.go
new file mode 100644
index 000000000..a3a28995e
--- /dev/null
+++ b/internal/models/vendors/lkeap/vendor.go
@@ -0,0 +1,140 @@
+// Package lkeap registers Tencent Cloud LKEAP (Knowledge Engine Atomic
+// Power) through its OpenAI-compatible endpoint.
+//
+// Chat facts (https://cloud.tencent.com/document/product/1772/115969 and
+// the model list at https://cloud.tencent.com/document/product/1772/115963):
+// - the documented endpoint is
+// https://api.lkeap.cloud.tencent.com/v1/chat/completions, so the base
+// URL already carries the /v1 segment;
+// - authentication is a plain `Authorization: Bearer sk-...` console key,
+// unrelated to the Tencent Cloud SecretId / SecretKey pair;
+// - output cap is `max_tokens`; temperature (default 0.6, range [0, 2]) and
+// top_p (default 0.6, range (0, 1]) are both accepted, as are stop,
+// presence_penalty, frequency_penalty, Function Calling and
+// response_format json_object (json_schema on V3.1+);
+// - thinking is switched with `thinking: {"type": "enabled"|"disabled"}`,
+// documented as taking effect only on deepseek-v3.1-terminus and
+// deepseek-v3.2; DeepSeek R1 reasons unconditionally, so the R1 entries
+// carry "off": null and never receive a disable switch;
+// - `reasoning_effort` is not part of the LKEAP surface, so effort grading
+// stays off and only the thinking switch is sent.
+//
+// Rerank facts (https://cloud.tencent.com/document/product/1772/115339):
+// - it is not the OpenAI-compatible host but the Tencent Cloud API
+// lkeap.tencentcloudapi.com, action RunRerank, version 2024-05-22,
+// available in ap-beijing and ap-guangzhou only;
+// - it therefore needs the TC3-HMAC-SHA256 credential pair: the API key
+// field carries the SecretId and the rerank-only extra fields carry the
+// SecretKey and the region (default ap-guangzhou). The SecretKey is
+// genuinely required — TC3 signing cannot be done without it;
+// - the optional Model parameter defaults to lke-reranker-base, which is
+// documented as the only available rerank model.
+//
+// unverified: the current model list documents deepseek-v3-0324,
+// deepseek-r1-0528, deepseek-v3.1-terminus and deepseek-v3.2. The plain
+// deepseek-r1 / deepseek-v3 / deepseek-v3.1 ids kept in models.json are no
+// longer listed, but no LKEAP retirement notice covers them, so they stay
+// with their previously recorded limits.
+//
+// unverified: LKEAP documents neither tool_choice modes,
+// stream_options.include_usage nor any prompt-cache accounting, so the
+// protocol defaults are kept.
+package lkeap
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "lkeap"
+
+// BaseURL is the OpenAI-compatible chat endpoint.
+const BaseURL = "https://api.lkeap.cloud.tencent.com/v1"
+
+// RerankBaseURL is the TC3-signed cloud API host used for rerank.
+const RerankBaseURL = "https://lkeap.tencentcloudapi.com"
+
+func init() {
+ rerankOnly := []types.ModelType{types.ModelTypeRerank}
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Tencent Cloud LKEAP",
+ Names: map[string]string{"zh-CN": "腾讯云 LKEAP"},
+ Description: "deepseek-v3.2, deepseek-v3.1-terminus, deepseek-r1-0528, lke-reranker-base",
+ Descriptions: map[string]string{
+ "zh-CN": "DeepSeek-V3.2、DeepSeek-V3.1-Terminus、DeepSeek-R1-0528、lke-reranker-base",
+ },
+ Website: "https://cloud.tencent.com/product/lkeap",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 23,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"lkeap.cloud.tencent.com", "api.lkeap", "lkeap.tencentcloudapi.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeRerank: RerankBaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeRerank,
+ },
+ // The rerank API authenticates with a TC3-signed CAM identity, so the
+ // first credential is a SecretId, not a bearer token. Left as the
+ // generic "API Key" an operator pastes an `sk-` key that can never
+ // sign a request.
+ CredentialLabels: []catalog.CredentialLabel{{
+ Label: "SecretId",
+ Labels: map[string]string{"zh-CN": "SecretId(TC3 签名)"},
+ Placeholder: "Tencent Cloud SecretId (AKID...)",
+ Placeholders: map[string]string{"zh-CN": "腾讯云 SecretId(AKID 开头)"},
+ Hint: "Rerank is signed with a CAM key pair; this is not an sk- API key.",
+ Hints: map[string]string{"zh-CN": "Rerank 使用 CAM 密钥对签名,不是 sk- 开头的 API Key。"},
+ ModelTypes: rerankOnly,
+ Required: true,
+ }},
+ ExtraFields: []catalog.ExtraField{
+ {
+ Key: "secret_key",
+ Label: "Secret Key",
+ Labels: map[string]string{"zh-CN": "SecretKey(TC3 签名)"},
+ Type: "password",
+ Required: true,
+ Placeholder: "Tencent Cloud SecretKey (the API Key field holds the SecretId)",
+ ModelTypes: rerankOnly,
+ Secret: true,
+ },
+ {
+ // RunRerank is only published in ap-beijing and ap-guangzhou.
+ Key: "region",
+ Label: "Region",
+ Labels: map[string]string{"zh-CN": "地域"},
+ Type: "select",
+ Default: "ap-guangzhou",
+ Placeholder: "ap-guangzhou",
+ Options: []catalog.ExtraFieldOption{
+ {Label: "ap-guangzhou", Value: "ap-guangzhou"},
+ {Label: "ap-beijing", Value: "ap-beijing"},
+ },
+ ModelTypes: rerankOnly,
+ },
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/longcat/icon.svg b/internal/models/vendors/longcat/icon.svg
new file mode 100644
index 000000000..fde6c8a36
--- /dev/null
+++ b/internal/models/vendors/longcat/icon.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>LongCat</title><path clip-rule="evenodd" d="M.507 19.883a.507.507 0 01-.489-.642L4.29 3.745a1.013 1.013 0 011.533-.578l5.622 3.687a1.013 1.013 0 001.11 0L18.2 3.165a1.013 1.013 0 011.532.58l4.25 15.497a.506.506 0 01-.49.64H18.07a6.297 6.297 0 001.53-4.115v-.177a6.09 6.09 0 00-1.513-4.017l-.697-3.495a.438.438 0 00-.694-.266L14.07 9.781a.748.748 0 01-.654.121 5.156 5.156 0 00-2.833 0 .746.746 0 01-.653-.121L7.302 7.81a.435.435 0 00-.688.269l-.675 3.652a5.36 5.36 0 00-1.539 3.76v.333c0 1.474.527 2.9 1.488 4.02l.032.038H.507z" fill="#29E154" fill-rule="evenodd"></path><path d="M9.213 16.843h1.52v-3.546h-1.29l-.23 3.546zm5.573 0h-1.52v-3.546h1.29l.23 3.546z"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/longcat/models.json b/internal/models/vendors/longcat/models.json
new file mode 100644
index 000000000..7d28fcdc9
--- /dev/null
+++ b/internal/models/vendors/longcat/models.json
@@ -0,0 +1,9 @@
+{
+ "vendor": "longcat",
+ "source": "https://longcat.chat/platform/docs/zh/api/chat.html",
+ "models": [
+ {"id": "LongCat-2.0", "name": "LongCat 2.0", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 0.75, "output": 2.95, "cache_read": 0.015}, "source": "https://longcat.chat/platform/docs/zh/api/chat.html"},
+ {"id": "LongCat-Flash-Chat", "name": "LongCat Flash Chat (retired 2026-05-29)", "deprecated": true, "reasoning": false, "input": ["text"], "context_window": 262144, "max_output_tokens": 8192, "source": "https://longcat.chat/platform/docs/zh/ChangeLog.html"},
+ {"id": "LongCat-Flash-Thinking", "name": "LongCat Flash Thinking (retired 2026-05-29)", "deprecated": true, "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 65536, "thinking_levels": {"off": null}, "source": "https://longcat.chat/platform/docs/zh/ChangeLog.html"}
+ ]
+}
diff --git a/internal/models/vendors/longcat/vendor.go b/internal/models/vendors/longcat/vendor.go
new file mode 100644
index 000000000..603a5727b
--- /dev/null
+++ b/internal/models/vendors/longcat/vendor.go
@@ -0,0 +1,97 @@
+// Package longcat registers Meituan LongCat's OpenAI-compatible endpoint.
+//
+// Facts (chat reference https://longcat.chat/platform/docs/zh/api/chat.html,
+// overview https://longcat.chat/platform/docs/zh/APIDocs.html):
+// - the OpenAI facade is served at
+// POST https://api.longcat.chat/openai/v1/chat/completions, so the base
+// URL carries the /openai/v1 prefix;
+// - auth is `Authorization: Bearer <API Key>` and nothing else;
+// - output cap is `max_tokens`, which defaults to and tops out at the
+// model's 128K (131072) output budget; `max_completion_tokens` is not
+// part of the reference;
+// - thinking IS switchable, with `thinking: {"type": "enabled"}` or
+// `{"type": "disabled"}`, and it is enabled by default. No
+// `reasoning_effort` is documented, so the switch is sent without a
+// grade;
+// - the model replies with `reasoning_content` and reports
+// `completion_tokens_details.reasoning_tokens`, which the protocol
+// already reads by default;
+// - `messages` is text only (roles system / user / assistant), which is
+// why every entry lists the text modality alone;
+// - temperature is documented over 0..1 rather than the OpenAI 0..2, and
+// top_p is accepted. The protocol has no field for a narrower range,
+// so values are passed through unchanged;
+// - LongCat also serves an Anthropic Messages surface at
+// https://api.longcat.chat/anthropic/v1/messages
+// (https://longcat.chat/platform/docs/zh/api/messages.html) with the
+// same model and the same thinking shape. The documented default, and
+// what this package configures, is the OpenAI format.
+//
+// unverified: the changelog credits LongCat-2.0 with "native tool
+// calling", but neither API reference documents `tools`, `tool_choice`,
+// `parallel_tool_calls` or a `tool` message role, so the protocol
+// defaults (the full OpenAI tool_choice set) are kept untested.
+//
+// unverified: `response_format` and `stream_options.include_usage` do not
+// appear in the reference either; the protocol defaults are kept.
+//
+// unverified: nothing documents a mandatory thinking switch or a
+// non-stream restriction, so thinking_always_send and
+// thinking_disable_on_non_stream stay off.
+//
+// unverified: the published usage object carries no cache counters even
+// though the price list bills cached input, so prompt_cache_accounting
+// stays off; neither prompt_cache_key nor cache_control is documented.
+package longcat
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "longcat"
+
+// BaseURL is the OpenAI-compatible chat endpoint.
+const BaseURL = "https://api.longcat.chat/openai/v1"
+
+// AnthropicBaseURL is the Anthropic Messages surface of the same platform.
+const AnthropicBaseURL = "https://api.longcat.chat/anthropic/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "LongCat AI",
+ Names: map[string]string{"zh-CN": "美团 LongCat"},
+ Description: "LongCat-2.0",
+ Website: "https://longcat.chat/platform",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 22,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"longcat.chat"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/mimo/icon.svg b/internal/models/vendors/mimo/icon.svg
new file mode 100644
index 000000000..b8ba03b87
--- /dev/null
+++ b/internal/models/vendors/mimo/icon.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>XiaomiMiMo</title><path d="M.958 15.936a.459.459 0 01.459.44v2.729a.46.46 0 01-.918 0v-2.729a.459.459 0 01.459-.44zm4.814-2.035a.46.46 0 01.553.45v4.754a.458.458 0 11-.918 0V15.48L3.74 17.202a.462.462 0 01-.655.016.462.462 0 01-.065-.082L.628 14.67a.459.459 0 01.658-.637l2.124 2.187 2.127-2.188a.46.46 0 01.235-.13zm2.068.004a.46.46 0 01.458.445v4.755a.46.46 0 01-.458.458.459.459 0 01-.458-.458V14.35a.459.459 0 01.458-.445zm1.973 2.014a.46.46 0 01.46.457v2.729a.46.46 0 01-.784.324.46.46 0 01-.134-.324v-2.729a.46.46 0 01.458-.458zm.002-2.045a.458.458 0 01.328.157l2.127 2.19 2.125-2.19a.459.459 0 01.784.318v4.756a.46.46 0 01-.455.458.46.46 0 01-.458-.458V15.48l-1.667 1.723a.46.46 0 01-.65.008l-.005-.005c0-.002-.002-.002-.004-.003l-2.455-2.534a.46.46 0 01-.008-.667.461.461 0 01.338-.128zm6.797 1.206a.46.46 0 01.53.651A1.966 1.966 0 0019.81 18.4a.462.462 0 01.623.18.46.46 0 01-.181.624 2.863 2.863 0 01-1.38.353l-.142-.004a2.88 2.88 0 01-2.393-4.263.461.461 0 01.274-.21zm.864-.931a2.884 2.884 0 013.915 3.914.46.46 0 01-.402.24l-.057-.004a.458.458 0 01-.164-.055.46.46 0 01-.182-.622 1.967 1.967 0 00-2.669-2.67.459.459 0 11-.441-.803zM9.59 6.368c1.481 0 1.696 1.202 1.696 1.654v2.648h-.917v-.432c-.26.346-.792.535-1.36.535-.133 0-1.289-.03-1.384-1.136-.082-.932.675-1.61 2.053-1.61h.691c0-.563-.367-.886-.983-.886-.44.013-.864.174-1.2.458l-.36-.664c.484-.379 1.012-.567 1.764-.567zm4.427.1c1.263 0 2.082.97 2.083 2.15 0 1.181-.824 2.154-2.083 2.154-1.26 0-2.084-.972-2.084-2.152 0-1.18.82-2.153 2.084-2.153zm6.801.015c.68 0 1.202.465 1.197 1.548v2.642H21.1V8.29c0-.312-.002-.98-.63-.98s-.628.667-.628.838v2.524h-.89V8.148c0-.17-.001-.838-.63-.838-.628 0-.628.668-.628.98v2.383h-.917v-4.03h.917V7a1.22 1.22 0 01.947-.516c.398 0 .76.193.982.686a1.321 1.321 0 011.195-.686zm-18.093.872l1.457-1.772H5.32L3.311 8.07l2.14 2.602H4.24L2.725 8.796 1.21 10.672H0L2.138 8.07.13 5.583h1.138l1.458 1.772zm4.149 3.317h-.916V6.644h.916v4.028zm16.99 0h-.916V6.644h.916v4.028zM9.925 8.71c-1.055 0-1.359.412-1.326.742.032.329.324.537.757.537a1.013 1.013 0 001.014-.968l.002-.31h-.447zM14.018 7.3c-.663 0-1.184.487-1.184 1.32 0 .832.52 1.32 1.184 1.32.662 0 1.182-.49 1.182-1.32 0-.832-.52-1.32-1.182-1.32zM6.417 5.001a.568.568 0 01.587.582.588.588 0 01-1.175 0A.57.57 0 016.417 5zm16.991 0a.57.57 0 01.592.582.588.588 0 01-1.174 0 .57.57 0 01.357-.542.572.572 0 01.225-.04z"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/mimo/models.json b/internal/models/vendors/mimo/models.json
new file mode 100644
index 000000000..c54858e31
--- /dev/null
+++ b/internal/models/vendors/mimo/models.json
@@ -0,0 +1,10 @@
+{
+ "vendor": "mimo",
+ "source": "https://mimo.mi.com/static/docs/quick-start/summary/model.md",
+ "models": [
+ {"id": "mimo-v2.5-pro", "name": "MiMo V2.5 Pro", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 0.435, "output": 0.87, "cache_read": 0.0036}, "source": "https://mimo.mi.com/static/docs/price/pay-as-you-go.md"},
+ {"id": "mimo-v2.5", "name": "MiMo V2.5", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 0.14, "output": 0.28, "cache_read": 0.0028}, "source": "https://mimo.mi.com/static/docs/price/pay-as-you-go.md"},
+ {"id": "mimo-v2.5-pro-ultraspeed", "name": "MiMo V2.5 Pro Ultraspeed", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 1.305, "output": 2.61, "cache_read": 0.0108}, "source": "https://mimo.mi.com/static/docs/news/latest/beta-extended.md"},
+ {"id": "mimo-v2-flash", "name": "MiMo V2 Flash (retired 2026-06-30)", "reasoning": true, "input": ["text"], "context_window": 256000, "max_output_tokens": 256000, "cost": {"input": 0.1, "output": 0.3, "cache_read": 0.01}, "deprecated": true, "source": "https://mimo.mi.com/static/docs/updates/deprecate.md"}
+ ]
+}
diff --git a/internal/models/vendors/mimo/vendor.go b/internal/models/vendors/mimo/vendor.go
new file mode 100644
index 000000000..f3c7ec138
--- /dev/null
+++ b/internal/models/vendors/mimo/vendor.go
@@ -0,0 +1,87 @@
+// Package mimo registers Xiaomi MiMo's OpenAI-compatible endpoint.
+//
+// Facts (https://mimo.mi.com/static/docs/api/chat/openai-api.md,
+// https://mimo.mi.com/static/docs/quick-start/summary/model.md,
+// https://mimo.mi.com/static/docs/api/guidance/model-hyperparameters.md):
+// - the OpenAI-compatible base URL is https://api.xiaomimimo.com/v1 and auth
+// is `Authorization: Bearer sk-...`; an Anthropic Messages endpoint lives
+// at https://api.xiaomimimo.com/anthropic and is not selected here;
+// - the output cap is `max_completion_tokens` (the protocol default);
+// `max_tokens` is not a documented parameter;
+// - thinking is switched with `thinking: {"type": "enabled"|"disabled"}`,
+// enabled by default on both chat models; there is no reasoning_effort and
+// no thinking budget;
+// - prior assistant turns must replay `reasoning_content` whenever the turn
+// carried tool_calls, otherwise the API answers 400 (the default);
+// - temperature ([0, 1.5], default 1.0) and top_p ([0.01, 1.0], default
+// 0.95) are accepted, but while thinking is on the service silently pins
+// them to 1.0 / 0.95 instead of erroring, so they stay enabled;
+// - `tool_choice` only offers `auto`: any other value is dropped server side
+// and the request behaves as auto;
+// - usage reports `prompt_tokens_details.cached_tokens` (cache writes are
+// free for now), so cache accounting is on;
+// - mimo-v2-flash — together with mimo-v2-pro, mimo-v2-omni and mimo-v2-tts —
+// was retired on 2026-06-30 and is kept only as a deprecated entry
+// (https://mimo.mi.com/static/docs/updates/deprecate.md).
+//
+// Unverified: `stream_options.include_usage` is absent from the documented
+// request schema, but the streaming chunks document a `usage` object, so the
+// protocol default (send it) is kept rather than guessed away;
+// parallel_tool_calls and seed are likewise absent from the documented schema
+// without being documented as rejected; mimo-v2.5-pro-ultraspeed is a closed
+// beta that neither the model list nor the price list carries, so its id,
+// limits and prices are unconfirmed; the ASR (mimo-v2.5-asr) and TTS models
+// are documented but not registered here, since this vendor only declares the
+// chat model type.
+package mimo
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "mimo"
+
+// BaseURL is the OpenAI-compatible chat endpoint.
+const BaseURL = "https://api.xiaomimimo.com/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Xiaomi MiMo",
+ Names: map[string]string{"zh-CN": "小米 MiMo"},
+ Description: "mimo-v2.5-pro, mimo-v2.5",
+ Website: "https://platform.xiaomimimo.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 18,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"xiaomimimo.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ PromptCacheAccounting: catalog.Ptr(true),
+ // Only `auto` is honoured; everything else is stripped.
+ ToolChoiceModes: []string{"auto"},
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/minimax/icon.svg b/internal/models/vendors/minimax/icon.svg
new file mode 100644
index 000000000..beb7adb86
--- /dev/null
+++ b/internal/models/vendors/minimax/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Minimax</title><defs><linearGradient id="lobe-icons-minimax-_R_0_" x1="0%" x2="100.182%" y1="50.057%" y2="50.057%"><stop offset="0%" stop-color="#E2167E"></stop><stop offset="100%" stop-color="#FE603C"></stop></linearGradient></defs><path d="M16.278 2c1.156 0 2.093.927 2.093 2.07v12.501a.74.74 0 00.744.709.74.74 0 00.743-.709V9.099a2.06 2.06 0 012.071-2.049A2.06 2.06 0 0124 9.1v6.561a.649.649 0 01-.652.645.649.649 0 01-.653-.645V9.1a.762.762 0 00-.766-.758.762.762 0 00-.766.758v7.472a2.037 2.037 0 01-2.048 2.026 2.037 2.037 0 01-2.048-2.026v-12.5a.785.785 0 00-.788-.753.785.785 0 00-.789.752l-.001 15.904A2.037 2.037 0 0113.441 22a2.037 2.037 0 01-2.048-2.026V18.04c0-.356.292-.645.652-.645.36 0 .652.289.652.645v1.934c0 .263.142.506.372.638.23.131.514.131.744 0a.734.734 0 00.372-.638V4.07c0-1.143.937-2.07 2.093-2.07zm-5.674 0c1.156 0 2.093.927 2.093 2.07v11.523a.648.648 0 01-.652.645.648.648 0 01-.652-.645V4.07a.785.785 0 00-.789-.78.785.785 0 00-.789.78v14.013a2.06 2.06 0 01-2.07 2.048 2.06 2.06 0 01-2.071-2.048V9.1a.762.762 0 00-.766-.758.762.762 0 00-.766.758v3.8a2.06 2.06 0 01-2.071 2.049A2.06 2.06 0 010 12.9v-1.378c0-.357.292-.646.652-.646.36 0 .653.29.653.646V12.9c0 .418.343.757.766.757s.766-.339.766-.757V9.099a2.06 2.06 0 012.07-2.048 2.06 2.06 0 012.071 2.048v8.984c0 .419.343.758.767.758.423 0 .766-.339.766-.758V4.07c0-1.143.937-2.07 2.093-2.07z" fill="url(#lobe-icons-minimax-_R_0_)" fill-rule="nonzero"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/minimax/models.json b/internal/models/vendors/minimax/models.json
new file mode 100644
index 000000000..7aababf42
--- /dev/null
+++ b/internal/models/vendors/minimax/models.json
@@ -0,0 +1,14 @@
+{
+ "vendor": "minimax",
+ "source": "https://platform.minimax.io/docs/api-reference/text-openai-api",
+ "models": [
+ {"id": "MiniMax-M3", "name": "MiniMax M3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 512000, "cost": {"input": 0.3, "output": 1.2, "cache_read": 0.06}, "source": "https://platform.minimax.io/docs/guides/text-generation"},
+ {"id": "MiniMax-M2.7", "name": "MiniMax M2.7", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.3, "output": 1.2, "cache_read": 0.06, "cache_write": 0.375}, "thinking_levels": {"off": null}},
+ {"id": "MiniMax-M2.7-highspeed", "name": "MiniMax M2.7 Highspeed", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.6, "output": 2.4, "cache_read": 0.06, "cache_write": 0.375}, "thinking_levels": {"off": null}},
+ {"id": "MiniMax-M2.5", "name": "MiniMax M2.5", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.3, "output": 1.2, "cache_read": 0.03, "cache_write": 0.375}, "thinking_levels": {"off": null}},
+ {"id": "MiniMax-M2.5-highspeed", "name": "MiniMax M2.5 Highspeed", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.6, "output": 2.4, "cache_read": 0.06, "cache_write": 0.375}, "thinking_levels": {"off": null}},
+ {"id": "MiniMax-M2.1", "name": "MiniMax M2.1", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.3, "output": 1.2, "cache_read": 0.03, "cache_write": 0.375}, "thinking_levels": {"off": null}},
+ {"id": "MiniMax-M2.1-highspeed", "name": "MiniMax M2.1 Highspeed", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "thinking_levels": {"off": null}, "source": "https://platform.minimax.io/docs/guides/text-generation"},
+ {"id": "MiniMax-M2", "name": "MiniMax M2", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.3, "output": 1.2}, "thinking_levels": {"off": null}}
+ ]
+}
diff --git a/internal/models/vendors/minimax/vendor.go b/internal/models/vendors/minimax/vendor.go
new file mode 100644
index 000000000..08652c127
--- /dev/null
+++ b/internal/models/vendors/minimax/vendor.go
@@ -0,0 +1,108 @@
+// Package minimax registers MiniMax's OpenAI-compatible chat endpoint.
+//
+// Facts (https://platform.minimax.io/docs/api-reference/text-openai-api):
+// - both `max_tokens` (legacy) and `max_completion_tokens` are accepted,
+// and the reference recommends the latter for new integrations, so the
+// protocol default is kept;
+// - thinking is `thinking: {"type": "adaptive"|"disabled"}` (hence
+// thinking_enabled_value "adaptive"). On this OpenAI surface thinking is
+// ON when the field is omitted, so the switch is only sent when the
+// caller asks for one; the M2 generation accepts the field but cannot
+// actually turn thinking off, and models.json marks it "off": null;
+// - prompt caching is automatic and usage reports
+// `prompt_tokens_details.cached_tokens`, hence prompt_cache_accounting
+// (https://platform.minimax.io/docs/api-reference/text-prompt-caching);
+// - the only credential is a bearer API key: the GroupId that the legacy
+// /v1/text/chatcompletion_v2 endpoint required is not used here, so this
+// vendor needs no ExtraFields;
+// - the mainland endpoint is https://api.minimaxi.com/v1 and the global one
+// https://api.minimax.io/v1; keys are region-bound (mainland keys to
+// minimaxi.com, global keys to minimax.io).
+//
+// Second protocol: an Anthropic Messages facade lives at
+// https://api.minimax.io/anthropic (mainland form in AnthropicBaseURL), and
+// the vendor presents it first for thinking and tool workflows, documented at
+// https://platform.minimax.io/docs/api-reference/text-anthropic-api.
+// Resolve switches protocol when the base URL ends with /anthropic; this
+// package still defaults to the OpenAI-compatible surface, which is the one
+// documented for both regions.
+//
+// unverified: the sampling ranges are contradictory. The OpenAI-surface
+// reference gives temperature [0, 2] and top_p [0, 1], but MiniMax rejects
+// temperature=0 and top_p=0 in practice with error 2013 ("invalid params,
+// param 'top_p' should be in (0,1]"), i.e. the real range is (0, 1]. The
+// catalog can only express "no sampling" or "one fixed temperature", not an
+// exclusive lower bound, so nothing is configured and zero values still
+// reach the vendor;
+// unverified: `tool_choice`, `parallel_tool_calls`, `response_format` and
+// `prompt_cache_key` are not described on the OpenAI surface, so the
+// protocol defaults stand untested;
+// unverified: max output caps. The model table publishes context windows but
+// no per-model output cap, so the max_output_tokens in models.json are
+// carried over unconfirmed;
+// unverified: only the global https://api.minimax.io/anthropic form of the
+// Anthropic facade is spelled out in the docs; the mainland
+// https://api.minimaxi.com/anthropic that AnthropicBaseURL holds is inferred
+// from the region split of the /v1 hosts.
+package minimax
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "minimax"
+
+// BaseURL is the mainland-China OpenAI-compatible endpoint.
+const BaseURL = "https://api.minimaxi.com/v1"
+
+// GlobalBaseURL is the international endpoint.
+const GlobalBaseURL = "https://api.minimax.io/v1"
+
+// AnthropicBaseURL is the Anthropic Messages compatibility facade.
+const AnthropicBaseURL = "https://api.minimaxi.com/anthropic"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "MiniMax",
+ Names: map[string]string{"zh-CN": "MiniMax"},
+ Description: "MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed, etc. Global endpoint " +
+ GlobalBaseURL + "; Anthropic-compatible facade " + AnthropicBaseURL,
+ Descriptions: map[string]string{
+ "zh-CN": "MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed 等。国际版 " +
+ GlobalBaseURL + ";Anthropic 兼容接口 " + AnthropicBaseURL,
+ },
+ Website: "https://platform.minimaxi.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 16,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"minimax.io", "minimaxi.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ ThinkingEnabledValue: catalog.Ptr("adaptive"),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/modelscope/icon.svg b/internal/models/vendors/modelscope/icon.svg
new file mode 100644
index 000000000..afbaa171a
--- /dev/null
+++ b/internal/models/vendors/modelscope/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelScope</title><path d="M0 7.967h2.667v2.667H0zM8 10.633h2.667V13.3H8z" fill="#36CED0"></path><path d="M0 10.633h2.667V13.3H0zM2.667 13.3h2.666v2.667H8v2.666H2.667V13.3zM2.667 5.3H8v2.667H5.333v2.666H2.667V5.3zM10.667 13.3h2.667v2.667h-2.667z" fill="#624AFF"></path><path d="M24 7.967h-2.667v2.667H24zM16 10.633h-2.667V13.3H16z" fill="#36CED0"></path><path d="M24 10.633h-2.667V13.3H24zM21.333 13.3h-2.666v2.667H16v2.666h5.333V13.3zM21.333 5.3H16v2.667h2.667v2.666h2.666V5.3z" fill="#624AFF"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/modelscope/models.json b/internal/models/vendors/modelscope/models.json
new file mode 100644
index 000000000..8d46efc51
--- /dev/null
+++ b/internal/models/vendors/modelscope/models.json
@@ -0,0 +1,17 @@
+{
+ "vendor": "modelscope",
+ "source": "https://modelscope.cn/docs/model-service/API-Inference/intro",
+ "models": [
+ {"id": "ZhipuAI/GLM-4.6", "name": "GLM-4.6", "reasoning": true, "input": ["text"], "context_window": 202752, "max_output_tokens": 98304, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/ZhipuAI/GLM-4.6"},
+ {"id": "ZhipuAI/GLM-4.5", "name": "GLM-4.5", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 98304, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/ZhipuAI/GLM-4.5"},
+ {"id": "Qwen/Qwen3-235B-A22B-Instruct-2507", "name": "Qwen3 235B-A22B Instruct 2507", "reasoning": false, "input": ["text"], "context_window": 262144, "max_output_tokens": 131072, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/Qwen/Qwen3-235B-A22B-Instruct-2507"},
+ {"id": "Qwen/Qwen3-235B-A22B-Thinking-2507", "name": "Qwen3 235B-A22B Thinking 2507", "reasoning": true, "input": ["text"], "context_window": 262144, "max_output_tokens": 131072, "cost": {"input": 0, "output": 0}, "thinking_levels": {"off": null}, "source": "https://modelscope.cn/models/Qwen/Qwen3-235B-A22B-Thinking-2507"},
+ {"id": "Qwen/Qwen3-30B-A3B-Instruct-2507", "name": "Qwen3 30B-A3B Instruct 2507", "reasoning": false, "input": ["text"], "context_window": 262144, "max_output_tokens": 16384, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/Qwen/Qwen3-30B-A3B-Instruct-2507"},
+ {"id": "Qwen/Qwen3-30B-A3B-Thinking-2507", "name": "Qwen3 30B-A3B Thinking 2507", "reasoning": true, "input": ["text"], "context_window": 262144, "max_output_tokens": 32768, "cost": {"input": 0, "output": 0}, "thinking_levels": {"off": null}, "source": "https://modelscope.cn/models/Qwen/Qwen3-30B-A3B-Thinking-2507"},
+ {"id": "Qwen/Qwen3-Coder-30B-A3B-Instruct", "name": "Qwen3 Coder 30B-A3B Instruct", "reasoning": false, "input": ["text"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/Qwen/Qwen3-Coder-30B-A3B-Instruct"},
+ {"id": "Qwen/Qwen3-8B", "name": "Qwen3 8B (hybrid thinking)", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 32768, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/Qwen/Qwen3-8B"},
+ {"id": "Qwen/Qwen3-VL-235B-A22B-Instruct", "name": "Qwen3 VL 235B-A22B Instruct", "reasoning": false, "input": ["text", "image"], "context_window": 262144, "max_output_tokens": 32768, "cost": {"input": 0, "output": 0}, "source": "https://modelscope.cn/models/Qwen/Qwen3-VL-235B-A22B-Instruct"},
+ {"id": "Qwen/Qwen3-Embedding-8B", "name": "Qwen3 Embedding 8B", "type": "Embedding", "dimension": 4096, "source": "https://modelscope.cn/models/Qwen/Qwen3-Embedding-8B"},
+ {"id": "Qwen/Qwen3-Embedding-0.6B", "name": "Qwen3 Embedding 0.6B", "type": "Embedding", "dimension": 1024, "source": "https://modelscope.cn/models/Qwen/Qwen3-Embedding-0.6B"}
+ ]
+}
diff --git a/internal/models/vendors/modelscope/vendor.go b/internal/models/vendors/modelscope/vendor.go
new file mode 100644
index 000000000..382c91479
--- /dev/null
+++ b/internal/models/vendors/modelscope/vendor.go
@@ -0,0 +1,88 @@
+// Package modelscope registers ModelScope's API-Inference service.
+//
+// Facts (https://modelscope.cn/docs/model-service/API-Inference/intro,
+// https://modelscope.cn/docs/model-service/API-Inference/limits):
+// - the OpenAI-compatible base URL is https://api-inference.modelscope.cn/v1
+// and auth is `Authorization: Bearer <ModelScope Access Token>` (the
+// account must be bound to a verified Aliyun account);
+// - the same host also serves an OpenAI Responses endpoint on /v1 (Qwen3.5
+// family only) and a beta Anthropic Messages endpoint on the bare host
+// (https://api-inference.modelscope.cn/anthropic/v1/messages); this vendor
+// only selects Chat Completions;
+// - model ids are ModelScope repo ids ("Owner/Model-Name"); which of them
+// API-Inference serves changes over time — the docs state outright that
+// older models are taken offline as newer ones land, and only the model
+// page (the API-Inference panel) is authoritative;
+// - API-Inference is a free, non-commercial service with dynamic rate limits
+// and no per-token price: calls are metered in 魔粒 credits
+// (0.5 / 1 / 2 per call by model tier), which is why the entries below
+// carry a zero token cost rather than a real one;
+// - the documented scope is open LLM, multimodal (MLLM) and AIGC
+// text-to-image models.
+//
+// Unverified: the thinking switch — ModelScope documents no thinking
+// parameter, so the top-level `enable_thinking` of the DashScope/Bailian
+// channel behind API-Inference is kept as a guess, as is `max_tokens` for the
+// output cap; embedding support is not documented anywhere on the
+// API-Inference pages, so the Embedding model type and the two Qwen3-Embedding
+// entries are unconfirmed; every model id, context window, max output and
+// thinking flag below predates the current lineup, and as of 2026-09-20 none
+// of them advertises a "ModelScope" provider on
+// https://modelscope.cn/api/v1/inference/list_model_providers (models that are
+// served, such as Qwen/Qwen3.5-35B-A3B or ZhipuAI/GLM-5.2, do) — they are kept
+// because no official page states their retirement, but the list needs a
+// refresh against the model pages.
+package modelscope
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "modelscope"
+
+// BaseURL is the OpenAI-compatible inference endpoint.
+const BaseURL = "https://api-inference.modelscope.cn/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "ModelScope",
+ Names: map[string]string{"zh-CN": "魔搭 ModelScope"},
+ Description: "Qwen/Qwen3-235B-A22B-Instruct-2507, ZhipuAI/GLM-4.6, Qwen/Qwen3-Embedding-8B, etc.",
+ Website: "https://modelscope.cn",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 19,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"modelscope.cn"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatEnableThinking),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/moonshot/icon.svg b/internal/models/vendors/moonshot/icon.svg
new file mode 100644
index 000000000..ad3f92d42
--- /dev/null
+++ b/internal/models/vendors/moonshot/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Kimi</title><path d="M21.846 0a1.923 1.923 0 110 3.846H20.15a.226.226 0 01-.227-.226V1.923C19.923.861 20.784 0 21.846 0z" fill="#1783FF"></path><path d="M11.065 11.199l7.257-7.2c.137-.136.06-.41-.116-.41H14.3a.164.164 0 00-.117.051l-7.82 7.756c-.122.12-.302.013-.302-.179V3.82c0-.127-.083-.23-.185-.23H3.186c-.103 0-.186.103-.186.23V19.77c0 .128.083.23.186.23h2.69c.103 0 .186-.102.186-.23v-3.25c0-.069.025-.135.069-.178l2.424-2.406a.158.158 0 01.205-.023l6.484 4.772a7.677 7.677 0 003.453 1.283c.108.012.2-.095.2-.23v-3.06c0-.117-.07-.212-.164-.227a5.028 5.028 0 01-2.027-.807l-5.613-4.064c-.117-.078-.132-.279-.028-.381z" fill="#1783FF"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/moonshot/models.json b/internal/models/vendors/moonshot/models.json
new file mode 100644
index 000000000..fc51010d8
--- /dev/null
+++ b/internal/models/vendors/moonshot/models.json
@@ -0,0 +1,19 @@
+{
+ "vendor": "moonshot",
+ "source": "https://platform.kimi.com/docs/api/models-overview",
+ "models": [
+ {"id": "kimi-k3", "name": "Kimi K3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 3, "output": 15, "cache_read": 0.3}, "compat": {"thinking_format": "openai", "supports_reasoning_effort": true, "supports_temperature": false, "tool_choice_modes": ["none", "auto", "required"]}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://platform.kimi.com/docs/guide/kimi-k3-quickstart"},
+ {"id": "kimi-k2.7-code", "name": "Kimi K2.7 Code", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0.95, "output": 4, "cache_read": 0.19}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null}, "source": "https://platform.kimi.com/docs/guide/kimi-k2-7-code-quickstart"},
+ {"id": "kimi-k2.7-code-highspeed", "name": "Kimi K2.7 Code Highspeed", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 1.9, "output": 8, "cache_read": 0.38}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null}, "source": "https://platform.kimi.com/docs/guide/kimi-k2-7-code-quickstart"},
+ {"id": "kimi-k2.6", "name": "Kimi K2.6", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0.95, "output": 4, "cache_read": 0.16}, "compat": {"supports_temperature": false}, "source": "https://platform.kimi.com/docs/guide/kimi-k2-6-quickstart"},
+
+ {"name": "moonshot-v1 family (retired 2026-08-31)", "match": "moonshot-v1*", "reasoning": false, "input": ["text"], "deprecated": true, "compat": {"fixed_temperature": 1}, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "kimi-k2.5", "name": "Kimi K2.5 (retired 2026-08-31)", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0.6, "output": 3, "cache_read": 0.1}, "deprecated": true, "compat": {"supports_temperature": false}, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "kimi-k2-thinking", "name": "Kimi K2 Thinking (retired 2026-08-31)", "reasoning": true, "input": ["text"], "context_window": 262144, "max_output_tokens": 16384, "cost": {"input": 0.574, "output": 2.294}, "deprecated": true, "thinking_levels": {"off": null}, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "kimi-k2-turbo-preview", "name": "Kimi K2 Turbo (retired 2026-08-31)", "reasoning": false, "input": ["text"], "context_window": 262144, "max_output_tokens": 16384, "deprecated": true, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "moonshot-v1-8k", "name": "Moonshot v1 8K (retired 2026-08-31)", "reasoning": false, "input": ["text"], "context_window": 8192, "max_output_tokens": 8192, "deprecated": true, "compat": {"fixed_temperature": 1}, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "moonshot-v1-32k", "name": "Moonshot v1 32K (retired 2026-08-31)", "reasoning": false, "input": ["text"], "context_window": 32768, "max_output_tokens": 32768, "deprecated": true, "compat": {"fixed_temperature": 1}, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "moonshot-v1-128k", "name": "Moonshot v1 128K (retired 2026-08-31)", "reasoning": false, "input": ["text"], "context_window": 131072, "max_output_tokens": 131072, "deprecated": true, "compat": {"fixed_temperature": 1}, "source": "https://platform.kimi.com/docs/models"},
+ {"id": "moonshot-v1-8k-vision-preview", "name": "Moonshot v1 8K Vision (retired 2026-08-31)", "reasoning": false, "input": ["text", "image"], "context_window": 8192, "max_output_tokens": 8192, "deprecated": true, "compat": {"fixed_temperature": 1}, "source": "https://platform.kimi.com/docs/models"}
+ ]
+}
diff --git a/internal/models/vendors/moonshot/vendor.go b/internal/models/vendors/moonshot/vendor.go
new file mode 100644
index 000000000..0a6539d57
--- /dev/null
+++ b/internal/models/vendors/moonshot/vendor.go
@@ -0,0 +1,98 @@
+// Package moonshot registers Moonshot AI (Kimi).
+//
+// Facts (https://platform.kimi.com/docs/api/overview,
+// https://platform.kimi.com/docs/api/chat,
+// https://platform.kimi.com/docs/api/models-overview):
+// - the mainland base URL is https://api.moonshot.cn/v1 and the global one
+// https://api.moonshot.ai/v1 (the default here); both are recognised by
+// URL pattern. The same hosts also expose an OpenAI Responses endpoint on
+// /v1 and an Anthropic Messages endpoint on /anthropic, neither of which
+// this vendor selects;
+// - auth is `Authorization: Bearer <key>`;
+// - the output cap is `max_completion_tokens` (the protocol default);
+// `max_tokens` is still accepted but documented as deprecated;
+// - kimi-k2.6 and the kimi-k2.7-code pair switch thinking with
+// `thinking: {"type": "enabled"|"disabled"}`; k2.7-code cannot turn it off
+// (Preserved Thinking is always on), k2.6 can;
+// - kimi-k3 takes no `thinking` object at all: it always reasons and is only
+// graded through the top-level `reasoning_effort` (low | high | max,
+// default max), so that entry overrides the thinking format to openai;
+// - every current model refuses sampling parameters (temperature is pinned
+// to 1.0 on k3 / k2.7-code and to 1.0 thinking / 0.6 non-thinking on k2.6,
+// top_p to 0.95, n to 1, both penalties to 0), so none are sent;
+// - tool_choice accepts none / auto on every model and required only on
+// kimi-k3; a named function is never sent because it answers 400 while
+// thinking is enabled;
+// - response_format (text / json_object / json_schema) and
+// `stream_options: {"include_usage": true}` are supported;
+// - context caching is automatic and usage reports
+// `prompt_tokens_details.cached_tokens` / `cache_write_tokens`;
+// Anthropic-style breakpoints (`prompt_cache_breakpoint`) are rejected;
+// - moonshot-v1* (incl. the vision previews), kimi-k2.5, kimi-k2-turbo-preview
+// and kimi-k2-thinking were retired on 2026-08-31, the older kimi-k2*
+// snapshots on 2026-05-25; they stay as deprecated entries so stored model
+// rows still resolve (https://platform.kimi.com/docs/models).
+//
+// Unverified: `prompt_cache_key` / `prompt_cache_options` are documented but
+// left off, because the protocol layer pairs prompt_cache_key with OpenAI's
+// `prompt_cache_retention`, which Moonshot does not document (it uses
+// prompt_cache_options.ttl with 5m / 1h); parallel_tool_calls and seed are
+// absent from the documented request schema yet not documented as rejected, so
+// the protocol defaults are kept; the 262144 max output tokens of the K2.x
+// entries is not a documented cap (the docs only give a 32768 default); the
+// per-token costs are USD conversions of the CNY price list.
+package moonshot
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "moonshot"
+
+// BaseURL is the global OpenAI-compatible endpoint.
+const BaseURL = "https://api.moonshot.ai/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Moonshot AI",
+ Names: map[string]string{"zh-CN": "月之暗面 Moonshot"},
+ Description: "kimi-k3, kimi-k2.7-code, kimi-k2.7-code-highspeed, kimi-k2.6",
+ Website: "https://platform.kimi.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 17,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"moonshot.ai", "moonshot.cn"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ PromptCacheAccounting: catalog.Ptr(true),
+ // `required` is kimi-k3 only and a named function 400s while
+ // thinking is on, which is the default on every model.
+ ToolChoiceModes: []string{"none", "auto"},
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/novita/icon.svg b/internal/models/vendors/novita/icon.svg
new file mode 100644
index 000000000..0658ce0f0
--- /dev/null
+++ b/internal/models/vendors/novita/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Novita AI</title><path clip-rule="evenodd" d="M9.167 4.17v5.665L0 19.003h9.167v-5.666l5.666 5.666H24L9.167 4.17z" fill="#23D57C" fill-rule="evenodd"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/novita/models.json b/internal/models/vendors/novita/models.json
new file mode 100644
index 000000000..fc924f41f
--- /dev/null
+++ b/internal/models/vendors/novita/models.json
@@ -0,0 +1,21 @@
+{
+ "vendor": "novita",
+ "source": "https://docs.novita.ai/api-reference/model-apis-llm-chat-completions-api",
+ "models": [
+ {"id": "moonshotai/kimi-k3", "name": "Kimi K3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1048576, "max_output_tokens": 1048576, "cost": {"input": 3, "output": 15, "cache_read": 0.3}},
+ {"id": "zai-org/glm-5.2", "name": "GLM-5.2", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}},
+ {"id": "zai-org/glm-5.1", "name": "GLM-5.1", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 1.38, "output": 4.4, "cache_read": 0.26}},
+ {"id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 393216, "cost": {"input": 1.6, "output": 3.2, "cache_read": 0.135}},
+ {"id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 393216, "cost": {"input": 0.14, "output": 0.28, "cache_read": 0.028}},
+ {"id": "moonshotai/kimi-k2.6", "name": "Kimi K2.6", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0.8, "output": 3.4, "cache_read": 0.16}},
+ {"id": "moonshotai/kimi-k2.7-code", "name": "Kimi K2.7 Code", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0.95, "output": 4, "cache_read": 0.19}},
+ {"id": "qwen/qwen3.7-max", "name": "Qwen3.7 Max", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 1.25, "output": 3.75, "cache_read": 0.25, "cache_write": 1.5625}},
+ {"id": "qwen/qwen3.5-397b-a17b", "name": "Qwen3.5 397B-A17B", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 0.6, "output": 3.6}},
+ {"id": "minimax/minimax-m2.7", "name": "MiniMax M2.7", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.3, "output": 1.2, "cache_read": 0.06}, "thinking_levels": {"off": null}},
+ {"id": "xiaomimimo/mimo-v2.5-pro", "name": "MiMo V2.5 Pro", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 0.522, "output": 1.044, "cache_read": 0.0043}, "thinking_levels": {"off": null}},
+ {"id": "google/gemma-4-31b-it", "name": "Gemma 4 31B IT", "reasoning": true, "input": ["text", "image"], "context_window": 262144, "max_output_tokens": 131072, "cost": {"input": 0.14, "output": 0.4}},
+ {"id": "qwen/qwen3-embedding-0.6b", "name": "Qwen3 Embedding 0.6B", "type": "Embedding", "dimension": 1024, "context_window": 32768},
+ {"id": "qwen/qwen3-embedding-8b", "name": "Qwen3 Embedding 8B", "type": "Embedding", "dimension": 4096, "context_window": 32768},
+ {"id": "baai/bge-m3", "name": "BGE-M3", "type": "Embedding", "dimension": 1024, "context_window": 8192}
+ ]
+}
diff --git a/internal/models/vendors/novita/vendor.go b/internal/models/vendors/novita/vendor.go
new file mode 100644
index 000000000..5fb86a288
--- /dev/null
+++ b/internal/models/vendors/novita/vendor.go
@@ -0,0 +1,77 @@
+// Package novita registers the Novita AI gateway.
+//
+// Facts (https://docs.novita.ai — novita.ai/docs/* redirects there):
+// - chat, embedding and VLM share https://api.novita.ai/openai/v1;
+// /v1/rerank, /v1/completions, /v1/batches and /v1/files sit alongside;
+// - output cap is `max_tokens`, documented as required;
+// `max_completion_tokens` is never mentioned;
+// - the thinking switch is a **top-level** `enable_thinking` boolean
+// (default true) — "Controls the switches between thinking and
+// non-thinking modes" — not `chat_template_kwargs.enable_thinking` and
+// not `reasoning_effort`, neither of which appears anywhere in the docs.
+// There is no graded effort, so supports_reasoning_effort stays off and
+// models that cannot stop reasoning are marked "off": null.
+//
+// Unverified:
+// - the documented enable_thinking support list still names glm-4.5 and
+// deepseek-v3.1/v3.2-exp, so whether the current flagships (glm-5.x,
+// deepseek-v4-*, kimi-k3, minimax-m2.7) honour it is not stated. The
+// switch is only sent when a caller asks for one, so a model that
+// ignores it degrades to its own default rather than failing;
+// - the three embedding entries are served by the API but the embeddings
+// reference restricts `model` to a single enum value (baai/bge-m3), and
+// they are absent from the default /v1/models listing.
+package novita
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "novita"
+
+// BaseURL is the OpenAI-compatible gateway endpoint.
+const BaseURL = "https://api.novita.ai/openai/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Novita AI",
+ Names: map[string]string{"zh-CN": "Novita AI"},
+ Description: "moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-pro, qwen/qwen3-embedding-0.6b, etc.",
+ Website: "https://novita.ai",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 52,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"api.novita.ai", "novita.ai"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatEnableThinking),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/nvidia/icon.svg b/internal/models/vendors/nvidia/icon.svg
new file mode 100644
index 000000000..a9683c2e0
--- /dev/null
+++ b/internal/models/vendors/nvidia/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Nvidia</title><path d="M10.212 8.976V7.62c.127-.01.256-.017.388-.021 3.596-.117 5.957 3.184 5.957 3.184s-2.548 3.647-5.282 3.647a3.227 3.227 0 01-1.063-.175v-4.109c1.4.174 1.681.812 2.523 2.258l1.873-1.627a4.905 4.905 0 00-3.67-1.846 6.594 6.594 0 00-.729.044m0-4.476v2.025c.13-.01.259-.019.388-.024 5.002-.174 8.261 4.226 8.261 4.226s-3.743 4.69-7.643 4.69c-.338 0-.675-.031-1.007-.092v1.25c.278.038.558.057.838.057 3.629 0 6.253-1.91 8.794-4.169.421.347 2.146 1.193 2.501 1.564-2.416 2.083-8.048 3.763-11.24 3.763-.308 0-.603-.02-.894-.048V19.5H24v-15H10.21zm0 9.756v1.068c-3.356-.616-4.287-4.21-4.287-4.21a7.173 7.173 0 014.287-2.138v1.172h-.005a3.182 3.182 0 00-2.502 1.178s.615 2.276 2.507 2.931m-5.961-3.3c1.436-1.935 3.604-3.148 5.961-3.336V6.523C5.81 6.887 2 10.723 2 10.723s2.158 6.427 8.21 7.015v-1.166C5.77 16 4.25 10.958 4.25 10.958h-.002z" fill="#74B71B" fill-rule="nonzero"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/nvidia/models.json b/internal/models/vendors/nvidia/models.json
new file mode 100644
index 000000000..9d0a0f745
--- /dev/null
+++ b/internal/models/vendors/nvidia/models.json
@@ -0,0 +1,21 @@
+{
+ "vendor": "nvidia",
+ "source": "https://build.nvidia.com",
+ "models": [
+ {"id": "nvidia/nemotron-3-ultra-550b-a55b", "name": "Nemotron 3 Ultra 550B-A55B", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 65536, "cost": {"input": 0.5, "output": 2.5, "cache_read": 0.15}},
+ {"id": "nvidia/nemotron-3-super-120b-a12b", "name": "Nemotron 3 Super 120B-A12B", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 262144, "cost": {"input": 0.2, "output": 0.8}},
+ {"id": "nvidia/nemotron-3.5-lightning-30b-a3b", "name": "Nemotron 3.5 Lightning 30B-A3B", "reasoning": true, "input": ["text"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0, "output": 0}},
+ {"id": "z-ai/glm-5.3", "name": "GLM-5.3", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 0, "output": 0}, "thinking_levels": {"off": null, "minimal": "low", "medium": "high", "xhigh": "max", "max": "max"}},
+ {"id": "deepseek-ai/deepseek-v4-pro-0813", "name": "DeepSeek V4 Pro", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 393216, "cost": {"input": 0.435, "output": 0.87, "cache_read": 0.003625}},
+ {"id": "deepseek-ai/deepseek-v4-flash-0731", "name": "DeepSeek V4 Flash", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 393216, "cost": {"input": 0.14, "output": 0.28, "cache_read": 0.0028}},
+ {"id": "moonshotai/kimi-k3", "name": "Kimi K3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1048576, "max_output_tokens": 131072, "cost": {"input": 0, "output": 0}, "compat": {"max_tokens_field": "max_completion_tokens"}, "thinking_levels": {"off": null, "minimal": "low", "medium": "high", "xhigh": "max", "max": "max"}},
+ {"id": "moonshotai/kimi-k2.6", "name": "Kimi K2.6", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 262144, "cost": {"input": 0, "output": 0}},
+ {"id": "google/gemma-4-31b-it", "name": "Gemma 4 31B IT", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 16384, "cost": {"input": 0, "output": 0}, "compat": {"max_tokens_field": "max_completion_tokens", "thinking_format": "none"}},
+ {"id": "nvidia/nv-embed-v1", "name": "NV-Embed v1", "type": "Embedding", "dimension": 4096, "context_window": 32768},
+ {"id": "nvidia/nemotron-3-embed-1b", "name": "Nemotron 3 Embed 1B", "type": "Embedding", "dimension": 2048, "context_window": 32768},
+ {"id": "nvidia/llama-3.2-nemoretriever-300m-embed-v1", "name": "Llama 3.2 NemoRetriever 300M Embed v1", "type": "Embedding", "dimension": 2048, "context_window": 8192},
+ {"id": "baai/bge-m3", "name": "BGE-M3", "type": "Embedding", "dimension": 1024, "context_window": 8192},
+ {"id": "nvidia/llama-nemotron-rerank-vl-1b-v2", "name": "Llama Nemotron Rerank VL 1B v2", "type": "Rerank"},
+ {"id": "nvidia/nv-rerankqa-mistral-4b-v3", "name": "NV-RerankQA Mistral 4B v3", "type": "Rerank"}
+ ]
+}
diff --git a/internal/models/vendors/nvidia/vendor.go b/internal/models/vendors/nvidia/vendor.go
new file mode 100644
index 000000000..425fcfd0e
--- /dev/null
+++ b/internal/models/vendors/nvidia/vendor.go
@@ -0,0 +1,102 @@
+// Package nvidia registers NVIDIA NIM's hosted API (build.nvidia.com).
+//
+// Facts (https://docs.api.nvidia.com/nim/ and the per-model cards on
+// https://build.nvidia.com):
+// - chat, embedding and VLM share https://integrate.api.nvidia.com/v1 with
+// `Authorization: Bearer`; rerank is a separate host,
+// https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking, whose body is
+// {query, passages, model, truncate} with at most 512 passages. Current
+// rerank NIMs also expose a per-model path
+// (.../retrieval/nvidia/<slug>/reranking); the shared path stays live and
+// is what legacy rerank models answer on;
+// - the output cap field is mixed per model. NVIDIA's own curl and Python
+// samples use `max_tokens`, so that is the vendor default, but the cards
+// for kimi-k3 and gemma-4-31b-it show `max_completion_tokens`; those
+// entries override it. The LLM API reference defers to the vLLM
+// OpenAI-server schema rather than pinning either field;
+// - thinking has no single encoding on NIM. Nemotron 3 takes
+// `chat_template_kwargs: {"enable_thinking": bool}` (the vendor default
+// here), DeepSeek V4 takes `chat_template_kwargs: {"thinking": bool,
+// "reasoning_effort": ...}`, GLM-5.3 takes a top-level `reasoning_effort`
+// defaulting to max, MiniMax M3 takes `thinking_mode`, and Gemma 4
+// switches thinking with a `<|think|>` token in the system prompt rather
+// than any parameter — which is why the gemma entry sets thinking_format
+// "none" instead of pretending a switch exists;
+// - most hosted endpoints are metered at zero cost; the Nemotron and
+// DeepSeek endpoints are priced.
+//
+// Unverified:
+// - embedding dimensions (nv-embed-v1 4096, nemoretriever-300m 2048,
+// nemotron-3-embed-1b 2048, bge-m3 1024) come from the model cards;
+// nv-embed-v1's 32768 context is not restated in the current card;
+// - `minimaxai/minimax-m3`, `minimaxai/minimax-m2.7` and
+// `mistralai/mistral-medium-3.5-128b` have live build.nvidia.com pages
+// whose samples ship an empty `model=""`, so the exact org-prefixed id
+// could not be confirmed; they are left out rather than guessed;
+// - `nvidia/rerank-qa-mistral-4b` (the previous entry here) has no
+// per-model rerank route and one source reports a 2026-08-24
+// deprecation, so it was replaced with nv-rerankqa-mistral-4b-v3 and the
+// current llama-nemotron-rerank-vl-1b-v2;
+// - DeepSeek on NIM wants `reasoning_effort` nested inside
+// chat_template_kwargs, which this compat model cannot express: it emits
+// either a chat-template switch or a top-level effort, never both.
+package nvidia
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "nvidia"
+
+// BaseURL serves chat, embedding and VLM.
+const BaseURL = "https://integrate.api.nvidia.com/v1"
+
+// RerankBaseURL is the retrieval reranking NIM.
+const RerankBaseURL = "https://ai.api.nvidia.com/v1/retrieval/nvidia/reranking"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "NVIDIA",
+ Names: map[string]string{"zh-CN": "NVIDIA"},
+ Description: "nvidia/nemotron-3-ultra-550b-a55b, deepseek-ai/deepseek-v4-pro-0813, " +
+ "nvidia/nv-embed-v1, nvidia/nv-rerankqa-mistral-4b-v3, etc.",
+ Website: "https://build.nvidia.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 51,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"nvidia.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: RerankBaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatChatTemplateKwargs),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/openai/icon.svg b/internal/models/vendors/openai/icon.svg
new file mode 100644
index 000000000..78caf4fa2
--- /dev/null
+++ b/internal/models/vendors/openai/icon.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>OpenAI</title><path d="M9.205 8.658v-2.26c0-.19.072-.333.238-.428l4.543-2.616c.619-.357 1.356-.523 2.117-.523 2.854 0 4.662 2.212 4.662 4.566 0 .167 0 .357-.024.547l-4.71-2.759a.797.797 0 00-.856 0l-5.97 3.473zm10.609 8.8V12.06c0-.333-.143-.57-.429-.737l-5.97-3.473 1.95-1.118a.433.433 0 01.476 0l4.543 2.617c1.309.76 2.189 2.378 2.189 3.948 0 1.808-1.07 3.473-2.76 4.163zM7.802 12.703l-1.95-1.142c-.167-.095-.239-.238-.239-.428V5.899c0-2.545 1.95-4.472 4.591-4.472 1 0 1.927.333 2.712.928L8.23 5.067c-.285.166-.428.404-.428.737v6.898zM12 15.128l-2.795-1.57v-3.33L12 8.658l2.795 1.57v3.33L12 15.128zm1.796 7.23c-1 0-1.927-.332-2.712-.927l4.686-2.712c.285-.166.428-.404.428-.737v-6.898l1.974 1.142c.167.095.238.238.238.428v5.233c0 2.545-1.974 4.472-4.614 4.472zm-5.637-5.303l-4.544-2.617c-1.308-.761-2.188-2.378-2.188-3.948A4.482 4.482 0 014.21 6.327v5.423c0 .333.143.571.428.738l5.947 3.449-1.95 1.118a.432.432 0 01-.476 0zm-.262 3.9c-2.688 0-4.662-2.021-4.662-4.519 0-.19.024-.38.047-.57l4.686 2.71c.286.167.571.167.856 0l5.97-3.448v2.26c0 .19-.07.333-.237.428l-4.543 2.616c-.619.357-1.356.523-2.117.523zm5.899 2.83a5.947 5.947 0 005.827-4.756C22.287 18.339 24 15.84 24 13.296c0-1.665-.713-3.282-1.998-4.448.119-.5.19-.999.19-1.498 0-3.401-2.759-5.947-5.946-5.947-.642 0-1.26.095-1.88.31A5.962 5.962 0 0010.205 0a5.947 5.947 0 00-5.827 4.757C1.713 5.447 0 7.945 0 10.49c0 1.666.713 3.283 1.998 4.448-.119.5-.19 1-.19 1.499 0 3.401 2.759 5.946 5.946 5.946.642 0 1.26-.095 1.88-.309a5.96 5.96 0 004.162 1.713z"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/openai/models.json b/internal/models/vendors/openai/models.json
new file mode 100644
index 000000000..89b805427
--- /dev/null
+++ b/internal/models/vendors/openai/models.json
@@ -0,0 +1,34 @@
+{
+ "vendor": "openai",
+ "source": "https://developers.openai.com/api/docs/models",
+ "models": [
+ {"name": "GPT-6 family (reasoning, no sampling parameters, thinking always on)", "match": "gpt-6*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}, "source": "https://developers.openai.com/api/docs/guides/latest-model"},
+ {"name": "GPT-5 family (reasoning, no sampling parameters)", "match": "gpt-5*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low"}, "source": "https://developers.openai.com/api/docs/guides/reasoning"},
+ {"name": "o1 family (always-on reasoning)", "match": "o1*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"name": "o3 family (always-on reasoning)", "match": "o3*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"name": "o4 family (always-on reasoning)", "match": "o4*", "reasoning": true, "input": ["text", "image"], "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+
+ {"id": "gpt-6-astra", "name": "GPT-6 Astra", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 10, "output": 50, "cache_read": 1, "cache_write": 12.5}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "gpt-5.6-terra", "name": "GPT-5.6 Terra", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 2, "output": 12, "cache_read": 0.2, "cache_write": 2.5}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "gpt-5.6-sol", "name": "GPT-5.6 Sol", "aliases": ["gpt-5.6"], "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 4, "output": 20, "cache_read": 0.4, "cache_write": 5}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "gpt-5.6-luna", "name": "GPT-5.6 Luna", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 0.2, "output": 1.2, "cache_read": 0.02, "cache_write": 0.25}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "gpt-5.5", "name": "GPT-5.5", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 30, "cache_read": 0.5}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "gpt-5.4", "name": "GPT-5.4", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 2.5, "output": 15, "cache_read": 0.25}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "gpt-5.4-mini", "name": "GPT-5.4 Mini", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 0.75, "output": 4.5, "cache_read": 0.075}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "gpt-5.4-nano", "name": "GPT-5.4 Nano", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 0.2, "output": 1.25, "cache_read": 0.02}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "gpt-5.2", "name": "GPT-5.2", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 1.75, "output": 14, "cache_read": 0.175}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "gpt-5.1", "name": "GPT-5.1", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 1.25, "output": 10, "cache_read": 0.125}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"id": "gpt-5", "name": "GPT-5", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 1.25, "output": 10, "cache_read": 0.125}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "xhigh": "high", "max": "high"}},
+ {"id": "gpt-5-mini", "name": "GPT-5 Mini", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 0.25, "output": 2, "cache_read": 0.025}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "xhigh": "high", "max": "high"}},
+ {"id": "gpt-5-nano", "name": "GPT-5 Nano", "reasoning": true, "input": ["text", "image"], "context_window": 400000, "max_output_tokens": 128000, "cost": {"input": 0.05, "output": 0.4, "cache_read": 0.005}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "xhigh": "high", "max": "high"}},
+ {"id": "o3", "name": "o3", "reasoning": true, "input": ["text", "image"], "context_window": 200000, "max_output_tokens": 100000, "cost": {"input": 2, "output": 8, "cache_read": 0.5}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"id": "gpt-4.1", "name": "GPT-4.1", "reasoning": false, "input": ["text", "image"], "context_window": 1047576, "max_output_tokens": 32768, "cost": {"input": 2, "output": 8, "cache_read": 0.5}},
+ {"id": "gpt-4.1-mini", "name": "GPT-4.1 Mini", "reasoning": false, "input": ["text", "image"], "context_window": 1047576, "max_output_tokens": 32768, "cost": {"input": 0.4, "output": 1.6, "cache_read": 0.1}},
+ {"id": "gpt-4o", "name": "GPT-4o", "aliases": ["gpt-4o-2024-11-20", "gpt-4o-2024-08-06"], "reasoning": false, "input": ["text", "image"], "context_window": 128000, "max_output_tokens": 16384, "cost": {"input": 2.5, "output": 10, "cache_read": 1.25}},
+ {"id": "gpt-4o-mini", "name": "GPT-4o Mini", "reasoning": false, "input": ["text", "image"], "context_window": 128000, "max_output_tokens": 16384, "cost": {"input": 0.15, "output": 0.6, "cache_read": 0.075}},
+
+ {"id": "text-embedding-3-small", "name": "text-embedding-3-small", "type": "Embedding", "dimension": 1536, "context_window": 8191, "cost": {"input": 0.02, "output": 0}},
+ {"id": "text-embedding-3-large", "name": "text-embedding-3-large", "type": "Embedding", "dimension": 3072, "context_window": 8191, "cost": {"input": 0.13, "output": 0}},
+ {"id": "text-embedding-ada-002", "name": "text-embedding-ada-002", "type": "Embedding", "dimension": 1536, "context_window": 8192, "cost": {"input": 0.1, "output": 0}}
+ ]
+}
diff --git a/internal/models/vendors/openai/vendor.go b/internal/models/vendors/openai/vendor.go
new file mode 100644
index 000000000..cf23b5308
--- /dev/null
+++ b/internal/models/vendors/openai/vendor.go
@@ -0,0 +1,126 @@
+// Package openai registers OpenAI's first-party platform.
+//
+// Facts (https://developers.openai.com/api/docs — platform.openai.com/docs
+// now redirects there):
+// - output cap is `max_completion_tokens` (`max_tokens` is one of the
+// parameters reasoning models reject outright);
+// - thinking is graded with `reasoning_effort` only. The full vocabulary is
+// none | minimal | low | medium | high | xhigh | max and every model takes
+// a subset: `minimal` exists only on the original GPT-5 trio and is gone
+// from gpt-5.1 and later, so the gpt-5* family folds minimal onto low;
+// `none` is accepted from gpt-5.1 through gpt-5.6 but rejected by GPT-5,
+// the o-series and GPT-6 Astra, which are therefore "off": null;
+// `xhigh` is limited to GPT-6, GPT-5.6, GPT-5.5 and GPT-5.4, and `max`
+// to GPT-6 and GPT-5.6
+// (https://developers.openai.com/api/docs/guides/reasoning, and the
+// per-model support matrix Microsoft publishes for the same models at
+// https://learn.microsoft.com/azure/ai-foundry/openai/how-to/reasoning);
+// - reasoning models take the `developer` role instead of `system`, and
+// reject temperature, top_p, presence_penalty, frequency_penalty,
+// logprobs, top_logprobs, logit_bias and max_tokens, so the gpt-6* /
+// gpt-5* / o1* / o3* / o4* families set supports_temperature false;
+// - `store: false` is sent so completions are not retained, and
+// `prompt_cache_key` steers cache routing; usage reports cached tokens;
+// - every model type (chat, embedding, rerank via generic clients, VLM,
+// ASR) is served from https://api.openai.com/v1;
+// - requests that go to api.openai.com itself use the Responses protocol
+// (https://developers.openai.com/api/docs/api-reference/responses),
+// OpenAI's primary API where reasoning items and encrypted reasoning are
+// replayable; relays and proxies that only speak Chat Completions keep
+// that protocol because their base URL is not api.openai.com. Operators
+// can force either with extra_config.api. Two documented Chat Completions
+// restrictions make Responses the right default rather than a preference:
+// `reasoning_effort: "max"` is Responses-only, and on GPT-5.6 models Chat
+// Completions rejects `tools` together with any effort other than "none"
+// ("Function tools with reasoning_effort are not supported ... in
+// /v1/chat/completions. To use function tools, use /v1/responses").
+// A relay pinned to Chat Completions therefore cannot combine tools with
+// graded thinking on those models; that is the relay's limit, not ours.
+//
+// Unverified: `o1-mini` does not accept `reasoning_effort` at all, but the
+// o1* family entry cannot express a single-model exception without shadowing
+// the pattern, so the vendor-level supports_reasoning_effort still applies to
+// it. Responses-only compat (prompt-cache retention, reasoning summaries)
+// cannot be set per model here either: a models.json `compat` object is read
+// against the entry's own API, and these entries are Chat Completions
+// entries. GPT-5.6 and later replaced `prompt_cache_retention` with
+// `prompt_cache_options.ttl`, which the protocol layer does not send yet.
+package openai
+
+import (
+ _ "embed"
+ "net/url"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "openai"
+
+// BaseURL is the documented first-party endpoint.
+const BaseURL = "https://api.openai.com/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "OpenAI",
+ Names: map[string]string{"zh-CN": "OpenAI"},
+ Description: "gpt-6-astra, gpt-5.6-sol, gpt-5.5, gpt-4.1, text-embedding-3-large, etc.",
+ Website: "https://developers.openai.com",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 30,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"api.openai.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ types.ModelTypeASR: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ types.ModelTypeASR,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatOpenAI),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ SupportsDeveloperRole: catalog.Ptr(true),
+ SupportsStore: catalog.Ptr(true),
+ PromptCacheKey: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ PreferAPI: preferResponsesOnFirstParty,
+ })
+}
+
+// preferResponsesOnFirstParty switches chat traffic aimed at api.openai.com
+// to the Responses protocol. Anything else (Azure-style relays, LiteLLM,
+// enterprise gateways) keeps Chat Completions, the protocol they document.
+func preferResponsesOnFirstParty(baseURL string, spec catalog.ModelSpec) api.API {
+ if spec.Type != "" && spec.Type != types.ModelTypeKnowledgeQA {
+ return ""
+ }
+ u, err := url.Parse(strings.TrimSpace(baseURL))
+ if err != nil || !strings.EqualFold(u.Hostname(), "api.openai.com") {
+ return ""
+ }
+ return api.APIOpenAIResponses
+}
diff --git a/internal/models/vendors/openrouter/icon.svg b/internal/models/vendors/openrouter/icon.svg
new file mode 100644
index 000000000..029070c88
--- /dev/null
+++ b/internal/models/vendors/openrouter/icon.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>OpenRouter</title><path d="M18.654 3.87a5.087 5.087 0 110 10.174L23.7 19.09c.64.641.187 1.737-.72 1.737H8.48a8.479 8.479 0 010-16.958h10.175zM8.479 7.26a5.087 5.087 0 100 10.176 5.087 5.087 0 000-10.175z"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/openrouter/models.json b/internal/models/vendors/openrouter/models.json
new file mode 100644
index 000000000..7360d5ddd
--- /dev/null
+++ b/internal/models/vendors/openrouter/models.json
@@ -0,0 +1,23 @@
+{
+ "vendor": "openrouter",
+ "source": "https://openrouter.ai/docs/guides/best-practices/reasoning-tokens",
+ "models": [
+ {"name": "Anthropic models (cache_control breakpoints, thinking always on)", "match": "anthropic/*", "reasoning": true, "input": ["text", "image"], "compat": {"cache_control_format": "anthropic"}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "openai/gpt-5.5", "name": "GPT-5.5", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 30, "cache_read": 0.5}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "openai/gpt-5.4", "name": "GPT-5.4", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "cost": {"input": 2.5, "output": 15, "cache_read": 0.25}, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "anthropic/claude-opus-5", "name": "Claude Opus 5", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}, "compat": {"cache_control_format": "anthropic"}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "anthropic/claude-sonnet-5", "name": "Claude Sonnet 5", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 2, "output": 10, "cache_read": 0.2, "cache_write": 2.5}, "compat": {"cache_control_format": "anthropic"}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "cost": {"input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75}, "compat": {"cache_control_format": "anthropic"}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "max", "max": "max"}},
+ {"id": "google/gemini-3.8-flash", "name": "Gemini 3.8 Flash", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 0.75, "output": 3.75, "cache_read": 0.075, "cache_write": 0.041667}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"id": "google/gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro Preview", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "cost": {"input": 2, "output": 12, "cache_read": 0.2, "cache_write": 0.375}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "high", "max": "high"}},
+ {"id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 384000, "cost": {"input": 1.6, "output": 3.2, "cache_read": 0.135}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 384000, "cost": {"input": 0.07, "output": 0.14, "cache_read": 0.014}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "z-ai/glm-5.3", "name": "GLM-5.3", "reasoning": true, "input": ["text"], "context_window": 1310720, "max_output_tokens": 131072, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}, "thinking_levels": {"off": null, "minimal": "low", "medium": "high", "xhigh": "max", "max": "max"}},
+ {"id": "moonshotai/kimi-k3", "name": "Kimi K3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1048576, "max_output_tokens": 943718, "cost": {"input": 3, "output": 15, "cache_read": 0.3}, "thinking_levels": {"minimal": "low", "medium": "high", "xhigh": "max", "max": "max"}},
+ {"id": "qwen/qwen3.7-max", "name": "Qwen3.7 Max", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 1.475, "output": 4.425, "cache_read": 0.295, "cache_write": 1.84375}},
+ {"id": "minimax/minimax-m3", "name": "MiniMax M3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1048576, "max_output_tokens": 512000, "cost": {"input": 0.3, "output": 1.2, "cache_read": 0.06}},
+ {"id": "x-ai/grok-4.6", "name": "Grok 4.6", "reasoning": true, "input": ["text", "image"], "context_window": 500000, "max_output_tokens": 450000, "cost": {"input": 2, "output": 6, "cache_read": 0.5}, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "openai/text-embedding-3-small", "name": "text-embedding-3-small", "type": "Embedding", "dimension": 1536, "context_window": 8192, "source": "https://openrouter.ai/docs/api_reference/embeddings"},
+ {"id": "openai/text-embedding-3-large", "name": "text-embedding-3-large", "type": "Embedding", "dimension": 3072, "context_window": 8192, "source": "https://openrouter.ai/docs/api_reference/embeddings"}
+ ]
+}
diff --git a/internal/models/vendors/openrouter/vendor.go b/internal/models/vendors/openrouter/vendor.go
new file mode 100644
index 000000000..c01abfb1e
--- /dev/null
+++ b/internal/models/vendors/openrouter/vendor.go
@@ -0,0 +1,93 @@
+// Package openrouter registers the OpenRouter gateway.
+//
+// Facts (https://openrouter.ai/docs/guides/best-practices/reasoning-tokens —
+// the old /docs/use-cases/ path now redirects there):
+// - `max_tokens` is documented as deprecated ("Maximum tokens
+// (deprecated, use max_completion_tokens)") and some upstreams enforce a
+// minimum of 16 on it, so this vendor keeps the protocol default
+// `max_completion_tokens`;
+// - thinking is expressed with the unified `reasoning` object
+// ({"effort": ...} or {"enabled": bool}) which OpenRouter translates for
+// every upstream. The effort enum is
+// max | xhigh | high | medium | low | minimal | none, which is why xhigh
+// and max are enabled vendor-wide; per-model support is gated by
+// `supported_efforts` in /api/v1/models, and models flagged mandatory
+// (today gemini-3.8-flash, gemini-3.1-pro-preview, glm-5.3, grok-4.6)
+// reject an off switch entirely. Claude upstreams reject "none" and send
+// minimal as low, so the anthropic/* family is "off": null with minimal
+// folded onto low;
+// - Anthropic-routed models honour `cache_control` breakpoints, ephemeral
+// with a 5m or 1h ttl and at most four explicit breakpoints (the
+// anthropic/* family sets cache_control_format "anthropic");
+// - `prompt_cache_key` is accepted as the sticky routing key (OpenRouter's
+// own preferred field is `session_id`) and usage reports
+// prompt_tokens_details.cached_tokens;
+// - embeddings are routed through the same /api/v1 base
+// (https://openrouter.ai/docs/api_reference/embeddings).
+//
+// Unverified: GET /api/v1/models lists chat models only — embedding models
+// live behind /api/v1/embeddings/models — so any future auto-sync of this
+// catalog has to read both listings or it will silently lose embeddings.
+package openrouter
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "openrouter"
+
+// BaseURL is the OpenAI-compatible gateway endpoint.
+const BaseURL = "https://openrouter.ai/api/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "OpenRouter",
+ Names: map[string]string{"zh-CN": "OpenRouter"},
+ Description: "openai/gpt-5.5, anthropic/claude-opus-5, google/gemini-3.8-flash, " +
+ "deepseek/deepseek-v4-pro, etc.",
+ Website: "https://openrouter.ai",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 40,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"openrouter.ai"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatOpenRouter),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ PromptCacheKey: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ // The reasoning.effort enum covers the whole ladder; per-model
+ // support is gated upstream, not here.
+ ThinkingLevels: api.ThinkingLevelMap{
+ api.ReasoningXHigh: api.StringPtr("xhigh"),
+ api.ReasoningMax: api.StringPtr("max"),
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/qianfan/icon.svg b/internal/models/vendors/qianfan/icon.svg
new file mode 100644
index 000000000..40565efc0
--- /dev/null
+++ b/internal/models/vendors/qianfan/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>BaiduCloud</title><path d="M21.715 5.61l-3.983 2.31a.903.903 0 01-.896 0L12.44 5.384a.903.903 0 00-.897 0L7.156 7.92a.903.903 0 01-.896 0L2.276 5.617 12.002 0l9.713 5.61z" fill="#5BCA87"></path><path d="M18.641 9.467a.89.89 0 00-.438.77v5.072a.896.896 0 01-.445.77l-4.428 2.51a.884.884 0 00-.445.777v4.607l4.429-2.536 5.31-3.047V7.157l-3.983 2.31z" fill="#EC5D3E"></path><path d="M10.98 18.941a.936.936 0 00-.305-.352l-4.429-2.516a.903.903 0 01-.431-.764v-5.078a.89.89 0 00-.452-.757l-.451-.26L1.38 7.158V18.39l5.311 3.047L11.126 24v-4.608a.881.881 0 00-.146-.45z" fill="#2464F5"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/qianfan/models.json b/internal/models/vendors/qianfan/models.json
new file mode 100644
index 000000000..c0abc74ad
--- /dev/null
+++ b/internal/models/vendors/qianfan/models.json
@@ -0,0 +1,15 @@
+{
+ "vendor": "qianfan",
+ "source": "https://cloud.baidu.com/doc/qianfan-docs/s/7m95lyy43",
+ "models": [
+ {"id": "ernie-5.0-thinking-preview", "name": "ERNIE 5.0 Thinking Preview", "reasoning": true, "input": ["text", "image"], "context_window": 128000, "max_output_tokens": 65536, "source": "https://cloud.baidu.com/doc/qianfan-docs/s/Wm95lyynv"},
+ {"id": "ernie-4.5-turbo-128k", "name": "ERNIE 4.5 Turbo 128K", "reasoning": false, "input": ["text"], "context_window": 128000, "max_output_tokens": 12288},
+ {"id": "ernie-4.5-turbo-vl-32k", "name": "ERNIE 4.5 Turbo VL 32K", "reasoning": false, "input": ["text", "image"], "context_window": 32000, "max_output_tokens": 12288},
+ {"id": "ernie-x1-turbo-32k", "name": "ERNIE X1 Turbo 32K", "reasoning": true, "input": ["text"], "context_window": 32000, "max_output_tokens": 16000, "thinking_levels": {"off": null}},
+ {"id": "deepseek-v3.2", "name": "DeepSeek V3.2 (Qianfan)", "reasoning": true, "input": ["text"], "context_window": 128000, "max_output_tokens": 32000, "compat": {"thinking_format": "thinking-type"}, "source": "https://cloud.baidu.com/doc/qianfan-docs/s/Wm95lyynv"},
+ {"id": "embedding-v1", "name": "Embedding-V1", "type": "Embedding", "dimension": 384, "source": "https://cloud.baidu.com/doc/qianfan-api/s/Fm7u3ropn"},
+ {"id": "bge-large-zh", "name": "BGE Large ZH", "type": "Embedding", "dimension": 1024, "source": "https://cloud.baidu.com/doc/qianfan-api/s/Fm7u3ropn"},
+ {"id": "tao-8k", "name": "Tao-8K", "type": "Embedding", "dimension": 1024, "source": "https://cloud.baidu.com/doc/qianfan-api/s/Fm7u3ropn"},
+ {"id": "bce-reranker-base", "name": "BCE Reranker Base", "type": "Rerank"}
+ ]
+}
diff --git a/internal/models/vendors/qianfan/vendor.go b/internal/models/vendors/qianfan/vendor.go
new file mode 100644
index 000000000..316ef2e9f
--- /dev/null
+++ b/internal/models/vendors/qianfan/vendor.go
@@ -0,0 +1,115 @@
+// Package qianfan registers Baidu AI Cloud Qianfan through its
+// OpenAI-compatible v2 endpoint.
+//
+// Facts (v2 text generation reference
+// https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb, auth
+// https://cloud.baidu.com/doc/qianfan-api/s/ym9chdsy5):
+// - one host serves every model type: chat is POST /v2/chat/completions,
+// embeddings POST /v2/embeddings
+// (https://cloud.baidu.com/doc/qianfan-api/s/Fm7u3ropn) and rerank
+// POST /v2/rerank, so all model types share the /v2 base URL;
+// - auth is `Authorization: Bearer <API Key>` and nothing else. The
+// console-issued `appid` header is optional on v2 and is not a
+// credential, so the vendor exposes no extra fields;
+// - both `max_tokens` (final answer only) and `max_completion_tokens`
+// (answer plus thinking chain) are accepted; we send
+// max_completion_tokens because it is the one that bounds the whole
+// generation of a thinking model;
+// - tool_choice takes none / auto / required / a named function,
+// parallel_tool_calls defaults to true, response_format takes
+// text / json_object / json_schema, seed is accepted and
+// stream_options.include_usage is supported, so every protocol
+// default holds unchanged;
+// - usage carries prompt_tokens_details.cached_tokens, so the vendor
+// does report prompt-cache counters (Baidu documents the counter for
+// a subset of the ERNIE models only);
+// - thinking (https://cloud.baidu.com/doc/qianfan-docs/s/Wm95lyynv):
+// the ERNIE and Qwen3 families switch it with `enable_thinking`
+// (default false, except ernie-5.0-thinking-preview which defaults to
+// true), while the DeepSeek / GLM / Kimi routes use
+// `thinking: {"type": "enabled"|"disabled"}` and carry that as a
+// per-model compat overlay in models.json. The chain length is capped
+// by the top-level `thinking_budget` (default 16384, minimum 100).
+// `reasoning_effort` (high | max) exists only on deepseek-v4-pro and
+// deepseek-v4-flash, which this catalog does not list, so the vendor
+// level never sends it.
+//
+// Unverified:
+// - neither a mandatory thinking switch nor a non-stream restriction is
+// documented, so thinking_always_send and thinking_disable_on_non_stream
+// stay off;
+// - prompt_cache_key and Anthropic-style cache_control are not
+// documented anywhere; only the usage counter above is;
+// - ernie-x1-turbo-32k no longer appears in the model list
+// (https://cloud.baidu.com/doc/qianfan-docs/s/7m95lyy43) but no
+// retirement notice was found, so the entry is kept unchanged,
+// including its always-on "off": null;
+// - ernie-4.5-turbo-vl-32k is listed without thinking while the
+// `-preview` variant of the same family has it, so the entry stays
+// reasoning: false;
+// - the DeepSeek routes reject temperature / top_p / presence_penalty /
+// frequency_penalty *while thinking*, but the docs give no rule for
+// the non-thinking path, so supports_temperature is left alone;
+// - Qianfan also exposes a Responses API
+// (https://cloud.baidu.com/doc/qianfan-docs/s/4mi400l1m); this vendor
+// stays on Chat Completions, which is what the model pages document.
+package qianfan
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "qianfan"
+
+// BaseURL is the OpenAI-compatible v2 endpoint for every model type.
+const BaseURL = "https://qianfan.baidubce.com/v2"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Baidu Qianfan",
+ Names: map[string]string{"zh-CN": "百度千帆 Baidu Cloud"},
+ Description: "ernie-5.0-thinking-preview, ernie-4.5-turbo-128k, embedding-v1, bce-reranker-base, etc.",
+ Website: "https://console.bce.baidu.com/qianfan",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 20,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"qianfan.baidubce.com", "baidubce.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ // Both spellings are accepted; max_completion_tokens is the
+ // one that also covers the thinking chain.
+ MaxTokensField: catalog.Ptr("max_completion_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatEnableThinking),
+ ThinkingBudgetField: catalog.Ptr("thinking_budget"),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/qiniu/icon.svg b/internal/models/vendors/qiniu/icon.svg
new file mode 100644
index 000000000..8057b68d2
--- /dev/null
+++ b/internal/models/vendors/qiniu/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Qiniu</title><path d="M23.111 4.6a.914.914 0 00-.861.161A13.443 13.443 0 017.947 8.897L7.38 6.831a1.076 1.076 0 00-1.211-.698l.27 2.18c-1.816-.827-2.313-.946-3.587-2.45C2.674 5.729 1.263 4.472.89 4.6a11.906 11.906 0 005.892 6.497l.738 5.97s.33 2.286 2.473 2.286h4.586c2.144 0 2.474-2.286 2.474-2.286l.518-4.28c-1.393-.11-2.268.857-2.546 1.814-.465 1.614-.465 1.716-.557 1.998-.188.575-.806.644-.806.644h-2.753s-.617-.07-.806-.644c-.12-.371-.727-2.54-1.335-4.74A11.877 11.877 0 0023.11 4.599V4.6z" fill="#06AEEF"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/qiniu/models.json b/internal/models/vendors/qiniu/models.json
new file mode 100644
index 000000000..c1f5b4bd8
--- /dev/null
+++ b/internal/models/vendors/qiniu/models.json
@@ -0,0 +1,16 @@
+{
+ "vendor": "qiniu",
+ "source": "https://www.qiniu.com/ai/models",
+ "models": [
+ {"id": "qwen3.5-397b-a17b", "name": "Qwen3.5 397B-A17B", "reasoning": true, "input": ["text", "image"], "context_window": 256000, "max_output_tokens": 64000},
+ {"id": "z-ai/glm-5", "name": "GLM-5", "reasoning": true, "input": ["text"], "context_window": 200000, "max_output_tokens": 128000},
+ {"id": "z-ai/glm-4.7", "name": "GLM-4.7", "reasoning": true, "input": ["text"], "context_window": 200000, "max_output_tokens": 200000, "source": "https://api.qnaigc.com/v1/market/models"},
+ {"id": "minimax/minimax-m2.5", "name": "MiniMax M2.5", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 128000},
+ {"id": "doubao-seed-2.0-pro", "name": "Doubao Seed 2.0 Pro", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 128000},
+ {"id": "moonshotai/kimi-k2.5", "name": "Kimi K2.5", "reasoning": false, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 256000},
+ {"id": "xiaomi/mimo-v2-flash", "name": "MiMo V2 Flash", "reasoning": true, "input": ["text"], "context_window": 256000, "max_output_tokens": 256000, "cost": {"input": 0.1, "output": 0.3, "cache_read": 0.01}},
+ {"id": "deepseek/deepseek-v3.2-251201", "name": "DeepSeek V3.2 (251201)", "reasoning": true, "input": ["text"], "context_window": 128000, "max_output_tokens": 32000, "source": "https://apidocs.qnaigc.com/397639742e0"},
+ {"id": "deepseek-r1", "name": "DeepSeek R1", "reasoning": true, "input": ["text"], "context_window": 128000, "max_output_tokens": 32000, "thinking_levels": {"off": null}, "source": "https://api.qnaigc.com/v1/market/models"},
+ {"id": "deepseek-v3", "name": "DeepSeek V3", "reasoning": false, "input": ["text"], "context_window": 128000, "max_output_tokens": 16000}
+ ]
+}
diff --git a/internal/models/vendors/qiniu/vendor.go b/internal/models/vendors/qiniu/vendor.go
new file mode 100644
index 000000000..98fd5dbee
--- /dev/null
+++ b/internal/models/vendors/qiniu/vendor.go
@@ -0,0 +1,103 @@
+// Package qiniu registers Qiniu Cloud's AI token gateway.
+//
+// Facts (parameter reference
+// https://developer.qiniu.com/aitokenapi/13390/chat-completions, endpoint
+// https://developer.qiniu.com/aitokenapi/13379/real-time-ai-interface-api,
+// FAQ https://developer.qiniu.com/aitokenapi/13462/aitoken-use-faq):
+// - the base URL is the host plus /v1; the FAQ spells it out as
+// "domain + /v1" and the gateway serves POST /v1/chat/completions,
+// POST /v1/messages (an Anthropic-compatible surface) and
+// GET /v1/models. This package speaks Chat Completions, the format the
+// parameter reference documents;
+// - auth is `Authorization: Bearer <API Key>`; there are no other
+// credentials or vendor fields;
+// - output cap is `max_tokens`; `max_completion_tokens` is not in the
+// reference;
+// - thinking is switched with `thinking: {"type": ...}`. The OpenAPI
+// spec behind https://apidocs.qnaigc.com documents the types
+// enabled | disabled | auto; this package only ever sends
+// enabled / disabled, so "auto" is left to callers who set it
+// themselves;
+// - `reasoning_effort` is graded, and the same spec lists its values as
+// minimal | low | medium | high (plus `none`, which the protocol
+// expresses as thinking.type=disabled). minimal..high therefore pass
+// through under their own names and xhigh / max clamp down to high,
+// which is the protocol default, so no vendor level map is needed;
+// - sampling is the full OpenAI set: temperature 0..2, top_p 0..1,
+// top_k, presence_penalty / frequency_penalty -2..2,
+// repetition_penalty 0..2;
+// - tools, tool_choice (none / auto / required / a named tool) and
+// response_format are all accepted, so the protocol defaults hold;
+// - the gateway serves no embedding or rerank models: the FAQ states it
+// "currently has no text vector or embedding models", which is why
+// ModelTypes lists chat only.
+//
+// unverified: `parallel_tool_calls` and `stream_options.include_usage` do
+// not appear in the reference; the protocol defaults are kept.
+//
+// unverified: no response schema is published, so nothing states whether
+// usage carries cache counters. prompt_cache_accounting stays off, and
+// neither prompt_cache_key nor Anthropic-style cache_control is
+// documented.
+//
+// unverified: nothing documents a mandatory thinking switch or a
+// non-stream restriction, so thinking_always_send and
+// thinking_disable_on_non_stream stay off.
+//
+// unverified: the model catalogue is served dynamically from the model
+// marketplace rather than published as a list, and /v1/market/models
+// returned only a subset of the ids below. No retirement notice was found
+// for any of them, so every entry is kept; models.dev lists no prices for
+// this gateway, so cost is omitted.
+package qiniu
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "qiniu"
+
+// BaseURL is the OpenAI-compatible chat endpoint.
+const BaseURL = "https://api.qnaigc.com/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Qiniu Cloud",
+ Names: map[string]string{"zh-CN": "七牛云 Qiniu"},
+ Description: "deepseek/deepseek-v3.2-251201, z-ai/glm-4.7, qwen3.5-397b-a17b, etc.",
+ Website: "https://portal.qiniu.com/ai-inference",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 21,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ // api.modelink.ai is the gateway's documented international host.
+ URLPatterns: []string{"qiniuapi.com", "qiniu", "qnaigc.com", "modelink.ai"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/requesty/icon.svg b/internal/models/vendors/requesty/icon.svg
new file mode 100644
index 000000000..432f374b5
--- /dev/null
+++ b/internal/models/vendors/requesty/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><rect width="24" height="24" rx="5" fill="#111827"/><text x="12" y="16" font-family="sans-serif" font-weight="700" font-size="10" fill="#FFFFFF" text-anchor="middle">RQ</text></svg>
diff --git a/internal/models/vendors/requesty/models.json b/internal/models/vendors/requesty/models.json
new file mode 100644
index 000000000..360c6a99b
--- /dev/null
+++ b/internal/models/vendors/requesty/models.json
@@ -0,0 +1,17 @@
+{
+ "vendor": "requesty",
+ "source": "https://docs.requesty.ai/frameworks/openai",
+ "models": [
+ {"id": "openai/gpt-6-astra", "name": "GPT-6 Astra", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "compat": {"supports_temperature": false}, "thinking_levels": {"off": null, "minimal": "min", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "openai/gpt-5.5", "name": "GPT-5.5", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "min", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "openai/gpt-5.4", "name": "GPT-5.4", "reasoning": true, "input": ["text", "image"], "context_window": 1050000, "max_output_tokens": 128000, "compat": {"supports_temperature": false}, "thinking_levels": {"off": "none", "minimal": "min", "xhigh": "xhigh", "max": "xhigh"}},
+ {"id": "anthropic/claude-opus-5", "name": "Claude Opus 5", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "anthropic/claude-sonnet-5", "name": "Claude Sonnet 5", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 128000, "thinking_levels": {"off": null, "minimal": "low", "xhigh": "xhigh", "max": "max"}},
+ {"id": "vertex/gemini-3.8-flash", "name": "Gemini 3.8 Flash (Vertex)", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "thinking_levels": {"off": null, "minimal": "min", "xhigh": "high", "max": "high"}},
+ {"id": "google/gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro Preview", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "thinking_levels": {"off": null, "minimal": "min", "xhigh": "high", "max": "high"}},
+ {"id": "google/gemini-3.6-flash", "name": "Gemini 3.6 Flash", "reasoning": true, "input": ["text", "image", "audio", "video"], "context_window": 1048576, "max_output_tokens": 65536, "thinking_levels": {"off": null, "minimal": "min", "xhigh": "high", "max": "high"}},
+ {"id": "deepseek/deepseek-v4-pro-0813", "name": "DeepSeek V4 Pro", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072},
+ {"id": "zai/glm-5.2", "name": "GLM-5.2", "reasoning": true, "input": ["text"], "context_window": 1048576, "max_output_tokens": 131072},
+ {"id": "moonshot/kimi-k3", "name": "Kimi K3", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1048576, "max_output_tokens": 262144}
+ ]
+}
diff --git a/internal/models/vendors/requesty/vendor.go b/internal/models/vendors/requesty/vendor.go
new file mode 100644
index 000000000..3076f4e9e
--- /dev/null
+++ b/internal/models/vendors/requesty/vendor.go
@@ -0,0 +1,98 @@
+// Package requesty registers the Requesty router.
+//
+// Facts (https://docs.requesty.ai/features/reasoning and
+// https://docs.requesty.ai/frameworks/openai):
+// - output cap is `max_tokens`; `max_completion_tokens` appears nowhere in
+// the documentation;
+// - thinking is a flat `reasoning_effort` string (there is no
+// OpenRouter-style reasoning object). Accepted values are
+// none | min | low | medium | high | xhigh | max, plus a numeric budget
+// passed as a string. Note the weakest rung is spelled `min`, not
+// `minimal`, which is what the vendor level map corrects;
+// - `max` is not the top rung everywhere: "`xhigh` is OpenAI's highest
+// reasoning effort. It is not the same as `max`. `max` is normalized to
+// `high` for OpenAI models, whereas `xhigh` is a strictly higher tier."
+// The OpenAI-routed entries therefore send `xhigh` for both xhigh and
+// max; Anthropic-routed ones keep `max` as their top rung;
+// - model ids are always `provider/model`: "To specify a model, you must
+// include the provider prefix". Every id in the live catalog carries
+// one, and the bare `model_canonical_name` a record reports is metadata,
+// not a usable value. The catalog entries below are prefixed
+// accordingly;
+// - embeddings and VLM share the https://router.requesty.ai/v1 base; the
+// Anthropic-style surface is a separate path
+// (/anthropic/v1/messages) and xhigh is unreachable through it.
+//
+// Unverified:
+// - Requesty warns "Do not hardcode model versions — model availability
+// changes", and several routes only exist in dated form
+// (deepseek/deepseek-v4-pro-0813). The undated deepseek-v4-flash has no
+// first-party route at all, so it is left out rather than guessed;
+// - gemini-3.8-flash is routed under `vertex/` only; there is no
+// `google/gemini-3.8-flash`, and the newest `google/` Gemini Flash is
+// 3.6;
+// - GET /v1/models is chat-only; embedding models live at
+// /v1/models/embedding, which the docs do not mention.
+package requesty
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "requesty"
+
+// BaseURL is the OpenAI-compatible router endpoint.
+const BaseURL = "https://router.requesty.ai/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Requesty",
+ Names: map[string]string{"zh-CN": "Requesty"},
+ Description: "openai/gpt-5.5, anthropic/claude-opus-5, google/gemini-3.1-pro-preview, zai/glm-5.2, etc.",
+ Website: "https://requesty.ai",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 42,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"router.requesty.ai", "requesty.ai"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatOpenAI),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ },
+ },
+ // Requesty spells the weakest rung "min" and accepts the whole
+ // ladder; "off" is the literal "none".
+ ThinkingLevels: api.ThinkingLevelMap{
+ api.ReasoningOff: api.StringPtr("none"),
+ api.ReasoningMinimal: api.StringPtr("min"),
+ api.ReasoningXHigh: api.StringPtr("xhigh"),
+ api.ReasoningMax: api.StringPtr("max"),
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/siliconflow/icon.svg b/internal/models/vendors/siliconflow/icon.svg
new file mode 100644
index 000000000..6b5f6d805
--- /dev/null
+++ b/internal/models/vendors/siliconflow/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>SiliconCloud</title><path clip-rule="evenodd" d="M22.956 6.521H12.522c-.577 0-1.044.468-1.044 1.044v3.13c0 .577-.466 1.044-1.043 1.044H1.044c-.577 0-1.044.467-1.044 1.044v4.174C0 17.533.467 18 1.044 18h10.434c.577 0 1.044-.467 1.044-1.043v-3.13c0-.578.466-1.044 1.043-1.044h9.391c.577 0 1.044-.467 1.044-1.044V7.565c0-.576-.467-1.044-1.044-1.044z" fill="#6E29F6" fill-rule="evenodd"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/siliconflow/models.json b/internal/models/vendors/siliconflow/models.json
new file mode 100644
index 000000000..2d3f25a3e
--- /dev/null
+++ b/internal/models/vendors/siliconflow/models.json
@@ -0,0 +1,29 @@
+{
+ "vendor": "siliconflow",
+ "source": "https://docs.siliconflow.cn/cn/api-reference/chat-completions/chat-completions",
+ "models": [
+ {"name": "DeepSeek V4 family (reasoning_effort high | max)", "match": "deepseek-ai/DeepSeek-V4*", "reasoning": true, "input": ["text"], "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}},
+ {"name": "DeepSeek V4 Pro-tier family (reasoning_effort high | max)", "match": "Pro/deepseek-ai/DeepSeek-V4*", "reasoning": true, "input": ["text"], "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}},
+ {"id": "deepseek-ai/DeepSeek-V4-Pro", "name": "DeepSeek V4 Pro", "reasoning": true, "input": ["text"], "context_window": 1049000, "max_output_tokens": 393000, "cost": {"input": 1.74, "output": 3.48, "cache_read": 0.145}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}},
+ {"id": "deepseek-ai/DeepSeek-V4-Flash", "name": "DeepSeek V4 Flash", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 384000, "cost": {"input": 0.14, "output": 0.28, "cache_read": 0.003}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}},
+ {"id": "zai-org/GLM-5.2", "name": "GLM-5.2", "aliases": ["Pro/zai-org/GLM-5.2"], "reasoning": true, "input": ["text"], "context_window": 1049000, "max_output_tokens": 262000, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}, "thinking_levels": {"minimal": "high", "low": "high", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}},
+ {"id": "Pro/zai-org/GLM-5.1", "name": "GLM-5.1 (Pro)", "reasoning": true, "input": ["text"], "context_window": 205000, "max_output_tokens": 205000, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Pro/zai-org/GLM-5", "name": "GLM-5 (Pro)", "reasoning": true, "input": ["text"], "context_window": 205000, "max_output_tokens": 205000, "cost": {"input": 1, "output": 3.2}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Pro/moonshotai/Kimi-K2.6", "name": "Kimi K2.6 (Pro)", "reasoning": true, "input": ["text", "image"], "context_window": 262000, "max_output_tokens": 262000, "cost": {"input": 0.95, "output": 4, "cache_read": 0.16}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Pro/moonshotai/Kimi-K2.5", "name": "Kimi K2.5 (Pro)", "reasoning": true, "input": ["text", "image"], "context_window": 262000, "max_output_tokens": 262000, "cost": {"input": 0.45, "output": 2.25, "cache_read": 0.07}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Qwen/Qwen3.5-397B-A17B", "name": "Qwen3.5 397B-A17B", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 0.29, "output": 1.74}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Qwen/Qwen3.5-122B-A10B", "name": "Qwen3.5 122B-A10B", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 0.29, "output": 2.32}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Qwen/Qwen3.5-35B-A3B", "name": "Qwen3.5 35B-A3B", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 0.23, "output": 1.86}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Qwen/Qwen3.6-35B-A3B", "name": "Qwen3.6 35B-A3B", "reasoning": false, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 65536, "cost": {"input": 0.23, "output": 1.86}},
+ {"id": "deepseek-ai/DeepSeek-V3.2", "name": "DeepSeek V3.2", "reasoning": true, "input": ["text"], "context_window": 164000, "max_output_tokens": 164000, "cost": {"input": 0.27, "output": 0.42}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "Pro/MiniMaxAI/MiniMax-M2.5", "name": "MiniMax M2.5 (Pro)", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131000, "cost": {"input": 0.3, "output": 1.22}, "compat": {"supports_reasoning_effort": false}, "source": "https://platform.minimax.io/docs/api-reference/text-openai-api"},
+ {"id": "Qwen/Qwen3-VL-32B-Instruct", "name": "Qwen3 VL 32B Instruct", "reasoning": false, "input": ["text", "image"], "context_window": 262000, "max_output_tokens": 262000, "cost": {"input": 0.2, "output": 0.6}},
+ {"id": "BAAI/bge-m3", "name": "BGE-M3", "type": "Embedding", "dimension": 1024, "source": "https://docs.siliconflow.cn/cn/api-reference/embeddings/create-embeddings"},
+ {"id": "Qwen/Qwen3-Embedding-8B", "name": "Qwen3 Embedding 8B", "type": "Embedding", "dimension": 4096, "source": "https://docs.siliconflow.cn/cn/api-reference/embeddings/create-embeddings"},
+ {"id": "Qwen/Qwen3-Embedding-4B", "name": "Qwen3 Embedding 4B", "type": "Embedding", "dimension": 2560, "source": "https://docs.siliconflow.cn/cn/api-reference/embeddings/create-embeddings"},
+ {"id": "Qwen/Qwen3-Embedding-0.6B", "name": "Qwen3 Embedding 0.6B", "type": "Embedding", "dimension": 1024, "source": "https://docs.siliconflow.cn/cn/api-reference/embeddings/create-embeddings"},
+ {"id": "BAAI/bge-reranker-v2-m3", "name": "BGE Reranker v2 M3", "type": "Rerank", "source": "https://docs.siliconflow.cn/cn/api-reference/rerank/create-rerank"},
+ {"id": "Qwen/Qwen3-Reranker-8B", "name": "Qwen3 Reranker 8B", "type": "Rerank", "source": "https://docs.siliconflow.cn/cn/api-reference/rerank/create-rerank"},
+ {"id": "FunAudioLLM/SenseVoiceSmall", "name": "SenseVoice Small", "type": "ASR", "source": "https://docs.siliconflow.cn/cn/api-reference/audio/create-audio-transcriptions"}
+ ]
+}
diff --git a/internal/models/vendors/siliconflow/vendor.go b/internal/models/vendors/siliconflow/vendor.go
new file mode 100644
index 000000000..d9c5c38c6
--- /dev/null
+++ b/internal/models/vendors/siliconflow/vendor.go
@@ -0,0 +1,90 @@
+// Package siliconflow registers SiliconFlow (SiliconCloud), an
+// OpenAI-compatible gateway to open-weight models.
+//
+// Facts (https://docs.siliconflow.cn/cn/api-reference/chat-completions/chat-completions):
+// - output cap is `max_tokens`; `max_completion_tokens` is not documented;
+// - `enable_thinking` "在推理模式与非推理模式之间切换。该字段适用于大多数推理
+// 模型", sent as a top-level boolean, together with `thinking_budget`
+// (128 <= value <= 32768). Both work in streaming and non-streaming
+// mode and neither is mandatory, so the switch is only sent when the
+// caller asks for one;
+// - `reasoning_effort` accepts "high" | "max" and "该字段适用于
+// Pro/deepseek-ai/DeepSeek-V4、deepseek-ai/DeepSeek-V4-Flash 以及
+// Pro/zai-org/GLM-5.2", so every other reasoning entry disables it;
+// - usage reports `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`,
+// hence prompt_cache_accounting;
+// - response_format accepts text (default), json_object and json_schema;
+// - temperature is [0, 2] (default 0.7) and top_p up to 1, unrestricted;
+// - one base URL serves chat, embedding, rerank, VLM and ASR, and the only
+// credential is a bearer API key, so there are no ExtraFields.
+//
+// unverified: the reference documents `tools` but not `tool_choice`,
+// `parallel_tool_calls` or `stream_options`, so the protocol defaults for
+// those three stand untested;
+// unverified: `prompt_cache_key` and Anthropic-style cache_control are not
+// documented, so neither is sent;
+// unverified: the embedding / rerank / ASR entries (ids, dimensions) come
+// from the SiliconCloud model pages, and the per-model context windows,
+// output caps and prices in models.json are not restated in the API
+// reference.
+package siliconflow
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "siliconflow"
+
+// BaseURL serves every model type.
+const BaseURL = "https://api.siliconflow.cn/v1"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "SiliconFlow",
+ Names: map[string]string{"zh-CN": "硅基流动 SiliconFlow"},
+ Description: "deepseek-ai/DeepSeek-V4-Pro, zai-org/GLM-5.2, Qwen/Qwen3.5-397B-A17B, BAAI/bge-m3, etc.",
+ Website: "https://cloud.siliconflow.cn",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 14,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"siliconflow.cn"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ types.ModelTypeASR: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ types.ModelTypeASR,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatEnableThinking),
+ ThinkingBudgetField: catalog.Ptr("thinking_budget"),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/vendors_test.go b/internal/models/vendors/vendors_test.go
new file mode 100644
index 000000000..b895d571a
--- /dev/null
+++ b/internal/models/vendors/vendors_test.go
@@ -0,0 +1,401 @@
+package vendors
+
+import (
+ "bytes"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// expectedIDs is every built-in vendor this package links.
+var expectedIDs = []string{
+ "generic", "weknoracloud",
+ "aliyun", "zhipu", "volcengine", "hunyuan", "siliconflow", "deepseek",
+ "minimax", "moonshot", "mimo", "modelscope", "qianfan", "qiniu", "longcat", "lkeap",
+ "openai", "azure_openai", "anthropic", "gemini",
+ "openrouter", "litellm", "requesty",
+ "jina", "nvidia", "novita", "gpustack",
+}
+
+func TestAllVendorsRegistered(t *testing.T) {
+ if len(expectedIDs) != 27 {
+ t.Fatalf("expected 27 vendor ids in the spec, got %d", len(expectedIDs))
+ }
+ for _, id := range expectedIDs {
+ v, ok := catalog.Get(id)
+ if !ok {
+ t.Errorf("vendor %q is not registered", id)
+ continue
+ }
+ if v.ID != strings.ToLower(v.ID) {
+ t.Errorf("vendor %q: id is not lowercase", id)
+ }
+ if v.Name == "" {
+ t.Errorf("vendor %q: empty Name", id)
+ }
+ if len(v.Icon) == 0 || !bytes.HasPrefix(bytes.TrimSpace(v.Icon), []byte("<svg")) {
+ t.Errorf("vendor %q: icon is empty or not an <svg> document", id)
+ }
+ if len(v.Icon) > 6*1024 {
+ t.Errorf("vendor %q: icon is %d bytes, over the 6 KB budget", id, len(v.Icon))
+ }
+ if v.RequiresAuth && v.Auth == "" {
+ t.Errorf("vendor %q: RequiresAuth without Auth style", id)
+ }
+ if v.Auth == catalog.AuthSigned && v.Signer == nil {
+ t.Errorf("vendor %q: AuthSigned without Signer", id)
+ }
+ if !v.API.Known() {
+ t.Errorf("vendor %q: unknown default API %q", id, v.API)
+ }
+ if len(v.ModelTypes) == 0 {
+ t.Errorf("vendor %q: no ModelTypes", id)
+ }
+ }
+ for _, v := range catalog.List() {
+ found := false
+ for _, id := range expectedIDs {
+ if id == v.ID {
+ found = true
+ break
+ }
+ }
+ if !found {
+ t.Errorf("unexpected vendor %q registered", v.ID)
+ }
+ }
+}
+
+func TestEveryCatalogEntryResolves(t *testing.T) {
+ for _, id := range expectedIDs {
+ v, ok := catalog.Get(id)
+ if !ok {
+ t.Fatalf("vendor %q missing", id)
+ }
+ for _, m := range v.Models {
+ if m.ID == "" && m.Match == "" {
+ t.Errorf("%s: model entry %q has neither id nor match", id, m.Name)
+ continue
+ }
+ name := m.ID
+ if name == "" {
+ // Exercise pattern entries with a name that matches the glob.
+ name = strings.ReplaceAll(m.Match, "*", "x")
+ }
+ modelType := m.Type
+ if modelType == "" {
+ modelType = types.ModelTypeKnowledgeQA
+ }
+ r, err := catalog.Resolve(catalog.Ref{Provider: v.ID, Model: name, ModelType: modelType})
+ if err != nil {
+ t.Errorf("%s/%s: resolve: %v", id, name, err)
+ continue
+ }
+ if !r.Cataloged {
+ t.Errorf("%s/%s: did not match its own catalog entry", id, name)
+ }
+ if modelType == types.ModelTypeKnowledgeQA && !r.API.Known() {
+ t.Errorf("%s/%s: resolved to unknown API %q", id, name, r.API)
+ }
+ if modelType == types.ModelTypeEmbedding && m.ID != "" && m.Dimension <= 0 {
+ t.Logf("%s/%s: embedding entry without dimension", id, name)
+ }
+ }
+ }
+}
+
+func TestDetectByURLRoundTrip(t *testing.T) {
+ for _, id := range expectedIDs {
+ v, _ := catalog.Get(id)
+ if len(v.URLPatterns) == 0 {
+ continue
+ }
+ u := v.GetDefaultURL(types.ModelTypeKnowledgeQA)
+ if !strings.HasPrefix(u, "https://") || strings.Contains(u, "{") {
+ continue // placeholder or http-only self-hosted default
+ }
+ if got := catalog.DetectByURL(u); got != v.ID {
+ t.Errorf("DetectByURL(%q) = %q, want %q", u, got, v.ID)
+ }
+ }
+ if got := catalog.DetectByURL("http://your_litellm_proxy/v1"); got != "litellm" {
+ t.Errorf("litellm placeholder detected as %q", got)
+ }
+ // GPUStack 2.x serves the OpenAI-compatible surface at /v1; the 0.x
+ // /v1-openai path must keep resolving for rows saved before the move.
+ if got := catalog.DetectByURL("http://your_gpustack_server_url/v1-openai"); got != "gpustack" {
+ t.Errorf("gpustack placeholder detected as %q", got)
+ }
+ if got := catalog.DetectByURL("https://api.moonshot.cn/v1"); got != "moonshot" {
+ t.Errorf("moonshot.cn detected as %q", got)
+ }
+}
+
+// TestOpenAIProtocolSelection pins the first-party / relay split: Responses on
+// api.openai.com, Chat Completions everywhere else, extra_config.api wins.
+func TestOpenAIProtocolSelection(t *testing.T) {
+ cases := []struct {
+ baseURL string
+ extra map[string]string
+ want api.API
+ }{
+ {"", nil, api.APIOpenAIResponses},
+ {"https://api.openai.com/v1", nil, api.APIOpenAIResponses},
+ {"https://API.openai.com/v1/", nil, api.APIOpenAIResponses},
+ {"https://my-relay.example.com/v1", nil, api.APIOpenAICompletions},
+ {"https://api.openai.com/v1", map[string]string{"api": "openai-completions"}, api.APIOpenAICompletions},
+ }
+ for _, tc := range cases {
+ r, err := catalog.Resolve(catalog.Ref{
+ Provider: "openai", Model: "gpt-5.5", BaseURL: tc.baseURL, Extra: tc.extra,
+ })
+ if err != nil {
+ t.Fatalf("resolve openai %q: %v", tc.baseURL, err)
+ }
+ if r.API != tc.want {
+ t.Errorf("openai base %q extra %v: api = %q, want %q", tc.baseURL, tc.extra, r.API, tc.want)
+ }
+ }
+}
+
+func resolve(t *testing.T, provider, model string) *catalog.Resolved {
+ t.Helper()
+ r, err := catalog.Resolve(catalog.Ref{Provider: provider, Model: model})
+ if err != nil {
+ t.Fatalf("resolve %s/%s: %v", provider, model, err)
+ }
+ return r
+}
+
+func TestFamilyExpectations(t *testing.T) {
+ if r := resolve(t, "openai", "gpt-5.2"); r.OpenAICompletions.SupportsTemperature {
+ t.Error("openai/gpt-5.2 should not support temperature")
+ }
+ if r := resolve(t, "openai", "gpt-5-turbo-future"); r.OpenAICompletions.SupportsTemperature || !r.Spec.Reasoning {
+ t.Error("openai gpt-5* family should be reasoning without temperature")
+ }
+ if r := resolve(t, "openai", "o4-mini"); r.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Error("openai/o4-mini should not allow thinking off")
+ }
+ if r := resolve(t, "azure_openai", "gpt-5.4-prod"); r.OpenAICompletions.SupportsTemperature {
+ t.Error("azure gpt-5* deployment should not support temperature")
+ }
+ // A deployment named exactly gpt-5 / gpt-5-mini / gpt-5-nano must agree
+ // with the openai vendor: the original GPT-5 trio rejects
+ // reasoning_effort "none", so the picker must not offer thinking off.
+ // Only GPT-5.1 and later, which the gpt-5* pattern covers, accept it.
+ for _, deployment := range []string{"gpt-5", "gpt-5-mini", "gpt-5-nano"} {
+ azureSpec := resolve(t, "azure_openai", deployment)
+ if azureSpec.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Errorf("azure/%s should not allow thinking off", deployment)
+ }
+ openaiSpec := resolve(t, "openai", deployment)
+ if openaiSpec.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Errorf("openai/%s should not allow thinking off", deployment)
+ }
+ }
+ if r := resolve(t, "azure_openai", "gpt-5.1-prod"); !r.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Error("azure gpt-5* family (GPT-5.1 and later) should allow thinking off")
+ }
+ if r := resolve(t, "aliyun", "qwen3-max"); !r.OpenAICompletions.ThinkingAlwaysSend {
+ t.Error("aliyun/qwen3-max should always send the thinking switch")
+ }
+ if r := resolve(t, "aliyun", "qwen-plus-2026-01-01"); !r.OpenAICompletions.ThinkingAlwaysSend ||
+ !r.OpenAICompletions.ThinkingDisableOnNonStream {
+ t.Error("aliyun qwen-plus* family should carry the hybrid thinking flags")
+ }
+ if r := resolve(t, "aliyun", "qwq-plus"); r.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Error("aliyun/qwq-plus should not allow thinking off")
+ }
+ if r := resolve(t, "moonshot", "moonshot-v1-8k"); r.OpenAICompletions.FixedTemperature == nil ||
+ *r.OpenAICompletions.FixedTemperature != 1 {
+ t.Error("moonshot/moonshot-v1-8k should pin temperature to 1")
+ }
+ if r := resolve(t, "moonshot", "kimi-k2.6"); r.OpenAICompletions.SupportsTemperature {
+ t.Error("moonshot/kimi-k2.6 should not support temperature")
+ }
+ if r := resolve(t, "lkeap", "deepseek-r1"); r.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Error("lkeap/deepseek-r1 should not allow thinking off")
+ }
+ if r := resolve(t, "lkeap", "my-deepseek-v3-route"); !r.Spec.Reasoning ||
+ !r.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Error("lkeap *deepseek-v3* family should be switchable reasoning")
+ }
+ if r := resolve(t, "zhipu", "glm-5.2"); r.ThinkingLevels.Value(api.ReasoningMedium) != "high" {
+ t.Errorf("zhipu/glm-5.2 medium should map to high, got %q", r.ThinkingLevels.Value(api.ReasoningMedium))
+ }
+ if r := resolve(t, "zhipu", "glm-4.7"); r.ThinkingLevels.Value(api.ReasoningOff) != "none" {
+ t.Error("zhipu vendor map should spell off as none")
+ }
+ if r := resolve(t, "gemini", "gemini-2.5-flash"); r.API != api.APIGoogleGenerativeAI {
+ t.Errorf("gemini/gemini-2.5-flash API = %q", r.API)
+ }
+ if r := resolve(t, "gemini", "gemini-3.8-flash"); r.GoogleGenerativeAI.ThinkingMode != catalog.GoogleThinkingLevel {
+ t.Errorf("gemini/gemini-3.8-flash thinking mode = %q", r.GoogleGenerativeAI.ThinkingMode)
+ }
+ if r := resolve(t, "anthropic", "claude-opus-5"); r.AnthropicMessages.ThinkingMode !=
+ catalog.AnthropicThinkingAdaptive || !r.AnthropicMessages.SupportsEffort {
+ t.Error("anthropic/claude-opus-5 should use adaptive thinking with effort")
+ }
+ if r := resolve(t, "anthropic", "claude-sonnet-4-5"); r.AnthropicMessages.ThinkingMode !=
+ catalog.AnthropicThinkingBudget {
+ t.Error("anthropic/claude-sonnet-4-5 should keep budget thinking")
+ }
+ if r := resolve(t, "anthropic", "claude-sonnet-4-5-20250929"); !r.Cataloged {
+ t.Error("anthropic dated alias should resolve to the catalog entry")
+ }
+ if r := resolve(t, "openrouter", "anthropic/claude-haiku-4.5"); r.OpenAICompletions.CacheControlFormat !=
+ "anthropic" {
+ t.Error("openrouter anthropic/* family should use anthropic cache_control")
+ }
+ if r := resolve(t, "siliconflow", "deepseek-ai/DeepSeek-V4-Pro"); !r.OpenAICompletions.SupportsReasoningEffort ||
+ r.ThinkingLevels.Value(api.ReasoningMax) != "max" {
+ t.Error("siliconflow DeepSeek-V4-Pro should grade effort high/max")
+ }
+ if r := resolve(t, "siliconflow", "Pro/zai-org/GLM-5"); r.OpenAICompletions.SupportsReasoningEffort {
+ t.Error("siliconflow GLM-5 should not send reasoning_effort")
+ }
+ if r := resolve(t, "minimax", "MiniMax-M3"); r.OpenAICompletions.ThinkingEnabledValue != "adaptive" {
+ t.Error("minimax should enable thinking with type adaptive")
+ }
+ if r := resolve(t, "volcengine", "doubao-seed-1-6-251015"); r.OpenAICompletions.MaxTokensField !=
+ "max_completion_tokens" {
+ t.Error("volcengine must keep max_completion_tokens")
+ }
+ if r := resolve(t, "deepseek", "deepseek-reasoner"); r.ThinkingLevels.Supports(api.ReasoningOff) {
+ t.Error("deepseek/deepseek-reasoner should not allow thinking off")
+ }
+}
+
+func TestHooks(t *testing.T) {
+ azure, _ := catalog.Get("azure_openai")
+ u, q := azure.Endpoint(catalog.EndpointRequest{
+ BaseURL: "https://my-res.openai.azure.com/",
+ Model: "gpt-4o deploy",
+ ModelType: types.ModelTypeKnowledgeQA,
+ Extra: map[string]string{catalog.ExtraAPIVersion: "2025-01-01-preview"},
+ })
+ if u != "https://my-res.openai.azure.com/openai/deployments/gpt-4o%20deploy/chat/completions" {
+ t.Errorf("azure endpoint = %q", u)
+ }
+ if q["api-version"] != "2025-01-01-preview" {
+ t.Errorf("azure api-version = %q", q["api-version"])
+ }
+ // Without an explicit api_version the hook emits the v1 GA data plane,
+ // which carries the deployment name in the body and takes no
+ // api-version at all.
+ u, q = azure.Endpoint(catalog.EndpointRequest{BaseURL: "https://x.openai.azure.com", Model: "d"})
+ if u != "https://x.openai.azure.com/openai/v1/chat/completions" {
+ t.Errorf("azure v1 endpoint = %q", u)
+ }
+ if len(q) != 0 {
+ t.Errorf("azure v1 query = %v, want none", q)
+ }
+ if azure.Auth != catalog.AuthAPIKeyHeader {
+ t.Errorf("azure auth = %q", azure.Auth)
+ }
+ // Embedding obeys the same rule as chat for the same stored row, so one
+ // Azure resource never ends up serving chat on v1 and embedding on the
+ // dated deployments path. internal/models/embedding calls this hook.
+ u, q = azure.Endpoint(catalog.EndpointRequest{
+ BaseURL: "https://x.openai.azure.com", Model: "embed-deploy",
+ ModelType: types.ModelTypeEmbedding,
+ })
+ if u != "https://x.openai.azure.com/openai/v1/embeddings" {
+ t.Errorf("azure v1 embedding endpoint = %q", u)
+ }
+ if len(q) != 0 {
+ t.Errorf("azure v1 embedding query = %v, want none", q)
+ }
+ u, q = azure.Endpoint(catalog.EndpointRequest{
+ BaseURL: "https://x.openai.azure.com", Model: "embed-deploy",
+ ModelType: types.ModelTypeEmbedding,
+ Extra: map[string]string{catalog.ExtraAPIVersion: "2024-10-21"},
+ })
+ if u != "https://x.openai.azure.com/openai/deployments/embed-deploy/embeddings" {
+ t.Errorf("azure legacy embedding endpoint = %q", u)
+ }
+ if q["api-version"] != "2024-10-21" {
+ t.Errorf("azure legacy embedding api-version = %q", q["api-version"])
+ }
+
+ wk, _ := catalog.Get("weknoracloud")
+ u, _ = wk.Endpoint(catalog.EndpointRequest{
+ BaseURL: "https://weknora.weixin.qq.com/", ModelType: types.ModelTypeKnowledgeQA,
+ })
+ if u != "https://weknora.weixin.qq.com/api/v1/chat/completions" {
+ t.Errorf("weknoracloud endpoint = %q", u)
+ }
+ if wk.Auth != catalog.AuthSigned || wk.Signer == nil {
+ t.Error("weknoracloud should use a signer")
+ }
+ if err := wk.ValidateConfig(&catalog.Config{}); err != nil {
+ t.Errorf("weknoracloud validate should pass without key: %v", err)
+ }
+
+ generic, _ := catalog.Get("generic")
+ if err := generic.ValidateConfig(&catalog.Config{ModelName: "m"}); err == nil {
+ t.Error("generic validate should require a base URL")
+ }
+ if err := generic.ValidateConfig(&catalog.Config{BaseURL: "http://x/v1", ModelName: "m"}); err != nil {
+ t.Errorf("generic validate: %v", err)
+ }
+ gpustack, _ := catalog.Get("gpustack")
+ if err := gpustack.ValidateConfig(&catalog.Config{APIKey: "k", ModelName: "m"}); err == nil {
+ t.Error("gpustack validate should require a base URL")
+ }
+
+ for _, id := range []string{"volcengine", "lkeap"} {
+ v, _ := catalog.Get(id)
+ found := false
+ for _, f := range v.ExtraFields {
+ if f.Key == "secret_key" {
+ found = true
+ if !f.Secret || len(f.ModelTypes) != 1 || f.ModelTypes[0] != types.ModelTypeRerank {
+ t.Errorf("%s secret_key field should be secret and rerank-only", id)
+ }
+ }
+ }
+ if !found {
+ t.Errorf("%s should expose a secret_key extra field", id)
+ }
+ }
+}
+
+// TestSignedRerankCredentialLabels pins that the two signed rerank vendors
+// name their first credential after the identity it actually is. The editor
+// renders this instead of a hardcoded vendor table, so losing it silently
+// sends operators back to pasting an sk- key into a signature field.
+func TestSignedRerankCredentialLabels(t *testing.T) {
+ for _, tc := range []struct{ vendor, wantLabel string }{
+ {"lkeap", "SecretId"},
+ {"volcengine", "Access Key ID"},
+ } {
+ t.Run(tc.vendor, func(t *testing.T) {
+ v, ok := catalog.Get(tc.vendor)
+ if !ok {
+ t.Fatalf("vendor %s is not registered", tc.vendor)
+ }
+ label := v.CredentialLabelFor(types.ModelTypeRerank)
+ if label == nil {
+ t.Fatalf("rerank should override the credential label")
+ }
+ if label.Label != tc.wantLabel {
+ t.Errorf("rerank credential label = %q, want %q", label.Label, tc.wantLabel)
+ }
+ if label.LocalizedLabel("zh-CN") == label.Label {
+ t.Errorf("zh-CN label should differ from the default")
+ }
+ if label.Hint == "" {
+ t.Errorf("the hint is what stops an sk- key being pasted here")
+ }
+ // Chat and embedding on these vendors do take a plain API key.
+ if other := v.CredentialLabelFor(types.ModelTypeKnowledgeQA); other != nil {
+ t.Errorf("chat should keep the generic API-key wording, got %q", other.Label)
+ }
+ })
+ }
+}
diff --git a/internal/models/vendors/volcengine/icon.svg b/internal/models/vendors/volcengine/icon.svg
new file mode 100644
index 000000000..ecf6d75e0
--- /dev/null
+++ b/internal/models/vendors/volcengine/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Volcengine</title><path d="M19.44 10.153l-2.936 11.586a.215.215 0 00.214.261h5.87a.215.215 0 00.214-.261l-2.95-11.586a.214.214 0 00-.412 0zM3.28 12.778l-2.275 8.96A.214.214 0 001.22 22h4.532a.212.212 0 00.214-.165.214.214 0 000-.097l-2.276-8.96a.214.214 0 00-.41 0z" fill="#00E5E5"></path><path d="M7.29 5.359L3.148 21.738a.215.215 0 00.203.261h8.29a.214.214 0 00.215-.261L7.7 5.358a.214.214 0 00-.41 0z" fill="#006EFF"></path><path d="M14.44.15a.214.214 0 00-.41 0L8.366 21.739a.214.214 0 00.214.261H19.9a.216.216 0 00.171-.078.214.214 0 00.044-.183L14.439.15z" fill="#006EFF"></path><path d="M10.278 7.741L6.685 21.736a.214.214 0 00.214.264h7.17a.215.215 0 00.214-.264L10.688 7.741a.214.214 0 00-.41 0z" fill="#00E5E5"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/volcengine/models.json b/internal/models/vendors/volcengine/models.json
new file mode 100644
index 000000000..27c7a3dcc
--- /dev/null
+++ b/internal/models/vendors/volcengine/models.json
@@ -0,0 +1,27 @@
+{
+ "vendor": "volcengine",
+ "source": "https://www.volcengine.com/docs/82379/1494384",
+ "models": [
+ {"id": "doubao-seed-2-1-pro-260915", "name": "Doubao Seed 2.1 Pro (260915)", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1024000, "max_output_tokens": 256000, "source": "https://docs.volcengine.com/docs/ark/model-list?lang=zh"},
+ {"id": "doubao-seed-2-1-pro-260628", "name": "Doubao Seed 2.1 Pro", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 256000, "cost": {"input": 0.8906, "output": 4.45301, "cache_read": 0.17812}},
+ {"id": "doubao-seed-2-1-turbo-260628", "name": "Doubao Seed 2.1 Turbo", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 256000, "cost": {"input": 0.4453, "output": 2.22651, "cache_read": 0.08906}},
+ {"id": "doubao-seed-2-0-pro-260215", "name": "Doubao Seed 2.0 Pro", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 131072, "cost": {"input": 0.47499, "output": 2.37494, "cache_read": 0.095}, "compat": {"fixed_temperature": 1}, "source": "https://docs.volcengine.com/docs/ark/model-list?lang=zh"},
+ {"id": "doubao-seed-2-0-lite-260428", "name": "Doubao Seed 2.0 Lite", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 131072, "cost": {"input": 0.08906, "output": 0.53436, "cache_read": 0.01781}},
+ {"id": "doubao-seed-2-0-mini-260428", "name": "Doubao Seed 2.0 Mini", "reasoning": true, "input": ["text", "image", "video"], "context_window": 256000, "max_output_tokens": 131072, "cost": {"input": 0.02969, "output": 0.29687, "cache_read": 0.00594}},
+ {"id": "doubao-seed-2-0-code-preview-260215", "name": "Doubao Seed 2.0 Code Preview", "reasoning": true, "input": ["text", "image", "video"], "context_window": 262144, "max_output_tokens": 131072, "cost": {"input": 0.47499, "output": 2.37494, "cache_read": 0.095}},
+ {"id": "doubao-seed-1-8-251228", "name": "Doubao Seed 1.8 (retiring)", "deprecated": true, "reasoning": true, "input": ["text", "image"], "context_window": 256000, "max_output_tokens": 32768, "cost": {"input": 0.11875, "output": 1.18747, "cache_read": 0.02375}, "source": "https://docs.volcengine.com/docs/ark/model-list?lang=zh"},
+ {"id": "doubao-seed-1-6-251015", "name": "Doubao Seed 1.6 (retiring)", "deprecated": true, "reasoning": true, "input": ["text"], "context_window": 256000, "max_output_tokens": 32768, "cost": {"input": 0.11875, "output": 1.18747, "cache_read": 0.02375}, "source": "https://docs.volcengine.com/docs/ark/model-list?lang=zh"},
+ {"id": "doubao-seed-1-6-flash-250828", "name": "Doubao Seed 1.6 Flash (retiring)", "deprecated": true, "reasoning": true, "input": ["text", "image"], "context_window": 256000, "max_output_tokens": 32768, "cost": {"input": 0.02227, "output": 0.22265, "cache_read": 0.00445}, "compat": {"supports_reasoning_effort": false}, "source": "https://docs.volcengine.com/docs/ark/deep-thinking?lang=zh"},
+ {"id": "doubao-seed-1-6-vision-250815", "name": "Doubao Seed 1.6 Vision (retiring)", "deprecated": true, "reasoning": true, "input": ["text", "image"], "context_window": 256000, "max_output_tokens": 32768, "cost": {"input": 0.11875, "output": 1.18747, "cache_read": 0.02375}, "compat": {"supports_reasoning_effort": false}, "source": "https://docs.volcengine.com/docs/ark/deep-thinking?lang=zh"},
+ {"id": "deepseek-v4-1-flash-260910", "name": "DeepSeek V4.1 Flash (Ark)", "reasoning": true, "input": ["text", "image"], "context_window": 1000000, "max_output_tokens": 393216, "source": "https://docs.volcengine.com/docs/ark/model-list?lang=zh"},
+ {"id": "deepseek-v4-pro-ga-260813", "name": "DeepSeek V4 Pro (Ark)", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 393216, "cost": {"input": 1.3359, "output": 4.00771, "cache_read": 0.04453}},
+ {"id": "deepseek-v4-flash-ga-260731", "name": "DeepSeek V4 Flash (Ark)", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 393216, "cost": {"input": 0.4453, "output": 1.3359, "cache_read": 0.01484}},
+ {"id": "glm-5-3-flash-260828", "name": "GLM-5.3 Flash (Ark)", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 0.11875, "output": 0.41563, "cache_read": 0.03414}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://docs.volcengine.com/docs/ark/deep-thinking?lang=zh"},
+ {"id": "glm-5-2-260617", "name": "GLM-5.2 (Ark)", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 1.18747, "output": 4.15615, "cache_read": 0.29687}},
+ {"id": "doubao-embedding-large-text-250515", "name": "Doubao Embedding Large Text", "type": "Embedding", "dimension": 2048, "source": "https://www.volcengine.com/docs/82379/1302003"},
+ {"id": "doubao-embedding-vision-251215", "name": "Doubao Embedding Vision (251215)", "type": "Embedding", "dimension": 2048, "source": "https://docs.volcengine.com/docs/ark/multimodal-vectorization-api?lang=zh"},
+ {"id": "doubao-embedding-vision-250615", "name": "Doubao Embedding Vision", "type": "Embedding", "dimension": 2048, "source": "https://docs.volcengine.com/docs/ark/multimodal-vectorization-api?lang=zh"},
+ {"id": "doubao-seed-rerank", "name": "Doubao Seed Rerank", "type": "Rerank", "source": "https://www.volcengine.com/docs/84313/1254474"},
+ {"id": "base-multilingual-rerank", "name": "Base Multilingual Rerank", "type": "Rerank", "source": "https://www.volcengine.com/docs/84313/1254474"}
+ ]
+}
diff --git a/internal/models/vendors/volcengine/vendor.go b/internal/models/vendors/volcengine/vendor.go
new file mode 100644
index 000000000..aae1b9291
--- /dev/null
+++ b/internal/models/vendors/volcengine/vendor.go
@@ -0,0 +1,195 @@
+// Package volcengine registers Volcengine Ark (Doubao) through its
+// OpenAI-compatible chat endpoint.
+//
+// Facts (https://www.volcengine.com/docs/82379/1494384 = Chat API reference,
+// https://docs.volcengine.com/docs/ark/deep-thinking and
+// https://docs.volcengine.com/docs/ark/base-url-and-authentication):
+// - the data-plane base URL is https://ark.cn-beijing.volces.com/api/v3
+// (chat completions at /chat/completions) with Bearer API-key auth; AK/SK
+// signing is the alternative and is what the managed rerank service uses;
+// - output cap stays `max_completion_tokens` ("控制模型输出的最大长度(包括
+// 模型回答和模型思维链内容长度)"), which is explicitly "不可与
+// max_tokens 字段同时设置". Its documented range is [1, 65536];
+// `max_tokens` defaults to 4096 and covers the answer only;
+// - thinking is switched with `thinking: {"type": ...}` where the type is
+// enabled | disabled | auto — Ark does accept "auto" ("模型自行判断是否
+// 需要进行深度思考"), although only doubao-seed-1-6-250615 lists it as
+// supported today. Every model tagged 深度思考 defaults to enabled;
+// - `reasoning_effort` takes none | minimal | low | medium | high | xhigh |
+// max and "所有支持该字段的模型均接受全部 7 档取值"; each model then maps
+// the rungs it does not implement onto equivalents (Seed 2.x folds
+// xhigh/max into high, glm-5-3-flash folds them into max, and on most
+// models `minimal` switches thinking off). The vendor map therefore
+// passes all seven through verbatim;
+// - doubao-seed-1-6-flash-250828 and doubao-seed-1-6-vision-250815 are
+// absent from the reasoning_effort table, so those entries turn it off;
+// - glm-5-3-flash-260828 "始终启用思考,不再支持禁用思考", so it carries
+// "off": null;
+// - temperature is [0, 2] but is "固定为 1,手动指定的参数值将被忽略" on
+// doubao-seed-2-0-pro-260215 and doubao-seed-2-0-lite-260215;
+// - tool_choice takes none / auto / required / a named function, and
+// parallel_tool_calls (default true, false only on doubao-seed-1.6 and
+// later), response_format (text | json_object | json_schema, beta) and
+// stream_options.include_usage are all documented, so the protocol
+// defaults stand. glm-5-2-260617, deepseek-v4-pro-ga-260813 and
+// deepseek-v4-flash-ga-260731 return streaming usage even without
+// include_usage;
+// - usage reports `prompt_tokens_details.cached_tokens` (implicit cache);
+// explicit prefix / session caching is a separate Context Cache API and
+// is not driven from here;
+// - in tool-calling turns Ark also returns `encrypted_content` next to
+// `reasoning_content` and asks for it to be replayed; omitting it is not
+// an error but degrades multi-turn agent quality;
+// - multimodal embeddings post to /api/v3/embeddings/multimodal with
+// `dimensions` defaulting to 2048
+// (https://docs.volcengine.com/docs/ark/multimodal-vectorization-api);
+// - rerank is the VikingDB Knowledge Base service signed with AK/SK at
+// https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/service/rerank
+// (the API key field carries the access key; the secret key, region and
+// instruction come from the rerank-only extra fields). Documented models
+// are doubao-seed-rerank and base-multilingual-rerank
+// (https://www.volcengine.com/docs/84313/1254474);
+// - Ark additionally serves an Anthropic Messages surface at
+// https://ark.cn-beijing.volces.com/api/compatible/v1 with x-api-key
+// auth. This package configures OpenAI Chat Completions, which is the
+// surface every model page documents first.
+//
+// unverified: text-only embedding models post to /api/v3/embeddings, not the
+// multimodal path this vendor defaults to, and WeKnora's Ark embedder pins
+// the multimodal path regardless of the configured base URL. The default is
+// left alone; doubao-embedding-large-text-250515 is kept because no
+// retirement notice was found, even though the current 向量化 model list only
+// names the two doubao-embedding-vision snapshots.
+//
+// unverified: the model list spells lengths as "256k" / "1024k" without
+// saying whether k is 1000 or 1024, so the context windows in models.json are
+// left at their present values.
+//
+// unverified: the rerank instruction default here capitalises Document /
+// Query while the console default in the docs is lower case; it is kept in
+// sync with internal/models/rerank instead.
+//
+// unverified: prices in models.json come from the Ark pricing console, which
+// the public docs do not render.
+package volcengine
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "volcengine"
+
+// BaseURL is the OpenAI-compatible Ark chat endpoint.
+const BaseURL = "https://ark.cn-beijing.volces.com/api/v3"
+
+// EmbeddingBaseURL is the Ark multimodal embedding endpoint.
+const EmbeddingBaseURL = "https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal"
+
+// RerankBaseURL is the Knowledge Base managed rerank endpoint.
+const RerankBaseURL = "https://api-knowledgebase.mlp.cn-beijing.volces.com"
+
+// AnthropicBaseURL is the documented Anthropic Messages surface. It is not
+// the default for this vendor; operators who want it configure it explicitly.
+const AnthropicBaseURL = "https://ark.cn-beijing.volces.com/api/compatible/v1"
+
+func init() {
+ rerankOnly := []types.ModelType{types.ModelTypeRerank}
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Volcengine Ark",
+ Names: map[string]string{"zh-CN": "火山引擎 Volcengine"},
+ Description: "doubao-seed-2-1-pro-260628, deepseek-v4-pro-ga-260813, " +
+ "doubao-embedding-vision-250615, doubao-seed-rerank, etc.",
+ Website: "https://console.volcengine.com/ark",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 12,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"volces.com", "volcengine"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: EmbeddingBaseURL,
+ types.ModelTypeRerank: RerankBaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ },
+ // Rerank is signed with an IAM access-key pair, so the first
+ // credential is an Access Key ID rather than an Ark bearer token.
+ CredentialLabels: []catalog.CredentialLabel{{
+ Label: "Access Key ID",
+ Labels: map[string]string{"zh-CN": "Access Key ID(AK/SK 签名)"},
+ Placeholder: "Volcengine IAM access key id (AKLT...)",
+ Placeholders: map[string]string{"zh-CN": "火山引擎 IAM Access Key ID(AKLT 开头)"},
+ Hint: "Rerank is signed with an IAM key pair; this is not an Ark API key.",
+ Hints: map[string]string{"zh-CN": "Rerank 使用 IAM 密钥对签名,不是方舟的 API Key。"},
+ ModelTypes: rerankOnly,
+ Required: true,
+ }},
+ ExtraFields: []catalog.ExtraField{
+ {
+ Key: "secret_key",
+ Label: "Secret Key",
+ Labels: map[string]string{"zh-CN": "Secret Key(AK/SK 签名)"},
+ Type: "password",
+ Required: true,
+ Placeholder: "Volcengine IAM secret key (the API Key field holds the access key)",
+ ModelTypes: rerankOnly,
+ Secret: true,
+ },
+ {
+ Key: "region",
+ Label: "Region",
+ Labels: map[string]string{"zh-CN": "地域"},
+ Type: "string",
+ Default: "cn-beijing",
+ Placeholder: "cn-beijing",
+ ModelTypes: rerankOnly,
+ },
+ {
+ Key: "instruction",
+ Label: "Rerank Instruction",
+ Labels: map[string]string{"zh-CN": "重排指令"},
+ Type: "string",
+ Default: "Whether the Document answers the Query or matches the content retrieval intent",
+ Placeholder: "Instruction passed to the rerank model",
+ ModelTypes: rerankOnly,
+ },
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ },
+ },
+ // Ark accepts all seven effort rungs on every model that supports the
+ // field and maps the ones a model does not implement itself, so each
+ // level is passed through under its own name.
+ ThinkingLevels: api.ThinkingLevelMap{
+ api.ReasoningMinimal: api.StringPtr("minimal"),
+ api.ReasoningLow: api.StringPtr("low"),
+ api.ReasoningMedium: api.StringPtr("medium"),
+ api.ReasoningHigh: api.StringPtr("high"),
+ api.ReasoningXHigh: api.StringPtr("xhigh"),
+ api.ReasoningMax: api.StringPtr("max"),
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/weknoracloud/icon.svg b/internal/models/vendors/weknoracloud/icon.svg
new file mode 100644
index 000000000..a83416922
--- /dev/null
+++ b/internal/models/vendors/weknoracloud/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><rect width="24" height="24" rx="5" fill="#07C160"/><text x="12" y="16" font-family="sans-serif" font-weight="700" font-size="10" fill="#FFFFFF" text-anchor="middle">WK</text></svg>
diff --git a/internal/models/vendors/weknoracloud/models.json b/internal/models/vendors/weknoracloud/models.json
new file mode 100644
index 000000000..c6eb4252c
--- /dev/null
+++ b/internal/models/vendors/weknoracloud/models.json
@@ -0,0 +1,4 @@
+{
+ "vendor": "weknoracloud",
+ "models": []
+}
diff --git a/internal/models/vendors/weknoracloud/vendor.go b/internal/models/vendors/weknoracloud/vendor.go
new file mode 100644
index 000000000..b2e3628d1
--- /dev/null
+++ b/internal/models/vendors/weknoracloud/vendor.go
@@ -0,0 +1,119 @@
+// Package weknoracloud registers the WeKnora managed model service.
+//
+// unverified: this is a first-party endpoint with no published API
+// reference — https://weknora.weixin.qq.com/docs documents the WeKnora
+// product, not the model gateway's wire protocol. Every fact below is taken
+// from this repository's own clients rather than from vendor documentation,
+// and is cited accordingly:
+// - one host serves chat, embedding, rerank and VLM. Chat completions and
+// VLM live at /api/v1/chat/completions rather than the OpenAI default
+// path (internal/models/vlm/weknoracloud.go), embeddings at
+// /api/v1/embeddings (internal/models/embedding/weknoracloud.go) and
+// rerank at /api/v1/rerank (internal/models/rerank/weknoracloud.go).
+// Only the chat path goes through the Endpoint hook; the other three
+// clients build their own URLs;
+// - requests are signed with the tenant's AppID / AppSecret through
+// modelutils.Sign (internal/models/utils/signer.go), which sends
+// X-APPID, X-API-Key, X-Request-ID, X-Timestamp, X-Nonce and an
+// X-Signature that is the MD5 of the RFC3986-encoded, key-sorted
+// parameter string including the MD5 of the body. There is no bearer
+// key, hence the AuthSigned style and a fresh request id per call;
+// - credentials are provisioned through the dedicated initialization
+// endpoint (internal/handler/weknoracloud.go), so Validate performs no
+// key check here;
+// - the model names the product provisions are chat, embedding, rerank and
+// vlm (frontend/src/utils/weknoraCloudModels.ts). models.json is left
+// empty on purpose: no context window, output cap or price is published
+// for them, and the embedding dimension is probed at runtime through
+// GET /api/v1/models/weknoracloud/status.
+//
+// unverified: SupportsMultiContent is kept false so chat messages are
+// flattened to plain text, but nothing documents that restriction and the
+// VLM client posts image_url parts to the very same /api/v1/chat/completions
+// path, so it may only apply to the chat model. The value is left as-is
+// because the transport test pins it.
+//
+// unverified: PromptCacheAccounting is kept false; the gateway is not
+// documented to report prompt-cache counters, and none have been observed.
+package weknoracloud
+
+import (
+ _ "embed"
+ "net/http"
+ "strings"
+
+ "github.com/google/uuid"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ modelutils "github.com/Tencent/WeKnora/internal/models/utils"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "weknoracloud"
+
+// BaseURL is the single service entry point; per-capability paths are
+// appended by the Endpoint hook and the embedding / rerank clients.
+const BaseURL = "https://weknora.weixin.qq.com"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "WeKnora Cloud",
+ Names: map[string]string{"zh-CN": "WeKnora 云服务"},
+ Description: "WeKnora managed models: chat, embedding, rerank, vlm",
+ Descriptions: map[string]string{"zh-CN": "WeKnora云服务,模型:chat, embedding, rerank, vlm"},
+ Website: BaseURL,
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 1,
+ RequiresAuth: true,
+ Auth: catalog.AuthSigned,
+ URLPatterns: []string{"weknora.weixin.qq.com"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: BaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ SupportsMultiContent: catalog.Ptr(false),
+ PromptCacheAccounting: catalog.Ptr(false),
+ },
+ },
+ Signer: func(creds catalog.Credentials) api.AuthFunc {
+ return func(req *http.Request, body []byte) {
+ headers := modelutils.Sign(creds.AppID, creds.AppSecret, uuid.NewString(), string(body))
+ for k, v := range headers {
+ req.Header.Set(k, v)
+ }
+ }
+ },
+ Endpoint: func(r catalog.EndpointRequest) (string, map[string]string) {
+ switch r.ModelType {
+ case types.ModelTypeEmbedding, types.ModelTypeRerank, types.ModelTypeASR:
+ // Those clients build their own paths; fall back.
+ return "", nil
+ }
+ return strings.TrimRight(r.BaseURL, "/") + "/api/v1/chat/completions", nil
+ },
+ // AppID / AppSecret are written by the dedicated initialization
+ // endpoint; only structural checks happen there.
+ Validate: func(_ *catalog.Config) error { return nil },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vendors/zhipu/icon.svg b/internal/models/vendors/zhipu/icon.svg
new file mode 100644
index 000000000..0c6e61cea
--- /dev/null
+++ b/internal/models/vendors/zhipu/icon.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Zhipu</title><path d="M11.991 23.503a.24.24 0 00-.244.248.24.24 0 00.244.249.24.24 0 00.245-.249.24.24 0 00-.22-.247l-.025-.001zM9.671 5.365a1.697 1.697 0 011.099 2.132l-.071.172-.016.04-.018.054c-.07.16-.104.32-.104.498-.035.71.47 1.279 1.186 1.314h.366c1.309.053 2.338 1.173 2.286 2.523-.052 1.332-1.152 2.38-2.478 2.327h-.174c-.715.018-1.274.64-1.239 1.368 0 .124.018.23.053.337.209.373.54.658.96.8.75.23 1.517-.125 1.9-.782l.018-.035c.402-.64 1.17-.96 1.92-.711.854.284 1.378 1.226 1.099 2.167a1.661 1.661 0 01-2.077 1.102 1.711 1.711 0 01-.907-.711l-.017-.035c-.2-.323-.463-.58-.851-.711l-.056-.018a1.646 1.646 0 00-1.954.746 1.66 1.66 0 01-1.065.764 1.677 1.677 0 01-1.989-1.279c-.209-.906.332-1.83 1.257-2.043a1.51 1.51 0 01.296-.035h.018c.68-.071 1.151-.622 1.116-1.333a1.307 1.307 0 00-.227-.693 2.515 2.515 0 01-.366-1.403 2.39 2.39 0 01.366-1.208c.14-.195.21-.444.227-.693.018-.71-.506-1.261-1.186-1.332l-.07-.018a1.43 1.43 0 01-.299-.07l-.05-.019a1.7 1.7 0 01-1.047-2.114 1.68 1.68 0 012.094-1.101zm-5.575 10.11c.26-.264.639-.367.994-.27.355.096.633.379.728.74.095.362-.007.748-.267 1.013-.402.41-1.053.41-1.455 0a1.062 1.062 0 010-1.482zm14.845-.294c.359-.09.738.024.992.297.254.274.344.665.237 1.025-.107.36-.396.634-.756.718-.551.128-1.1-.22-1.23-.781a1.05 1.05 0 01.757-1.26zm-.064-4.39c.314.32.49.753.49 1.206 0 .452-.176.886-.49 1.206-.315.32-.74.5-1.185.5-.444 0-.87-.18-1.184-.5a1.727 1.727 0 010-2.412 1.654 1.654 0 012.369 0zm-11.243.163c.364.484.447 1.128.218 1.691a1.665 1.665 0 01-2.188.923c-.855-.36-1.26-1.358-.907-2.228a1.68 1.68 0 011.33-1.038c.593-.08 1.183.169 1.547.652zm11.545-4.221c.368 0 .708.2.892.524.184.324.184.724 0 1.048a1.026 1.026 0 01-.892.524c-.568 0-1.03-.47-1.03-1.048 0-.579.462-1.048 1.03-1.048zm-14.358 0c.368 0 .707.2.891.524.184.324.184.724 0 1.048a1.026 1.026 0 01-.891.524c-.569 0-1.03-.47-1.03-1.048 0-.579.461-1.048 1.03-1.048zm10.031-1.475c.925 0 1.675.764 1.675 1.706s-.75 1.705-1.675 1.705-1.674-.763-1.674-1.705c0-.942.75-1.706 1.674-1.706zm-2.626-.684c.362-.082.653-.356.761-.718a1.062 1.062 0 00-.238-1.028 1.017 1.017 0 00-.996-.294c-.547.14-.881.7-.752 1.257.13.558.675.907 1.225.783zm0 16.876c.359-.087.644-.36.75-.72a1.062 1.062 0 00-.237-1.019 1.018 1.018 0 00-.985-.301 1.037 1.037 0 00-.762.717c-.108.361-.017.754.239 1.028.245.263.606.377.953.305l.043-.01zM17.19 3.5a.631.631 0 00.628-.64c0-.355-.279-.64-.628-.64a.631.631 0 00-.628.64c0 .355.28.64.628.64zm-10.38 0a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64a.631.631 0 00-.628.64c0 .355.279.64.628.64zm-5.182 7.852a.631.631 0 00-.628.64c0 .354.28.639.628.639a.63.63 0 00.627-.606l.001-.034a.62.62 0 00-.628-.64zm5.182 9.13a.631.631 0 00-.628.64c0 .355.279.64.628.64a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64zm10.38.018a.631.631 0 00-.628.64c0 .355.28.64.628.64a.631.631 0 00.628-.64c0-.355-.279-.64-.628-.64zm5.182-9.148a.631.631 0 00-.628.64c0 .354.279.639.628.639a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64zm-.384-4.992a.24.24 0 00.244-.249.24.24 0 00-.244-.249.24.24 0 00-.244.249c0 .142.122.249.244.249zM11.991.497a.24.24 0 00.245-.248A.24.24 0 0011.99 0a.24.24 0 00-.244.249c0 .133.108.236.223.247l.021.001zM2.011 6.36a.24.24 0 00.245-.249.24.24 0 00-.244-.249.24.24 0 00-.244.249.24.24 0 00.244.249zm0 11.263a.24.24 0 00-.243.248.24.24 0 00.244.249.24.24 0 00.244-.249.252.252 0 00-.244-.248zm19.995-.018a.24.24 0 00-.245.248.24.24 0 00.245.25.24.24 0 00.244-.25.252.252 0 00-.244-.248z" fill="#3859FF" fill-rule="nonzero"></path></svg>
\ No newline at end of file
diff --git a/internal/models/vendors/zhipu/models.json b/internal/models/vendors/zhipu/models.json
new file mode 100644
index 000000000..1eba71ee0
--- /dev/null
+++ b/internal/models/vendors/zhipu/models.json
@@ -0,0 +1,20 @@
+{
+ "vendor": "zhipu",
+ "source": "https://docs.bigmodel.cn/api-reference/模型-api/对话补全",
+ "models": [
+ {"id": "glm-5.3", "name": "GLM-5.3", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3"},
+ {"id": "glm-5.3-flash", "name": "GLM-5.3 Flash", "reasoning": true, "input": ["text", "image", "video"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 0.075, "output": 0.25, "cache_read": 0.015}, "thinking_levels": {"off": null, "minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://docs.bigmodel.cn/cn/guide/models/vlm/glm-5.3-flash"},
+ {"id": "glm-5.2", "name": "GLM-5.2", "reasoning": true, "input": ["text"], "context_window": 1000000, "max_output_tokens": 131072, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}, "thinking_levels": {"minimal": "low", "low": "low", "medium": "high", "high": "high", "xhigh": "max", "max": "max"}, "source": "https://docs.bigmodel.cn/cn/guide/models/text/glm-5.2"},
+ {"id": "glm-5.1", "name": "GLM-5.1", "reasoning": true, "input": ["text"], "context_window": 200000, "max_output_tokens": 131072, "cost": {"input": 1.4, "output": 4.4, "cache_read": 0.26}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-5", "name": "GLM-5", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 1, "output": 3.2, "cache_read": 0.2}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-5v-turbo", "name": "GLM-5V Turbo", "reasoning": true, "input": ["text", "image", "video"], "context_window": 200000, "max_output_tokens": 131072, "cost": {"input": 5, "output": 22, "cache_read": 1.2}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-4.7", "name": "GLM-4.7", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.6, "output": 2.2, "cache_read": 0.11}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-4.7-flash", "name": "GLM-4.7 Flash", "reasoning": true, "input": ["text"], "context_window": 200000, "max_output_tokens": 131072, "cost": {"input": 0, "output": 0}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-4.6v", "name": "GLM-4.6V", "reasoning": true, "input": ["text", "image", "video"], "context_window": 128000, "max_output_tokens": 32768, "cost": {"input": 0.3, "output": 0.9}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-4.6", "name": "GLM-4.6", "reasoning": true, "input": ["text"], "context_window": 204800, "max_output_tokens": 131072, "cost": {"input": 0.6, "output": 2.2, "cache_read": 0.11}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "glm-4.5-air", "name": "GLM-4.5 Air", "reasoning": true, "input": ["text"], "context_window": 131072, "max_output_tokens": 98304, "cost": {"input": 0.2, "output": 1.1, "cache_read": 0.03}, "compat": {"supports_reasoning_effort": false}},
+ {"id": "embedding-3", "name": "Embedding-3", "type": "Embedding", "dimension": 2048, "source": "https://docs.bigmodel.cn/api-reference/模型-api/文本嵌入"},
+ {"id": "embedding-2", "name": "Embedding-2", "type": "Embedding", "dimension": 1024, "source": "https://docs.bigmodel.cn/api-reference/模型-api/文本嵌入"},
+ {"id": "rerank", "name": "Rerank", "type": "Rerank", "source": "https://docs.bigmodel.cn/api-reference/模型-api/文本重排序"}
+ ]
+}
diff --git a/internal/models/vendors/zhipu/vendor.go b/internal/models/vendors/zhipu/vendor.go
new file mode 100644
index 000000000..e528f66e7
--- /dev/null
+++ b/internal/models/vendors/zhipu/vendor.go
@@ -0,0 +1,130 @@
+// Package zhipu registers Zhipu AI's BigModel open platform.
+//
+// Facts (https://docs.bigmodel.cn/api-reference/模型-api/对话补全):
+// - chat completions live at POST /paas/v4/chat/completions under
+// https://open.bigmodel.cn/api, so the base URL is
+// https://open.bigmodel.cn/api/paas/v4;
+// - output cap is `max_tokens`; the reference lists no
+// `max_completion_tokens`. GLM-5.3 / 5.2 / 5.1 / 5 / 4.7 / 4.6 cap at
+// 128K output, the GLM-4.5 series at 96K;
+// - thinking is switched with `thinking: {"type": "enabled"|"disabled"}`
+// (default enabled, GLM-4.5 and later only). The sibling
+// `clear_thinking` defaults to true, i.e. the platform strips
+// `reasoning_content` from previous turns unless it is set to false, so
+// replaying it is accepted but normally a no-op;
+// - `reasoning_effort` takes none | minimal | low | medium | high | xhigh |
+// max, defaults to max, and is only honoured by "GLM-5.2 及其以上模型" —
+// GLM-5.1, GLM-5, GLM-4.7, GLM-4.6 and GLM-4.5 ignore it, so those
+// entries turn it off. The vendor-level map spells every rung, including
+// off -> "none";
+// - per-model effort ladders narrow that set: GLM-5.3 and GLM-5.3-Flash
+// only take low / high / max, and GLM-5.2 maps none|minimal to "no
+// thinking", low|medium to high and xhigh to max;
+// - GLM-5.3 and GLM-5.3-Flash/FlashX always think: `thinking.type` "限制只
+// 能开启", so both carry "off": null
+// (https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3,
+// https://docs.bigmodel.cn/cn/guide/models/vlm/glm-5.3-flash);
+// - `tool_choice` is documented as "默认 auto 且仅支持 auto", so none /
+// required / named-function are never sent;
+// - `response_format` takes text | json_object (no json_schema);
+// temperature is [0.0, 1.0] and top_p is [0.01, 1.0], both two decimals;
+// - usage reports `prompt_tokens_details.cached_tokens`;
+// - the platform also exposes an Anthropic Messages facade at
+// https://open.bigmodel.cn/api/anthropic (/v1/messages under it), which
+// Resolve switches to when the base URL ends with /anthropic;
+// - embeddings: embedding-3 defaults to 2048 dimensions (256 / 512 / 1024 /
+// 2048 selectable), embedding-2 is fixed at 1024;
+// - rerank is POST https://open.bigmodel.cn/api/paas/v4/rerank with model
+// id "rerank".
+//
+// unverified: the reference does not document `stream_options`,
+// `parallel_tool_calls` or `seed`; the protocol defaults (include_usage sent,
+// parallel tool calls and seed allowed) are kept because nothing states they
+// are rejected.
+//
+// unverified: glm-5v-turbo is a vision model and the "GLM-5.2 及其以上" rule
+// does not name it, so its supports_reasoning_effort:false is kept as-is.
+//
+// unverified: context windows, max output tokens and prices of individual
+// entries beyond the GLM-5 / 5.2 / 5.3 / 4.7 model pages, and the
+// glm-4.7-flash zero price.
+package zhipu
+
+import (
+ _ "embed"
+
+ "github.com/Tencent/WeKnora/internal/models/api"
+ "github.com/Tencent/WeKnora/internal/models/catalog"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+//go:embed models.json
+var modelsJSON []byte
+
+//go:embed icon.svg
+var icon []byte
+
+// ID is the provider identifier stored on model rows.
+const ID = "zhipu"
+
+// BaseURL is the OpenAI-compatible chat / embedding endpoint.
+const BaseURL = "https://open.bigmodel.cn/api/paas/v4"
+
+// RerankBaseURL is the rerank endpoint.
+const RerankBaseURL = "https://open.bigmodel.cn/api/paas/v4/rerank"
+
+// AnthropicBaseURL is the Anthropic Messages compatibility facade.
+const AnthropicBaseURL = "https://open.bigmodel.cn/api/anthropic"
+
+func init() {
+ catalog.Register(&catalog.Vendor{
+ ID: ID,
+ Name: "Zhipu BigModel",
+ Names: map[string]string{"zh-CN": "智谱 BigModel"},
+ Description: "glm-5.3, glm-5.2, glm-4.7, embedding-3, rerank; " +
+ "Anthropic-compatible facade at " + AnthropicBaseURL,
+ Descriptions: map[string]string{
+ "zh-CN": "glm-5.3, glm-5.2, glm-4.7, embedding-3, rerank;Anthropic 兼容接口 " + AnthropicBaseURL,
+ },
+ Website: "https://open.bigmodel.cn",
+ Icon: icon,
+ API: api.APIOpenAICompletions,
+ Order: 11,
+ RequiresAuth: true,
+ Auth: catalog.AuthBearer,
+ URLPatterns: []string{"open.bigmodel.cn", "zhipu"},
+ DefaultBaseURLs: map[types.ModelType]string{
+ types.ModelTypeKnowledgeQA: BaseURL,
+ types.ModelTypeEmbedding: BaseURL,
+ types.ModelTypeRerank: RerankBaseURL,
+ types.ModelTypeVLLM: BaseURL,
+ },
+ ModelTypes: []types.ModelType{
+ types.ModelTypeKnowledgeQA,
+ types.ModelTypeEmbedding,
+ types.ModelTypeRerank,
+ types.ModelTypeVLLM,
+ },
+ Compat: catalog.VendorCompat{
+ OpenAICompletions: catalog.OpenAICompletionsCompat{
+ MaxTokensField: catalog.Ptr("max_tokens"),
+ ThinkingFormat: catalog.Ptr(catalog.ThinkingFormatThinkingType),
+ SupportsReasoningEffort: catalog.Ptr(true),
+ PromptCacheAccounting: catalog.Ptr(true),
+ // "默认 auto 且仅支持 auto": none / required / named function
+ // are rejected.
+ ToolChoiceModes: []string{"auto"},
+ },
+ },
+ ThinkingLevels: api.ThinkingLevelMap{
+ api.ReasoningOff: api.StringPtr("none"),
+ api.ReasoningMinimal: api.StringPtr("minimal"),
+ api.ReasoningLow: api.StringPtr("low"),
+ api.ReasoningMedium: api.StringPtr("medium"),
+ api.ReasoningHigh: api.StringPtr("high"),
+ api.ReasoningXHigh: api.StringPtr("xhigh"),
+ api.ReasoningMax: api.StringPtr("max"),
+ },
+ Models: catalog.MustParseModels(modelsJSON),
+ })
+}
diff --git a/internal/models/vlm/remote_api.go b/internal/models/vlm/remote_api.go
index 2544d11af..1d1de4efb 100644
--- a/internal/models/vlm/remote_api.go
+++ b/internal/models/vlm/remote_api.go
@@ -11,9 +11,8 @@ import (
"time"
"github.com/Tencent/WeKnora/internal/logger"
- "github.com/Tencent/WeKnora/internal/models/provider"
- secutils "github.com/Tencent/WeKnora/internal/utils"
- openai "github.com/sashabaranov/go-openai"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
)
const (
@@ -38,13 +37,15 @@ func vlmHTTPTimeout() time.Duration {
return defaultTimeout
}
-// RemoteAPIVLM implements VLM via an OpenAI-compatible chat completions API.
+// RemoteAPIVLM implements VLM on top of the catalog-driven chat client: a
+// vision call is a chat call whose user turn carries images, so the vendor
+// dialect (max_tokens field, sampling restrictions, protocol) is resolved
+// exactly like it is for chat models.
type RemoteAPIVLM struct {
modelName string
modelID string
- client *openai.Client
- baseURL string
- temperature float32
+ chat chat.Chat
+ temperature float64
}
// NewRemoteAPIVLM creates a remote-API backed VLM instance.
@@ -53,154 +54,85 @@ func NewRemoteAPIVLM(config *Config) (*RemoteAPIVLM, error) {
return nil, err
}
- providerName := provider.ProviderName(config.Provider)
- if providerName == "" {
- providerName = provider.DetectProvider(config.BaseURL)
- }
-
- var apiCfg openai.ClientConfig
- if providerName == provider.ProviderAzureOpenAI {
- apiCfg = openai.DefaultAzureConfig(config.APIKey, config.BaseURL)
- apiCfg.AzureModelMapperFunc = func(model string) string {
- return model
- }
- if config.Extra != nil {
- if v, ok := config.Extra["api_version"]; ok {
- if vs, ok := v.(string); ok && vs != "" {
- apiCfg.APIVersion = vs
- }
- }
- }
- } else {
- apiCfg = openai.DefaultConfig(config.APIKey)
- if config.BaseURL != "" {
- apiCfg.BaseURL = config.BaseURL
+ temp := float64(defaultTemp)
+ extra := make(map[string]string, len(config.Extra))
+ for k, v := range config.Extra {
+ if s, ok := v.(string); ok {
+ extra[k] = s
}
}
- httpClient := newVLMHTTPClient(vlmHTTPTimeout())
-
- // 注入用户自定义 HTTP header(类似 OpenAI Python SDK 的 extra_headers)
- if len(config.CustomHeaders) > 0 {
- apiCfg.HTTPClient = secutils.WrapHTTPClientWithHeaders(httpClient, config.CustomHeaders)
- } else {
- apiCfg.HTTPClient = httpClient
- }
-
- temp := defaultTemp
- if config.Extra != nil {
- if v, ok := config.Extra["temperature"]; ok {
- if vs, ok := v.(string); ok {
- if f, err := strconv.ParseFloat(vs, 32); err == nil {
- temp = float32(f)
- }
- }
+ if raw, ok := extra["temperature"]; ok {
+ if f, err := strconv.ParseFloat(raw, 64); err == nil {
+ temp = f
}
}
+ client, err := chat.NewRemoteChat(&chat.ChatConfig{
+ Source: types.ModelSourceRemote,
+ BaseURL: config.BaseURL,
+ ModelName: config.ModelName,
+ APIKey: config.APIKey,
+ ModelID: config.ModelID,
+ Provider: config.Provider,
+ ExtraConfig: extra,
+ CustomHeaders: config.CustomHeaders,
+ AppID: config.AppID,
+ AppSecret: config.AppSecret,
+ Spec: config.Spec,
+ })
+ if err != nil {
+ return nil, err
+ }
return &RemoteAPIVLM{
modelName: config.ModelName,
modelID: config.ModelID,
- client: openai.NewClientWithConfig(apiCfg),
- baseURL: config.BaseURL,
+ chat: client,
temperature: temp,
}, nil
}
-// Predict sends an image with a text prompt to the OpenAI-compatible API.
+// Predict sends images with a text prompt through the chat client.
func (v *RemoteAPIVLM) Predict(ctx context.Context, imgBytesList [][]byte, prompt string) (string, error) {
- var parts []openai.ChatMessagePart
-
- // Add text prompt first
- parts = append(parts, openai.ChatMessagePart{
- Type: openai.ChatMessagePartTypeText,
- Text: prompt,
- })
-
- // Add images
+ parts := []chat.MessageContentPart{{Type: "text", Text: prompt}}
+ totalImageSize := 0
for _, imgBytes := range imgBytesList {
- if len(imgBytes) > 0 {
- mimeType := detectImageMIME(imgBytes)
- b64 := base64.StdEncoding.EncodeToString(imgBytes)
- dataURI := fmt.Sprintf("data:%s;base64,%s", mimeType, b64)
- parts = append(parts, openai.ChatMessagePart{
- Type: openai.ChatMessagePartTypeImageURL,
- ImageURL: &openai.ChatMessageImageURL{
- URL: dataURI,
- Detail: openai.ImageURLDetailAuto,
- },
- })
+ if len(imgBytes) == 0 {
+ continue
}
+ totalImageSize += len(imgBytes)
+ dataURI := fmt.Sprintf("data:%s;base64,%s",
+ detectImageMIME(imgBytes), base64.StdEncoding.EncodeToString(imgBytes))
+ parts = append(parts, chat.MessageContentPart{
+ Type: "image_url", ImageURL: &chat.ImageURL{URL: dataURI, Detail: "auto"},
+ })
}
+ logger.Infof(ctx, "[VLM] Calling chat protocol, model=%s, numImages=%d, totalImageSize=%d",
+ v.modelName, len(imgBytesList), totalImageSize)
- req := openai.ChatCompletionRequest{
- Model: v.modelName,
- Messages: []openai.ChatCompletionMessage{
- {
- Role: openai.ChatMessageRoleUser,
- MultiContent: parts,
- },
- },
- MaxTokens: defaultMaxToks,
+ ctx, cancel := context.WithTimeout(ctx, vlmHTTPTimeout())
+ defer cancel()
+ resp, err := v.chat.Chat(ctx, []chat.Message{{Role: "user", MultiContent: parts}}, &chat.ChatOptions{
Temperature: v.temperature,
- }
- shapeReasoningVLMRequest(&req)
-
- totalImageSize := 0
- for _, img := range imgBytesList {
- totalImageSize += len(img)
- }
- logger.Infof(ctx, "[VLM] Calling OpenAI-compatible API, model=%s, baseURL=%s, numImages=%d, totalImageSize=%d",
- v.modelName, v.baseURL, len(imgBytesList), totalImageSize)
-
- resp, err := v.client.CreateChatCompletion(ctx, req)
+ MaxTokens: defaultMaxToks,
+ })
if err != nil {
- return "", fmt.Errorf("OpenAI VLM request: %w", err)
- }
- if len(resp.Choices) == 0 {
- return "", fmt.Errorf("OpenAI VLM returned no choices")
+ return "", fmt.Errorf("VLM request: %w", err)
}
-
- choice := resp.Choices[0]
- content := choice.Message.Content
- if strings.TrimSpace(content) == "" && choice.FinishReason == openai.FinishReasonLength {
- // Reasoning models spend max_completion_tokens on reasoning before any
+ content := resp.Content
+ if strings.TrimSpace(content) == "" && resp.FinishReason == "length" {
+ // Reasoning models spend the completion budget on reasoning before any
// visible output, so an exhausted budget yields an empty message rather
// than an API error. Returning "" here would be recorded as
// "no_extracted_content" and look identical to an image with no text.
return "", fmt.Errorf(
- "OpenAI VLM returned no content: completion truncated at %d tokens (finish_reason=length)",
+ "VLM returned no content: completion truncated at %d tokens (finish_reason=length)",
defaultMaxToks,
)
}
- logger.Infof(ctx, "[VLM] OpenAI response received, len=%d", len(content))
+ logger.Infof(ctx, "[VLM] response received, len=%d", len(content))
return content, nil
}
-// shapeReasoningVLMRequest adapts an OpenAI-compatible VLM request for
-// reasoning (o-series) and GPT-5 models, which reject `max_tokens` and every
-// non-default sampling parameter.
-//
-// This mirrors shapeOpenAIReasoning in internal/models/chat, which fixed the
-// same incompatibility on the chat path for issue #1283. The VLM path was
-// never wired to it, so image OCR and captioning failed for every one of these
-// models (issue #2537).
-//
-// Both quirks have to be handled together: migrating max_tokens alone still
-// fails, because the VLM default temperature (0.1) is itself rejected.
-func shapeReasoningVLMRequest(req *openai.ChatCompletionRequest) {
- if !provider.IsOpenAIReasoningOrGPT5Model(req.Model) {
- return
- }
- if req.MaxCompletionTokens == 0 && req.MaxTokens > 0 {
- req.MaxCompletionTokens = req.MaxTokens
- }
- req.MaxTokens = 0
- req.Temperature = 0
- req.TopP = 0
- req.FrequencyPenalty = 0
- req.PresencePenalty = 0
-}
-
func (v *RemoteAPIVLM) GetModelName() string { return v.modelName }
func (v *RemoteAPIVLM) GetModelID() string { return v.modelID }
diff --git a/internal/models/vlm/remote_api_reasoning_test.go b/internal/models/vlm/remote_api_reasoning_test.go
index c376abbd6..5c8136e5b 100644
--- a/internal/models/vlm/remote_api_reasoning_test.go
+++ b/internal/models/vlm/remote_api_reasoning_test.go
@@ -2,105 +2,15 @@ package vlm
import (
"encoding/json"
- "errors"
"math"
"net/http"
"net/http/httptest"
"strings"
"testing"
- openai "github.com/sashabaranov/go-openai"
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
)
-// TestShapeReasoningVLMRequest 验证 GPT-5 / o-series 的请求参数改写。
-// 见 issue #2537:这些模型必须使用 max_completion_tokens 替代 max_tokens,
-// 且不接受非默认的采样参数。
-func TestShapeReasoningVLMRequest(t *testing.T) {
- cases := []struct {
- name string
- model string
- maxTokens int
- maxCompletionTokens int
- temperature float32
- wantMaxTokens int
- wantMaxCompletionTokens int
- wantTemperature float32
- }{
- {
- name: "gpt-5 migrates max_tokens and drops temperature",
- model: "gpt-5", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 5000, wantTemperature: 0,
- },
- {
- name: "gpt-5-nano is shaped", // the model reported in issue #2537
- model: "gpt-5-nano", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 5000, wantTemperature: 0,
- },
- {
- name: "gpt-5 mixed case is shaped",
- model: "GPT-5.4-Mini", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 5000, wantTemperature: 0,
- },
- {
- name: "o1-mini is shaped",
- model: "o1-mini", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 5000, wantTemperature: 0,
- },
- {
- name: "o3 is shaped",
- model: "o3", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 5000, wantTemperature: 0,
- },
- {
- name: "o4-mini is shaped",
- model: "o4-mini", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 5000, wantTemperature: 0,
- },
- {
- name: "explicit max_completion_tokens is preserved",
- model: "gpt-5", maxTokens: 5000, maxCompletionTokens: 128, temperature: 0.1,
- wantMaxTokens: 0, wantMaxCompletionTokens: 128, wantTemperature: 0,
- },
- {
- name: "gpt-4o is left untouched",
- model: "gpt-4o", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 5000, wantMaxCompletionTokens: 0, wantTemperature: 0.1,
- },
- {
- name: "qwen-vl is left untouched",
- model: "qwen2.5-vl-7b-instruct", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 5000, wantMaxCompletionTokens: 0, wantTemperature: 0.1,
- },
- {
- name: "empty model is left untouched",
- model: "", maxTokens: 5000, temperature: 0.1,
- wantMaxTokens: 5000, wantMaxCompletionTokens: 0, wantTemperature: 0.1,
- },
- }
-
- for _, tc := range cases {
- t.Run(tc.name, func(t *testing.T) {
- req := openai.ChatCompletionRequest{
- Model: tc.model,
- MaxTokens: tc.maxTokens,
- MaxCompletionTokens: tc.maxCompletionTokens,
- Temperature: tc.temperature,
- }
- shapeReasoningVLMRequest(&req)
-
- if req.MaxTokens != tc.wantMaxTokens {
- t.Errorf("MaxTokens = %d, want %d", req.MaxTokens, tc.wantMaxTokens)
- }
- if req.MaxCompletionTokens != tc.wantMaxCompletionTokens {
- t.Errorf("MaxCompletionTokens = %d, want %d", req.MaxCompletionTokens, tc.wantMaxCompletionTokens)
- }
- if req.Temperature != tc.wantTemperature {
- t.Errorf("Temperature = %v, want %v", req.Temperature, tc.wantTemperature)
- }
- })
- }
-}
-
// newVLMChatTestServer emulates an OpenAI-compatible chat completions endpoint
// and records the last decoded request body.
func newVLMChatTestServer(t *testing.T, lastRequest *map[string]interface{}) *httptest.Server {
@@ -129,54 +39,54 @@ func newVLMChatTestServer(t *testing.T, lastRequest *map[string]interface{}) *ht
var testPNG = []byte("\x89PNG\r\n\x1a\n" + strings.Repeat("\x00", 16))
// TestRemoteAPIVLMSendsMaxCompletionTokensForReasoningModel is the regression
-// test for issue #2537: with a GPT-5 / o-series vision model, every OCR and
-// caption call failed with
-//
-// "this model is not supported MaxTokens, please use MaxCompletionTokens"
-//
-// The request was rejected client-side by go-openai's reasoning validator, so
-// it never reached the server and no image chunk was ever created.
+// test for issue #2537: GPT-5 / o-series vision models reject max_tokens and
+// every non-default sampling parameter. The catalog marks those families on
+// the OpenAI vendor, and the generic vendor carries the same family entries
+// so relays that forward to OpenAI behave the same way.
func TestRemoteAPIVLMSendsMaxCompletionTokensForReasoningModel(t *testing.T) {
withVLMSSRFWhitelist(t, "127.0.0.1")
- var lastRequest map[string]interface{}
- server := newVLMChatTestServer(t, &lastRequest)
- defer server.Close()
+ for _, provider := range []string{"openai", ""} {
+ var lastRequest map[string]interface{}
+ server := newVLMChatTestServer(t, &lastRequest)
- v, err := NewRemoteAPIVLM(&Config{
- BaseURL: server.URL,
- ModelName: "gpt-5-nano",
- APIKey: "sk-test",
- })
- if err != nil {
- t.Fatalf("NewRemoteAPIVLM: %v", err)
- }
-
- content, err := v.Predict(t.Context(), [][]byte{testPNG}, "extract the text")
- if err != nil {
- t.Fatalf("Predict: %v", err)
- }
- if content != "extracted text" {
- t.Errorf("content = %q, want %q", content, "extracted text")
- }
+ v, err := NewRemoteAPIVLM(&Config{
+ BaseURL: server.URL,
+ ModelName: "gpt-5-nano",
+ APIKey: "sk-test",
+ Provider: provider,
+ })
+ if err != nil {
+ t.Fatalf("NewRemoteAPIVLM: %v", err)
+ }
- if _, ok := lastRequest["max_tokens"]; ok {
- t.Errorf("request carries max_tokens, which reasoning models reject: %v", lastRequest["max_tokens"])
- }
- if got, ok := lastRequest["max_completion_tokens"]; !ok {
- t.Error("request is missing max_completion_tokens")
- } else if got != float64(defaultMaxToks) {
- t.Errorf("max_completion_tokens = %v, want %d", got, defaultMaxToks)
- }
- // Temperature 0.1 is itself rejected for these models, so migrating
- // max_tokens alone would not have been enough.
- if _, ok := lastRequest["temperature"]; ok {
- t.Errorf("request carries temperature, which reasoning models reject: %v", lastRequest["temperature"])
+ content, err := v.Predict(t.Context(), [][]byte{testPNG}, "extract the text")
+ if err != nil {
+ t.Fatalf("Predict (provider=%q): %v", provider, err)
+ }
+ if content != "extracted text" {
+ t.Errorf("content = %q, want %q", content, "extracted text")
+ }
+ if _, ok := lastRequest["max_tokens"]; ok {
+ t.Errorf("provider=%q: request carries max_tokens, which reasoning models reject: %v",
+ provider, lastRequest["max_tokens"])
+ }
+ if got, ok := lastRequest["max_completion_tokens"]; !ok {
+ t.Errorf("provider=%q: request is missing max_completion_tokens", provider)
+ } else if got != float64(defaultMaxToks) {
+ t.Errorf("max_completion_tokens = %v, want %d", got, defaultMaxToks)
+ }
+ if _, ok := lastRequest["temperature"]; ok {
+ t.Errorf("provider=%q: request carries temperature, which reasoning models reject: %v",
+ provider, lastRequest["temperature"])
+ }
+ server.Close()
}
}
// TestRemoteAPIVLMKeepsMaxTokensForNonReasoningModel guards against the fix
-// regressing ordinary vision models, which still expect max_tokens.
+// regressing ordinary vision models on an unknown (generic) endpoint, which
+// still expect max_tokens.
func TestRemoteAPIVLMKeepsMaxTokensForNonReasoningModel(t *testing.T) {
withVLMSSRFWhitelist(t, "127.0.0.1")
@@ -186,7 +96,7 @@ func TestRemoteAPIVLMKeepsMaxTokensForNonReasoningModel(t *testing.T) {
v, err := NewRemoteAPIVLM(&Config{
BaseURL: server.URL,
- ModelName: "gpt-4o",
+ ModelName: "qwen2.5-vl-7b-instruct",
APIKey: "sk-test",
})
if err != nil {
@@ -210,14 +120,21 @@ func TestRemoteAPIVLMKeepsMaxTokensForNonReasoningModel(t *testing.T) {
} else if f, isFloat := got.(float64); !isFloat || math.Abs(f-float64(defaultTemp)) > 1e-6 {
t.Errorf("temperature = %v, want %v", got, defaultTemp)
}
+ messages := lastRequest["messages"].([]interface{})
+ parts := messages[0].(map[string]interface{})["content"].([]interface{})
+ if len(parts) != 2 {
+ t.Fatalf("user content parts = %d, want text + image", len(parts))
+ }
+ image := parts[1].(map[string]interface{})["image_url"].(map[string]interface{})
+ if !strings.HasPrefix(image["url"].(string), "data:image/png;base64,") {
+ t.Errorf("image url = %q, want a PNG data URI", image["url"])
+ }
}
// TestRemoteAPIVLMReportsTruncatedCompletion covers the other way a reasoning
-// model yields nothing: max_completion_tokens also covers reasoning tokens, so
+// model yields nothing: the completion budget also covers reasoning tokens, so
// an exhausted budget returns an empty message with finish_reason=length
-// instead of an API error. Reporting that as an error keeps it out of the
-// "no_extracted_content" bucket, where issue #2537 notes the failure is
-// indistinguishable from an image that genuinely has no text.
+// instead of an API error.
func TestRemoteAPIVLMReportsTruncatedCompletion(t *testing.T) {
withVLMSSRFWhitelist(t, "127.0.0.1")
@@ -237,6 +154,7 @@ func TestRemoteAPIVLMReportsTruncatedCompletion(t *testing.T) {
BaseURL: server.URL,
ModelName: "gpt-5-nano",
APIKey: "sk-test",
+ Provider: "openai",
})
if err != nil {
t.Fatalf("NewRemoteAPIVLM: %v", err)
@@ -250,44 +168,3 @@ func TestRemoteAPIVLMReportsTruncatedCompletion(t *testing.T) {
t.Errorf("error = %q, want it to mention truncation", err.Error())
}
}
-
-// TestRemoteAPIVLMUnshapedReasoningRequestIsRejected pins the upstream
-// behavior this fix works around: without the shaping, go-openai rejects the
-// request before it leaves the process. It fails identically for max_tokens
-// and for a non-default temperature.
-func TestRemoteAPIVLMUnshapedReasoningRequestIsRejected(t *testing.T) {
- withVLMSSRFWhitelist(t, "127.0.0.1")
-
- var lastRequest map[string]interface{}
- server := newVLMChatTestServer(t, &lastRequest)
- defer server.Close()
-
- v, err := NewRemoteAPIVLM(&Config{
- BaseURL: server.URL,
- ModelName: "gpt-5-nano",
- APIKey: "sk-test",
- })
- if err != nil {
- t.Fatalf("NewRemoteAPIVLM: %v", err)
- }
-
- unshaped := openai.ChatCompletionRequest{
- Model: "gpt-5-nano",
- Messages: []openai.ChatCompletionMessage{{Role: openai.ChatMessageRoleUser, Content: "hi"}},
- MaxTokens: defaultMaxToks,
- }
- _, err = v.client.CreateChatCompletion(t.Context(), unshaped)
- if !errors.Is(err, openai.ErrReasoningModelMaxTokensDeprecated) {
- t.Errorf("max_tokens error = %v, want ErrReasoningModelMaxTokensDeprecated", err)
- }
-
- tempOnly := openai.ChatCompletionRequest{
- Model: "gpt-5-nano",
- Messages: []openai.ChatCompletionMessage{{Role: openai.ChatMessageRoleUser, Content: "hi"}},
- Temperature: defaultTemp,
- }
- _, err = v.client.CreateChatCompletion(t.Context(), tempOnly)
- if !errors.Is(err, openai.ErrReasoningModelLimitationsOther) {
- t.Errorf("temperature error = %v, want ErrReasoningModelLimitationsOther", err)
- }
-}
diff --git a/internal/models/vlm/spec_override_test.go b/internal/models/vlm/spec_override_test.go
new file mode 100644
index 000000000..650755b5e
--- /dev/null
+++ b/internal/models/vlm/spec_override_test.go
@@ -0,0 +1,62 @@
+package vlm
+
+import (
+ "context"
+ "testing"
+
+ _ "github.com/Tencent/WeKnora/internal/models/vendors"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// TestConfigFromModelCarriesSpecOverride pins the per-row catalog override on
+// the VLM path. dto.NewModelResponse computes a VLLM row's advertised
+// capabilities from Parameters.Spec, so dropping the override here made the UI
+// describe a model the runtime never built: /models reported the pinned
+// protocol and levels while the request went out with the vendor defaults.
+func TestConfigFromModelCarriesSpecOverride(t *testing.T) {
+ override := &types.ModelSpecOverride{MaxOutputTokens: 4096}
+ m := &types.Model{
+ ID: "vlm-1",
+ Name: "gpt-4o",
+ Source: types.ModelSourceRemote,
+ Parameters: types.ModelParameters{
+ BaseURL: "https://api.example.com/v1",
+ Provider: "openai",
+ Spec: override,
+ },
+ }
+ cfg := ConfigFromModel(m, "", "")
+ if cfg.Spec != override {
+ t.Fatalf("Spec not propagated: %+v", cfg.Spec)
+ }
+}
+
+// TestRemoteAPIVLMAppliesSpecOverride checks the override actually reaches the
+// wire: pinning max_output_tokens on the row must clamp the VLM's own default
+// completion budget.
+func TestRemoteAPIVLMAppliesSpecOverride(t *testing.T) {
+ withVLMSSRFWhitelist(t, "127.0.0.1")
+
+ var lastRequest map[string]interface{}
+ server := newVLMChatTestServer(t, &lastRequest)
+ defer server.Close()
+
+ v, err := NewRemoteAPIVLM(&Config{
+ BaseURL: server.URL,
+ ModelName: "some-unlisted-vision-model",
+ APIKey: "sk-test",
+ Provider: "openai",
+ Spec: &types.ModelSpecOverride{API: "openai-responses"},
+ })
+ if err != nil {
+ t.Fatalf("NewRemoteAPIVLM: %v", err)
+ }
+ // The override selects a different protocol, which is only observable
+ // through the request shape the server receives.
+ if _, err := v.Predict(context.Background(), [][]byte{testPNG}, "read this"); err != nil {
+ t.Fatalf("Predict: %v", err)
+ }
+ if _, ok := lastRequest["input"]; !ok {
+ t.Errorf("spec.api override ignored: expected an openai-responses body, got %v keys", lastRequest)
+ }
+}
diff --git a/internal/models/vlm/vlm.go b/internal/models/vlm/vlm.go
index b14cc9982..29c7489e5 100644
--- a/internal/models/vlm/vlm.go
+++ b/internal/models/vlm/vlm.go
@@ -32,7 +32,12 @@ type Config struct {
// MaxConcurrency caps concurrent background calls to this model; 0 falls
// back to the process-wide default (see limiter.GateN).
MaxConcurrency int
- Extra map[string]any
+ // Spec carries per-row catalog overrides (protocol, compat, levels). VLM
+ // calls now go through the chat factory, so the override has to travel
+ // with them — otherwise /models reports capabilities computed WITH the
+ // override while the actual request is built without it.
+ Spec *types.ModelSpecOverride
+ Extra map[string]any
// CustomHeaders 允许在调用远程 API 时附加自定义 HTTP 请求头(类似 OpenAI Python SDK 的 extra_headers)。
CustomHeaders map[string]string
AppID string
@@ -64,6 +69,7 @@ func ConfigFromModel(m *types.Model, appID, appSecret string) *Config {
InterfaceType: ifType,
Provider: m.Parameters.Provider,
MaxConcurrency: m.Parameters.MaxConcurrency,
+ Spec: m.Parameters.Spec,
Extra: stringMapToAnyMap(m.Parameters.ExtraConfig),
CustomHeaders: m.Parameters.CustomHeaders,
AppID: appID,
diff --git a/internal/router/routes_infra.go b/internal/router/routes_infra.go
index c2631ce00..e0aa1cd59 100644
--- a/internal/router/routes_infra.go
+++ b/internal/router/routes_infra.go
@@ -22,6 +22,8 @@ func RegisterModelRoutes(
{
// 获取模型厂商列表 — Viewer+
models.GET("/providers", g.Viewer(), handler.ListModelProviders)
+ // 解析模型的有效接入配置(协议 / 思考等级 / 上下文)— Viewer+
+ models.GET("/catalog/resolve", g.Viewer(), handler.ResolveModelCatalog)
// 创建模型 — Admin+
models.POST("", g.Admin(), handler.CreateModel)
// 获取模型列表 — Viewer+
diff --git a/internal/types/agent.go b/internal/types/agent.go
index 8ea94d7d3..e4e3b0351 100644
--- a/internal/types/agent.go
+++ b/internal/types/agent.go
@@ -131,6 +131,8 @@ type AgentConfig struct {
MCPAuthWaitTimeout int `json:"mcp_auth_wait_timeout,omitempty"`
// Whether to enable thinking mode (for models that support extended thinking)
Thinking *bool `json:"thinking"`
+ // ReasoningEffort is the graded thinking level; empty falls back to Thinking.
+ ReasoningEffort string `json:"reasoning_effort,omitempty"`
// Whether final answers include knowledge/web source citations. Nil defaults to true.
CitationEnabled *bool `json:"citation_enabled"`
// Whether to retrieve knowledge base only when explicitly mentioned with @ (default: false)
@@ -441,9 +443,14 @@ type AgentStep struct {
// model in this round. Persisted on AgentStep so cross-turn replay can put it
// back on the assistant message — required by MiMo / DeepSeek V3.2+ thinking
// mode, ignored by providers that don't recognize the field.
- ReasoningContent string `json:"reasoning_content,omitempty"`
- ToolCalls []ToolCall `json:"tool_calls"` // Tools called in this step (Act phase)
- Timestamp time.Time `json:"timestamp"` // When this step occurred
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ // ReasoningSignature / ReasoningMetadata are the provider artifacts that
+ // must accompany ReasoningContent on replay (Anthropic signatures,
+ // OpenAI Responses encrypted reasoning items).
+ ReasoningSignature string `json:"reasoning_signature,omitempty"`
+ ReasoningMetadata ProviderMetadata `json:"reasoning_metadata,omitempty"`
+ ToolCalls []ToolCall `json:"tool_calls"` // Tools called in this step (Act phase)
+ Timestamp time.Time `json:"timestamp"` // When this step occurred
// Truncated marks the round the completion-token cap cut off. It rides in
// the agent_steps JSON so a reloaded, shared or re-opened conversation can
// still show that the answer stops mid-sentence by design, rather than
diff --git a/internal/types/builtin_models_config.go b/internal/types/builtin_models_config.go
index 7f1d508e5..f68c8bd5f 100644
--- a/internal/types/builtin_models_config.go
+++ b/internal/types/builtin_models_config.go
@@ -134,6 +134,7 @@ func LoadBuiltinModelsConfig(ctx context.Context, db *gorm.DB, configDir string)
continue
}
m := e.toModel()
+ warnOnUnresolvableParameters(&m)
// A system-admin edit clears managed_by to claim the row as a runtime
// override. Preserve that explicit override on subsequent starts rather
@@ -254,6 +255,26 @@ var validBuiltinModelStatuses = map[ModelStatus]struct{}{
// Source is intentionally NOT validated against a fixed list because the
// provider matrix in internal/models/* keeps growing and a too-strict
// check here would force changes in two places per new provider.
+// ValidateModelParameters is set at startup to catalog.ValidateRow. It is a
+// hook rather than a direct call because internal/models/catalog imports this
+// package, so the dependency can only run in this direction. A nil hook (unit
+// tests, tools that never build the container) simply skips the check.
+var ValidateModelParameters func(modelName string, modelType ModelType, params *ModelParameters) error
+
+// warnOnUnresolvableParameters reports a YAML row whose provider, protocol or
+// compat override the catalog cannot resolve. It only warns: refusing to load
+// the row would take a running deployment's model offline on restart, whereas
+// the request itself still fails loudly at first use with the same message.
+func warnOnUnresolvableParameters(m *Model) {
+ if ValidateModelParameters == nil {
+ return
+ }
+ if err := ValidateModelParameters(m.Name, m.Type, &m.Parameters); err != nil {
+ log.Printf("[builtin-models] WARN: id=%s name=%s has parameters the catalog cannot resolve: %v; "+
+ "the row is loaded but every call will fail until it is corrected", m.ID, m.Name, err)
+ }
+}
+
func validateBuiltinModelEntry(e *BuiltinModelEntry, index int) error {
if e.ID == "" {
return errBuiltinModel("entry %d has empty id", index)
diff --git a/internal/types/chat.go b/internal/types/chat.go
index b1fccb964..b208f5a3b 100644
--- a/internal/types/chat.go
+++ b/internal/types/chat.go
@@ -186,6 +186,12 @@ type LLMToolCall struct {
// with the assistant tool call, without teaching core agent code vendor fields.
type ToolCallMetadata map[string]json.RawMessage
+// ProviderMetadata carries opaque provider state attached to an assistant
+// turn as a whole (OpenAI Responses reasoning items, OpenRouter
+// reasoning_details, ...). Keyed by protocol / vendor namespace so several
+// providers can coexist on one persisted message without collisions.
+type ProviderMetadata map[string]json.RawMessage
+
// FunctionCall represents the function details
type FunctionCall struct {
Name string `json:"name"`
@@ -197,10 +203,16 @@ type ChatResponse struct {
Content string `json:"content"`
// ReasoningContent 是支持思考链的模型(DeepSeek thinking、小米 MiMo、vLLM reasoning 等)
// 在本轮输出的推理内容。需要在后续多轮请求中原样回传给那些严格校验的供应商。
- ReasoningContent string `json:"reasoning_content,omitempty"`
- ToolCalls []LLMToolCall `json:"tool_calls,omitempty"`
- FinishReason string `json:"finish_reason,omitempty"`
- Usage TokenUsage `json:"usage"`
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ // ReasoningSignature and ReasoningMetadata are the provider-issued
+ // artifacts that must be replayed together with ReasoningContent on the
+ // next turn (Anthropic thinking signatures, Gemini thought signatures,
+ // OpenAI Responses encrypted reasoning items).
+ ReasoningSignature string `json:"reasoning_signature,omitempty"`
+ ReasoningMetadata ProviderMetadata `json:"reasoning_metadata,omitempty"`
+ ToolCalls []LLMToolCall `json:"tool_calls,omitempty"`
+ FinishReason string `json:"finish_reason,omitempty"`
+ Usage TokenUsage `json:"usage"`
// AnswerStreamed reports whether the user-facing answer text was already
// streamed live to the final-answer UI area during this round (i.e. the
diff --git a/internal/types/custom_agent.go b/internal/types/custom_agent.go
index 007a8fd2c..70b2566ce 100644
--- a/internal/types/custom_agent.go
+++ b/internal/types/custom_agent.go
@@ -153,6 +153,10 @@ type CustomAgentConfig struct {
MaxCompletionTokens int `yaml:"max_completion_tokens" json:"max_completion_tokens"`
// Whether to enable thinking mode (for models that support extended thinking)
Thinking *bool `yaml:"thinking" json:"thinking"`
+ // ReasoningEffort selects the thinking intensity (off | auto | minimal |
+ // low | medium | high | xhigh | max). Empty keeps the boolean Thinking
+ // semantics: true means "auto". See internal/models/api.ReasoningEffort.
+ ReasoningEffort string `yaml:"reasoning_effort,omitempty" json:"reasoning_effort,omitempty"`
// Whether final answers include knowledge/web source citations. Nil defaults to true
// so agents saved before this option was introduced keep their existing behavior.
CitationEnabled *bool `yaml:"citation_enabled" json:"citation_enabled"`
@@ -490,6 +494,35 @@ func (CustomAgent) TableName() string {
return "custom_agents"
}
+// reasoningEffortEnablesThinking mirrors api.ParseReasoningEffort followed by
+// api.ReasoningEffort.Enabled(), for the strings this package can see.
+// internal/types cannot import internal/models/api (api imports types), so the
+// whole vocabulary — api.AllReasoningEfforts plus the aliases
+// api.ParseReasoningEffort accepts — is restated here. Keep the two in sync:
+// the cases below are exactly that function's, in the same order, and like it
+// they neither trim nor lowercase, so a spelling it rejects is rejected here
+// too.
+//
+// known is false for anything outside that vocabulary. Reporting it separately
+// is what keeps a typo from meaning "thinking on": the runtime drops such a
+// level (api.SanitizeReasoningEffort) and falls back to the Thinking boolean,
+// so deriving true from it here would enable thinking at the provider default
+// for a value the write path answers with a 400.
+func reasoningEffortEnablesThinking(level string) (enabled, known bool) {
+ switch level {
+ case "off":
+ return false, true
+ case "auto", "minimal", "low", "medium", "high", "xhigh", "max":
+ return true, true
+ // Aliases the legacy boolean UI and provider docs use.
+ case "none", "false", "disabled":
+ return false, true
+ case "true", "enabled", "default", "on":
+ return true, true
+ }
+ return false, false
+}
+
// EnsureDefaults sets default values for the agent
func (a *CustomAgent) EnsureDefaults() {
if a == nil {
@@ -560,6 +593,21 @@ func (a *CustomAgent) EnsureDefaults() {
if a.Config.AgentMode == AgentModeSmartReasoning {
a.Config.MultiTurnEnabled = true
}
+ // Keep the legacy boolean consistent with the graded level. ReasoningEffort
+ // wins wherever both are read (api.Options.Reasoning), but everything that
+ // still reads only Thinking — the agent editor, the pipeline logs, the
+ // "thinking is off" warning in applyAgentOverridesToChatManage — would
+ // otherwise report an agent configured for `high` as thinking-off.
+ //
+ // A level outside that vocabulary is left alone rather than read as "on":
+ // it is dropped at call time, so the boolean derived here would be the
+ // only thing left deciding, and a typo would silently buy thinking at the
+ // provider default.
+ if a.Config.ReasoningEffort != "" {
+ if enabled, known := reasoningEffortEnablesThinking(a.Config.ReasoningEffort); known {
+ a.Config.Thinking = &enabled
+ }
+ }
// Pin thinking to an explicit false when unset so provider-specific wire
// formats (e.g. thinking_control=thinking_type) always receive a value.
if a.Config.Thinking == nil {
diff --git a/internal/types/custom_agent_reasoning_effort_test.go b/internal/types/custom_agent_reasoning_effort_test.go
new file mode 100644
index 000000000..24850609c
--- /dev/null
+++ b/internal/types/custom_agent_reasoning_effort_test.go
@@ -0,0 +1,104 @@
+package types
+
+import "testing"
+
+// TestEnsureDefaultsSyncsThinkingWithReasoningEffort pins the alias contract
+// documented on CustomAgentConfig.ReasoningEffort.
+//
+// EnsureDefaults used to pin Thinking to false whenever it was nil, without
+// looking at the graded level. An agent saved as {reasoning_effort: "high"}
+// therefore came back as {thinking: false, reasoning_effort: "high"}: the
+// request was still sent at "high" (api.Options.Reasoning prefers the graded
+// field) while the editor, the pipeline logs and the
+// "thinking is unset after EnsureDefaults" warning all reported it as off.
+func TestEnsureDefaultsSyncsThinkingWithReasoningEffort(t *testing.T) {
+ cases := []struct {
+ level string
+ want bool
+ }{
+ // Every rung of api.ReasoningLadder, plus the two switches.
+ {"minimal", true},
+ {"low", true},
+ {"medium", true},
+ {"high", true},
+ {"xhigh", true},
+ {"max", true},
+ {"auto", true},
+ {"off", false},
+ // Aliases the API layer accepts before canonicalizing.
+ {"none", false},
+ {"disabled", false},
+ {"false", false},
+ {"true", true},
+ {"enabled", true},
+ {"default", true},
+ {"on", true},
+ }
+ for _, tc := range cases {
+ agent := &CustomAgent{Config: CustomAgentConfig{ReasoningEffort: tc.level}}
+ agent.EnsureDefaults()
+ if agent.Config.Thinking == nil {
+ t.Errorf("reasoning_effort=%q left Thinking nil", tc.level)
+ continue
+ }
+ if *agent.Config.Thinking != tc.want {
+ t.Errorf("reasoning_effort=%q: Thinking = %v, want %v",
+ tc.level, *agent.Config.Thinking, tc.want)
+ }
+ }
+}
+
+// TestEnsureDefaultsKeepsLegacyThinkingWhenNoLevel keeps the pre-existing
+// behaviour for agents that only ever used the boolean.
+func TestEnsureDefaultsKeepsLegacyThinkingWhenNoLevel(t *testing.T) {
+ enabled := true
+ agent := &CustomAgent{Config: CustomAgentConfig{Thinking: &enabled}}
+ agent.EnsureDefaults()
+ if agent.Config.Thinking == nil || !*agent.Config.Thinking {
+ t.Fatal("an explicit thinking:true must survive EnsureDefaults")
+ }
+ if agent.Config.ReasoningEffort != "" {
+ t.Errorf("the graded field must stay unset, got %q", agent.Config.ReasoningEffort)
+ }
+
+ unset := &CustomAgent{}
+ unset.EnsureDefaults()
+ if unset.Config.Thinking == nil || *unset.Config.Thinking {
+ t.Fatal("an unset thinking must still be pinned to false")
+ }
+}
+
+// TestEnsureDefaults_UnknownReasoningEffortDoesNotEnableThinking closes the
+// fail-safe the write path and the runtime already implement.
+//
+// A level api.ParseReasoningEffort rejects is dropped at call time
+// (api.SanitizeReasoningEffort returns "", so api.Options.Reasoning falls back
+// to the boolean). If EnsureDefaults derived `Thinking = true` from that same
+// typo, the fallback would enable thinking at the provider default — the exact
+// outcome the 400 on the write path and the sanitiser exist to prevent. Builtin
+// YAML agents and rows written before the 400 existed reach EnsureDefaults
+// without ever passing the handler's normalisation, so this is the last guard.
+func TestEnsureDefaults_UnknownReasoningEffortDoesNotEnableThinking(t *testing.T) {
+ // Values api.ParseReasoningEffort rejects: a typo, a level that does not
+ // exist, and canonical spellings in the wrong case (it neither trims nor
+ // lowercases, so neither may this).
+ for _, level := range []string{"hgih", "ultra", "HIGH", " high ", "Off"} {
+ agent := &CustomAgent{Config: CustomAgentConfig{ReasoningEffort: level}}
+ agent.EnsureDefaults()
+ if agent.Config.Thinking == nil {
+ t.Errorf("reasoning_effort=%q left Thinking nil; it must still be pinned", level)
+ continue
+ }
+ if *agent.Config.Thinking {
+ t.Errorf("reasoning_effort=%q enabled thinking; an unparseable level is not a preference", level)
+ }
+ }
+
+ // An unknown level must not overwrite an explicit boolean either way.
+ enabled := true
+ kept := &CustomAgent{Config: CustomAgentConfig{ReasoningEffort: "hgih", Thinking: &enabled}}
+ kept.EnsureDefaults()
+ if kept.Config.Thinking == nil || !*kept.Config.Thinking {
+ t.Error("an unparseable level must leave an explicit thinking:true alone")
+ }
+}
diff --git a/internal/types/legacy_persisted_json_test.go b/internal/types/legacy_persisted_json_test.go
new file mode 100644
index 000000000..2ac297430
--- /dev/null
+++ b/internal/types/legacy_persisted_json_test.go
@@ -0,0 +1,181 @@
+package types
+
+// Round-trip guards for the JSON columns this refactor touches. Each literal
+// below is a blob the pre-catalog code actually wrote, so a failure means an
+// existing deployment loses data the first time the row is read and saved.
+
+import (
+ "encoding/json"
+ "reflect"
+ "strings"
+ "testing"
+)
+
+// legacyModelParametersJSON is a `models.parameters` value written by the old
+// code, carrying every field the pre-refactor ModelParameters struct had.
+const legacyModelParametersJSON = `{
+ "base_url": "https://api.deepseek.com/v1",
+ "api_key": "sk-stored",
+ "interface_type": "openai",
+ "embedding_parameters": {
+ "dimension": 1024,
+ "truncate_prompt_tokens": 2048,
+ "supports_dimension_override": true
+ },
+ "parameter_size": "7B",
+ "provider": "deepseek",
+ "extra_config": {
+ "thinking_control": "thinking_type",
+ "remote_model_name": "deepseek-reasoner",
+ "api_version": "2024-10-21",
+ "secret_key": "sk",
+ "region": "ap-guangzhou",
+ "instruction": "rank these",
+ "truncate_prompt_tokens": "4096"
+ },
+ "custom_headers": {"X-Corp-Route": "llm"},
+ "supports_vision": true,
+ "context_window": 128000,
+ "max_output_tokens": 8192,
+ "max_concurrency": 4,
+ "app_id": "app",
+ "app_secret": "encrypted"
+}`
+
+// TestLegacyModelParametersRoundTrip proves that reading an old row and
+// writing it back preserves every field. The refactor added
+// ModelParameters.Spec; had it renamed or dropped anything, the re-marshalled
+// blob would differ from the stored one.
+func TestLegacyModelParametersRoundTrip(t *testing.T) {
+ var params ModelParameters
+ if err := json.Unmarshal([]byte(legacyModelParametersJSON), &params); err != nil {
+ t.Fatalf("an old parameters blob no longer unmarshals: %v", err)
+ }
+
+ // Strict decode: every key the old code wrote must still map to a field.
+ dec := json.NewDecoder(strings.NewReader(legacyModelParametersJSON))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&ModelParameters{}); err != nil {
+ t.Fatalf("an old parameters key has no field on the new struct: %v", err)
+ }
+
+ if params.Spec != nil {
+ t.Errorf("Spec must default to nil on a row that predates it, got %+v", params.Spec)
+ }
+
+ rewritten, err := json.Marshal(params)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ var before, after map[string]any
+ if err := json.Unmarshal([]byte(legacyModelParametersJSON), &before); err != nil {
+ t.Fatal(err)
+ }
+ if err := json.Unmarshal(rewritten, &after); err != nil {
+ t.Fatal(err)
+ }
+ for key, want := range before {
+ got, ok := after[key]
+ if !ok {
+ t.Errorf("key %q was dropped when the row was rewritten", key)
+ continue
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("key %q changed on rewrite: stored %v, rewritten %v", key, want, got)
+ }
+ }
+ if _, ok := after["spec"]; ok {
+ t.Error("spec must be omitted when unset so untouched rows are not rewritten")
+ }
+}
+
+// TestLegacyCustomAgentConfigThinking pins the legacy boolean for agent rows
+// saved before reasoning_effort existed: thinking true, false and absent must
+// each behave exactly as they did.
+func TestLegacyCustomAgentConfigThinking(t *testing.T) {
+ cases := []struct {
+ name string
+ blob string
+ want *bool
+ }{
+ {"thinking true", `{"thinking": true}`, boolPtr(true)},
+ {"thinking false", `{"thinking": false}`, boolPtr(false)},
+ // Absent has always been pinned to false by EnsureDefaults.
+ {"thinking absent", `{"max_completion_tokens": 4096}`, boolPtr(false)},
+ {"thinking null", `{"thinking": null}`, boolPtr(false)},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ agent := &CustomAgent{}
+ if err := json.Unmarshal([]byte(tc.blob), &agent.Config); err != nil {
+ t.Fatalf("an old agent config no longer unmarshals: %v", err)
+ }
+ if agent.Config.ReasoningEffort != "" {
+ t.Fatalf("an old row must leave reasoning_effort empty, got %q",
+ agent.Config.ReasoningEffort)
+ }
+ agent.EnsureDefaults()
+ if agent.Config.Thinking == nil {
+ t.Fatal("EnsureDefaults left Thinking nil")
+ }
+ if *agent.Config.Thinking != *tc.want {
+ t.Fatalf("Thinking = %v, old code produced %v",
+ *agent.Config.Thinking, *tc.want)
+ }
+ })
+ }
+}
+
+// TestLegacyAgentStepRoundTrip covers the persisted agent history. Old steps
+// carry reasoning_content but never a signature or provider metadata, and the
+// protocol layers only replay a thinking block when both the content and a
+// protocol-tagged signature are present.
+func TestLegacyAgentStepRoundTrip(t *testing.T) {
+ const legacyStep = `{
+ "thought": "I should search the knowledge base",
+ "reasoning_content": "the user asked about pricing",
+ "tool_calls": [],
+ "timestamp": "2025-01-02T03:04:05Z"
+ }`
+ var step AgentStep
+ if err := json.Unmarshal([]byte(legacyStep), &step); err != nil {
+ t.Fatalf("an old agent step no longer unmarshals: %v", err)
+ }
+ if step.ReasoningContent != "the user asked about pricing" {
+ t.Fatalf("reasoning_content was lost: %q", step.ReasoningContent)
+ }
+ if step.ReasoningSignature != "" {
+ t.Fatalf("an old step must carry no signature, got %q", step.ReasoningSignature)
+ }
+ if step.ReasoningMetadata != nil {
+ t.Fatalf("an old step must carry no provider metadata, got %v", step.ReasoningMetadata)
+ }
+ rewritten, err := json.Marshal(step)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ var after map[string]any
+ if err := json.Unmarshal(rewritten, &after); err != nil {
+ t.Fatal(err)
+ }
+ for _, key := range []string{"reasoning_signature", "reasoning_metadata"} {
+ if _, ok := after[key]; ok {
+ t.Errorf("%q must be omitted on a step that has none", key)
+ }
+ }
+}
+
+// TestLegacySummaryConfigThinking covers the session-level summary config,
+// which gained the same reasoning_effort alias.
+func TestLegacySummaryConfigThinking(t *testing.T) {
+ var cfg SummaryConfig
+ if err := json.Unmarshal([]byte(`{"thinking": true, "max_tokens": 2048}`), &cfg); err != nil {
+ t.Fatalf("an old summary config no longer unmarshals: %v", err)
+ }
+ if cfg.Thinking == nil || !*cfg.Thinking {
+ t.Fatal("thinking:true was lost")
+ }
+ if cfg.ReasoningEffort != "" {
+ t.Fatalf("an old row must leave reasoning_effort empty, got %q", cfg.ReasoningEffort)
+ }
+}
diff --git a/internal/types/model.go b/internal/types/model.go
index 80f88ffcd..c5ed9ab27 100644
--- a/internal/types/model.go
+++ b/internal/types/model.go
@@ -153,6 +153,37 @@ type ModelParameters struct {
// WeKnoraCloud 厂商专用凭证
AppID string `yaml:"app_id,omitempty" json:"app_id,omitempty"`
AppSecret string `yaml:"app_secret,omitempty" json:"app_secret,omitempty"` // AES-256 加密存储,实际承载上游 API Key
+ // Spec overrides the catalog entry for this row: protocol, capability
+ // flags and the flat protocol compat object. Everything omitted is
+ // inherited from the vendor catalog (see internal/models/catalog).
+ Spec *ModelSpecOverride `yaml:"spec,omitempty" json:"spec,omitempty"`
+}
+
+// ModelSpecOverride is the per-row slice of a catalog model entry that an
+// operator may pin from the UI or YAML. Compat is the flat protocol-specific
+// object documented in internal/models/catalog/compat.go.
+type ModelSpecOverride struct {
+ API string `yaml:"api,omitempty" json:"api,omitempty"`
+ Reasoning *bool `yaml:"reasoning,omitempty" json:"reasoning,omitempty"`
+ Input []string `yaml:"input,omitempty" json:"input,omitempty"`
+ ContextWindow int `yaml:"context_window,omitempty" json:"context_window,omitempty"`
+ MaxOutputTokens int `yaml:"max_output_tokens,omitempty" json:"max_output_tokens,omitempty"`
+ ThinkingLevels map[string]*string `yaml:"thinking_levels,omitempty" json:"thinking_levels,omitempty"`
+ // Compat is a plain object so it round-trips through both JSON (API,
+ // database column) and YAML (builtin_models.yaml).
+ Compat map[string]any `yaml:"compat,omitempty" json:"compat,omitempty"`
+}
+
+// CompatJSON renders Compat for the catalog decoder; nil when unset.
+func (o *ModelSpecOverride) CompatJSON() json.RawMessage {
+ if o == nil || len(o.Compat) == 0 {
+ return nil
+ }
+ data, err := json.Marshal(o.Compat)
+ if err != nil {
+ return nil
+ }
+ return data
}
// Per-response redaction for Model now lives in dto.NewModelResponse. The
diff --git a/internal/types/session.go b/internal/types/session.go
index e022ad7fd..1de44a147 100644
--- a/internal/types/session.go
+++ b/internal/types/session.go
@@ -46,6 +46,8 @@ type SummaryConfig struct {
MaxCompletionTokens int `json:"max_completion_tokens"`
// Thinking - whether to enable thinking mode
Thinking *bool `json:"thinking"`
+ // ReasoningEffort is the graded thinking level; empty falls back to Thinking.
+ ReasoningEffort string `json:"reasoning_effort,omitempty"`
}
// ContextCompressionStrategy represents the strategy for context compression
diff --git a/scripts/model_catalog_diff.py b/scripts/model_catalog_diff.py
new file mode 100755
index 000000000..a3c657c67
--- /dev/null
+++ b/scripts/model_catalog_diff.py
@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Compare the built-in vendor catalogs against models.dev and print a diff.
+
+Development-time helper, never run at runtime: it reports numeric facts
+(context window, max output, cost, new/retired ids) so a maintainer can update
+internal/models/vendors/<id>/models.json by hand. Behavioural facts (compat,
+thinking format) are intentionally out of scope — models.dev does not carry
+them and they must come from vendor documentation.
+
+Usage:
+ scripts/model_catalog_diff.py # fetch https://models.dev/api.json
+ scripts/model_catalog_diff.py --api api.json # use a downloaded copy
+ scripts/model_catalog_diff.py --vendor deepseek
+ scripts/model_catalog_diff.py --exit-code # non-zero when anything differs
+
+Findings are advisory: `+` is a model upstream has and we do not, `~` is a
+numeric difference, `?` is an entry upstream does not list (often correct —
+vendor-specific aliases and China-only ids are missing from models.dev).
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+VENDORS_DIR = ROOT / "internal" / "models" / "vendors"
+
+# WeKnora vendor id -> models.dev provider id.
+PROVIDER_MAP = {
+ "openai": "openai",
+ "anthropic": "anthropic",
+ "gemini": "google",
+ "deepseek": "deepseek",
+ "zhipu": "zhipuai",
+ "aliyun": "alibaba-cn",
+ "volcengine": "volcengine",
+ "moonshot": "moonshotai-cn",
+ "minimax": "minimax-cn",
+ "mimo": "xiaomi",
+ "siliconflow": "siliconflow-cn",
+ "modelscope": "modelscope",
+ "qiniu": "qiniu-ai",
+ "longcat": "longcat",
+ "novita": "novita-ai",
+ "nvidia": "nvidia",
+ "openrouter": "openrouter",
+ "requesty": "requesty",
+}
+
+
+MODELS_DEV_URL = "https://models.dev/api.json"
+
+
+def load_api(path):
+ """Load the models.dev catalog from a file, or fetch it once.
+
+ models.dev rejects the default urllib user agent, so send a real one.
+ When the network is unavailable (CI, offline dev box), download the file
+ by hand and pass --api, or set MODELS_DEV_API to its path.
+ """
+ path = path or os.environ.get("MODELS_DEV_API")
+ if path:
+ return json.loads(Path(path).read_text())
+ request = urllib.request.Request(
+ MODELS_DEV_URL,
+ headers={"User-Agent": "WeKnora-model-catalog-diff/1.0 (+https://github.com/Tencent/WeKnora)"},
+ )
+ try:
+ with urllib.request.urlopen(request, timeout=60) as resp:
+ return json.load(resp)
+ except urllib.error.URLError as err:
+ raise SystemExit(
+ f"failed to fetch {MODELS_DEV_URL}: {err}\n"
+ "Download it manually and re-run with --api <file>, or set MODELS_DEV_API."
+ ) from err
+
+
+def load_catalog(vendor):
+ file = VENDORS_DIR / vendor / "models.json"
+ if not file.exists():
+ return {}
+ data = json.loads(file.read_text())
+ return {m["id"]: m for m in data.get("models", []) if m.get("id")}
+
+
+def compare(vendor, upstream, ours):
+ lines = []
+ up_models = upstream.get("models", {})
+ for mid, spec in sorted(up_models.items()):
+ mods = spec.get("modalities", {})
+ if "text" not in mods.get("output", ["text"]):
+ continue # image / audio generation, out of scope
+ entry = ours.get(mid)
+ limit = spec.get("limit", {})
+ cost = spec.get("cost", {})
+ if entry is None:
+ lines.append(
+ f" + {mid} (new upstream: ctx={limit.get('context')} out={limit.get('output')} "
+ f"reasoning={spec.get('reasoning')} released={spec.get('release_date')})"
+ )
+ continue
+ diffs = []
+ if limit.get("context") and entry.get("context_window") != limit.get("context"):
+ diffs.append(f"context_window {entry.get('context_window')} -> {limit.get('context')}")
+ if limit.get("output") and entry.get("max_output_tokens") != limit.get("output"):
+ diffs.append(f"max_output_tokens {entry.get('max_output_tokens')} -> {limit.get('output')}")
+ if bool(entry.get("reasoning")) != bool(spec.get("reasoning")):
+ diffs.append(f"reasoning {entry.get('reasoning')} -> {spec.get('reasoning')}")
+ ours_cost = entry.get("cost") or {}
+ for key, up_key in (("input", "input"), ("output", "output"), ("cache_read", "cache_read")):
+ if cost.get(up_key) is not None and ours_cost.get(key) != cost.get(up_key):
+ diffs.append(f"cost.{key} {ours_cost.get(key)} -> {cost.get(up_key)}")
+ if diffs:
+ lines.append(f" ~ {mid}: " + "; ".join(diffs))
+ for mid in sorted(ours):
+ if mid not in up_models:
+ lines.append(f" ? {mid} (not in models.dev; keep if the vendor still documents it)")
+ return lines
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--api", help="path to a downloaded models.dev api.json")
+ parser.add_argument("--vendor", help="limit to one WeKnora vendor id")
+ parser.add_argument(
+ "--exit-code", action="store_true",
+ help="exit 1 when there are findings (for a scheduled job); default always exits 0",
+ )
+ args = parser.parse_args()
+
+ api = load_api(args.api)
+ vendors = [args.vendor] if args.vendor else sorted(PROVIDER_MAP)
+ exit_code = 0
+ for vendor in vendors:
+ upstream_id = PROVIDER_MAP.get(vendor)
+ if not upstream_id:
+ print(f"== {vendor}: no models.dev mapping", file=sys.stderr)
+ continue
+ upstream = api.get(upstream_id)
+ if upstream is None:
+ print(f"== {vendor}: models.dev provider {upstream_id!r} missing", file=sys.stderr)
+ continue
+ lines = compare(vendor, upstream, load_catalog(vendor))
+ print(f"== {vendor} (models.dev: {upstream_id}) — {len(lines)} finding(s)")
+ for line in lines:
+ print(line)
+ if lines:
+ exit_code = 1
+ return exit_code if args.exit_code else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/website-docs/03-features/06-models.md b/website-docs/03-features/06-models.md
index 20bf42b08..818449a9e 100644
--- a/website-docs/03-features/06-models.md
+++ b/website-docs/03-features/06-models.md
@@ -76,7 +76,8 @@ const (
| `embedding_parameters.supports_dimension_override` | bool | false | 是否支持请求级维度覆盖(`dimensions` 参数) |
| `parameter_size` | string | 空 | Ollama 模型参数规模(如 "7B"),后端维护、前端不可改 |
| `provider` | string | 空(按 BaseURL 自动检测) | 厂商标识 |
-| `extra_config` | map[string]string | nil | 厂商专属配置(如 Azure 的 `api_version`) |
+| `extra_config` | map[string]string | nil | 厂商专属配置(由厂商定义的 `extraFields` 驱动,如 Azure 的 `api_version`);保留键 `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 请求头(类似 OpenAI SDK `extra_headers`;`Authorization`、`api-key` 等保留头在运行期被忽略) |
| `supports_vision` | bool | false | Chat 模型是否接受图片多模态输入 |
| `context_window` | int | 0(回落到 200000) | 对话/VLM 上下文窗口(token)。智能体压缩历史按此上限工作;留空使用默认 200K。应填写服务实际支持的窗口大小,过高会导致压缩无法及时触发 |
@@ -169,84 +170,103 @@ builtin_models:
## 模型调用与实现参考
-### Provider 抽象
+### 厂商目录(catalog)
-`internal/models/provider/provider.go` 定义了多厂商适配的统一注册表:
+模型接入分三层,每层只做一件事:
-```go
-type Provider interface {
- // Info 返回服务商的元数据
- Info() ProviderInfo
- // ValidateConfig 验证服务商的配置
- ValidateConfig(config *Config) error
-}
+| 层 | 位置 | 职责 |
+|----|------|------|
+| 协议层 | `internal/models/api/<protocol>` | 一个 wire 协议一个包:`openaicompletions`、`openairesponses`、`anthropicmessages`、`googlegenai`。各自持有请求/响应结构、SSE 解析与 usage 解析,不含任何厂商名 |
+| 厂商层 | `internal/models/vendors/<id>/` | 一个厂商一个目录:`vendor.go`(注册 `catalog.Vendor`)、`models.json`(模型目录)、`icon.svg`(品牌图标,`go:embed` 进二进制) |
+| 目录层 | `internal/models/catalog` | 合并厂商定义、模型条目、部署叠加与单行覆盖,`Resolve` 得出「这个模型到底怎么发请求」 |
+
+`catalog.Resolve(Ref{Provider, Model, BaseURL, Extra, Override})` 的合并顺序从低到高:
+
+1. 协议默认值(`DefaultOpenAICompletions()` 等);
+2. 厂商级 `Compat`(`vendor.go` 里声明,例如 DeepSeek 的 `max_tokens_field: max_tokens`);
+3. `models.json` 里匹配到的条目(精确 id → `aliases` → `match` 通配,最长字面前缀优先);
+4. 部署叠加 `config/models.json`(见下);
+5. 模型行上的 `parameters.spec`(UI「高级」里的协议覆盖与 compat JSON);
+6. `extra_config.api` 强制协议、`extra_config.thinking_control` 旧版思考编码、`extra_config.remote_model_name`。
+
+厂商事实全部忠实厂商文档,每个 `vendor.go` 的包注释列出依据与文档链接,`models.json` 的 `source` 字段记录来源。对应的出站 JSON 由各协议包的 golden 测试钉死(如 `openaicompletions/golden_test.go`)。
+
+#### 关键 compat 字段(OpenAI Chat Completions 方言)
+
+| 字段 | 含义 | 典型厂商 |
+|------|------|----------|
+| `max_tokens_field` | `max_tokens` 或 `max_completion_tokens`,二者只发一个 | DeepSeek / 智谱 / 硅基流动 用 `max_tokens`;OpenAI / 火山 用 `max_completion_tokens` |
+| `thinking_format` | `openai`(`reasoning_effort`)、`thinking-type`(`thinking.type`)、`enable-thinking`(`enable_thinking` + `thinking_budget`)、`chat-template-kwargs`(vLLM)、`openrouter`(`reasoning`)、`none` | 见各厂商 |
+| `supports_reasoning_effort` | 是否额外发 `reasoning_effort` | DeepSeek、智谱、火山、OpenAI |
+| `thinking_always_send` / `thinking_disable_on_non_stream` | 每次请求都钉开关;非流式强制关 | 百炼混合思考模型 |
+| `supports_temperature` / `fixed_temperature` | 推理模型拒绝采样参数;Moonshot v1 固定 1 | GPT-5 / o 系列、Kimi K2.5+ |
+| `tool_choice_modes` | 允许的 `tool_choice` 取值 | DeepSeek 思考模式不支持 `required` |
+| `replay_reasoning_content` | 多轮回传 `reasoning_content` | DeepSeek、MiMo、Kimi |
+| `prompt_cache_key` / `cache_control_format` | OpenAI 缓存路由 / Anthropic 式断点 | OpenAI、OpenRouter、百炼 |
+
+思考强度在内部统一为 `off / auto / minimal / low / medium / high / xhigh / max`,每个模型的 `thinking_levels` 把统一等级映射到厂商取值(`null` 表示不支持,`"off": null` 表示无法关闭思考,如 DeepSeek Reasoner、QwQ、Kimi K3),不支持的等级按 PI 的规则就近钳位。
+
+#### 内置厂商
+
+`GET /api/v1/models/providers?model_type=chat` 返回全部厂商定义(图标 data URI、默认地址、额外字段、内置模型与思考能力),前端完全据此动态渲染,没有本地厂商表。目前内置 27 个厂商:`generic`、`weknoracloud`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`siliconflow`、`deepseek`、`minimax`、`moonshot`、`mimo`、`modelscope`、`qianfan`、`qiniu`、`longcat`、`lkeap`、`openai`、`azure_openai`、`anthropic`、`gemini`、`openrouter`、`litellm`、`requesty`、`jina`、`nvidia`、`novita`、`gpustack`;Ollama 走 `source=local` 独立路径。
+
+协议选择:Anthropic 走 Messages 协议;Gemini 默认走原生 `generateContent`(`base_url` 指向 `/v1beta/openai` 则保持 OpenAI 兼容);OpenAI 在 `api.openai.com` 上走 Responses 协议,中转/代理保持 Chat Completions;任何厂商 `base_url` 以 `/anthropic` 结尾时自动切到 Messages 协议(MiniMax、智谱、Kimi 的 Anthropic 兼容口)。`extra_config.api` 可强制指定。
+
+#### 新增厂商
+
+代码侧新增一个厂商只需要一个目录,四个文件,不用改协议层和前端:
+
+1. 复制一个相近的目录到 `internal/models/vendors/<id>/`,改 `vendor.go` 的 id、名称(`Names` 放中文名)、`Description`、默认地址、`Auth`、`Compat`、`ThinkingLevels`、`URLPatterns`,并在包注释里逐条写清依据的厂商文档链接;无法从文档确认的字段标 `unverified:`,不要臆测;
+2. 按厂商文档填 `models.json`(`id`、`reasoning`、`input`、`context_window`、`max_output_tokens`、`cost`、`thinking_levels`、`compat`、`source`),同一家族用 `match` 通配(如 `"match": "gpt-5*"`),精确 id 优先于通配;
+3. 放一个 `icon.svg`(LobeHub icons 或手绘,6 KB 以内),会 `go:embed` 进二进制并以 data URI 下发给前端;
+4. 在 `vendors/all.go` 加一行 blank import;
+5. 需要特殊 URL、协议选择或签名时实现 `Endpoint` / `PreferAPI` / `Signer` 钩子(参考 `azure_openai`、`openai`、`weknoracloud`)。
+
+然后跑一条命令,目录层的守护测试会自动覆盖新厂商,无需为它单独写用例:
+
+```bash
+make model-catalog-check
```
-每个厂商在自己的文件(如 `provider/openai.go`、`provider/aliyun.go`)中通过 `init()` 调用 `Register()` 注册自身,`ProviderInfo` 携带 `DisplayName`、`Description`、按模型类型区分的 `DefaultURLs`、支持的 `ModelTypes`、`RequiresAuth` 以及可选的 `ExtraFields`(例如 Azure OpenAI 声明了 `api_version` 额外字段,默认 `2024-10-21`)。
-
-#### 支持的厂商清单
-
-`AllProviders()`(`provider/provider.go`)返回的完整列表(共 27 个,每个厂商在自己的文件里 `init()` 注册)。表格最后一行的 Ollama 不在其中,它走 `source=local` 这条独立路径,列在这里只为方便对照:
-
-| Provider 标识 | 名称 | 说明 |
-|---------------|------|------|
-| `generic` | Generic | 任意 OpenAI 兼容 / 自定义部署(默认兜底) |
-| `weknoracloud` | WeKnoraCloud | WeKnora 云服务(硬编码 `https://weknora.weixin.qq.com`,使用 AppID/AppSecret 凭证) |
-| `aliyun` | 阿里云 DashScope | |
-| `zhipu` | 智谱 AI(GLM 系列) | |
-| `volcengine` | 火山引擎 Ark | |
-| `hunyuan` | 腾讯混元 | |
-| `siliconflow` | 硅基流动 | |
-| `deepseek` | DeepSeek | |
-| `minimax` | MiniMax | |
-| `moonshot` | 月之暗面 Moonshot (Kimi) | |
-| `modelscope` | 魔搭 ModelScope | |
-| `qianfan` | 百度千帆 | |
-| `qiniu` | 七牛云 | |
-| `openai` | OpenAI | 五种模型类型全支持 |
-| `anthropic` | Anthropic Claude | 独立 Messages 协议实现 |
-| `gemini` | Google Gemini | Embedding 走专用 API |
-| `openrouter` | OpenRouter | |
-| `litellm` | LiteLLM(自托管 OpenAI 兼容代理) | 默认 URL 为占位符,loopback 需加入 `SSRF_WHITELIST` |
-| `requesty` | Requesty | |
-| `jina` | Jina AI | Embedding 与 Rerank |
-| `mimo` | 小米 MiMo | |
-| `longcat` | 美团 LongCat AI | |
-| `lkeap` | 腾讯云 LKEAP(知识引擎原子能力) | 提供专用 Rerank 实现 |
-| `gpustack` | GPUStack(私有化部署) | |
-| `nvidia` | NVIDIA | 专用 Embedding / Rerank 实现 |
-| `novita` | Novita AI | |
-| `azure_openai` | Azure OpenAI | 额外字段 `api_version` |
-| `ollama`(source=`local`) | Ollama 本地模型 | 非 Provider 注册表成员,由 `ModelSourceLocal` 路由 |
-
-当模型未显式指定 provider 时,`DetectProvider(baseURL)` 会按 BaseURL 域名特征自动识别(如 `dashscope.aliyuncs.com -> aliyun`、`api.anthropic.com -> anthropic`),识别失败回落为 `generic`。
-
-#### 协议路由
-
-`internal/models/chat/chat.go` 的 `NewRemoteChat`:
+它包含三层校验:`vendors` 的注册与图标检查;`catalog` 的解析与叠加;`parity` 包的**不变量**(每个模型条目的字段合法性、compat 键名可解码、上下文与最大输出自洽)和**逐模型出站请求检查**(每个对话模型在思考开 / 关两种情况下,只能出现一个输出上限字段;不支持采样参数的模型不得带 temperature;始终思考的模型不得收到关闭开关等)。新加的厂商和模型一旦违反这些规则,测试直接失败。
-```go
-func NewRemoteChat(config *ChatConfig) (Chat, error) {
- providerName := provider.ProviderName(config.Provider)
- if providerName == "" {
- providerName = provider.DetectProvider(config.BaseURL)
- }
- if providerName == provider.ProviderAnthropic {
- return NewAnthropicChat(config) // 独立 Messages 协议
- }
- return NewRemoteAPIChat(config) // 统一 OpenAI 兼容协议 + providerAdapter
-}
+前端不需要任何改动:厂商下拉、图标、额外字段、内置模型列表都由 `GET /api/v1/models/providers` 动态渲染。
+
+写入侧也有一道闸:`catalog.ValidateRow` 会在创建 / 更新模型(REST)和加载 `config/builtin_models.yaml`(启动)时解析这行配置,未知协议、拼错的 compat 键、非法的思考档位在写入时就被拒绝(YAML 行只打 WARN 不阻塞启动,避免一次重启把线上模型下线)。
+
+#### 厂商更新了模型怎么办
+
+分两种情况:
+
+**只是新增 / 调整模型元数据**(新模型 id、上下文窗口、价格)。先拿差异报告,再人工核对厂商文档改 `models.json`:
+
+```bash
+make model-catalog-diff # 全部厂商
+make model-catalog-diff VENDOR=deepseek # 只看一家
```
-- **Ollama**(`source=local`):`chat/ollama.go`、`embedding/ollama.go`、`vlm/ollama.go` 通过 `internal/models/utils/ollama` 的 `OllamaService` 直连本机 Ollama。
-- **Anthropic**:`chat/anthropic.go` 实现 Messages 协议。
-- **其余远程厂商**:统一走 `chat/remote_api.go` 的 OpenAI 兼容 Chat Completions 实现,厂商差异(thinking 编码、参数兼容等)由构造时解析的 `providerAdapter` 处理。
-- **Embedding** 有更多专用实现:阿里云多模态(`tongyi-embedding-vision-*` 走 DashScope 专用端点,纯文本模型自动改写为 `/compatible-mode/v1` OpenAI 兼容端点)、Volcengine 多模态、Jina、Azure OpenAI、NVIDIA、Gemini、Zhipu、WeKnoraCloud,其余为 OpenAI 兼容(`embedding/openai.go`)。
-- **Rerank** 专用实现:Aliyun、Zhipu、Jina、NVIDIA、WeKnoraCloud、LKEAP、Volcengine,默认 `NewOpenAIReranker`(通用 `/rerank` 风格接口)。两个厂商有额外适配:
- - **LKEAP**:腾讯云 `RunRerank` 限制单次最多 60 篇文档、Query 与 Docs 合计不超过 2000 字符。`lkeapRerankBatches` 按这两个上限自动切批并回填全局下标,调用方不用感知分批;单篇文档自身就超限时直接报错并指出下标。
- - **Volcengine**:候选集超过接口单次文档上限时自动切成多批**并发**打分再合并(并发上限见 `volcengineRerankMaxConcurrency`),不会静默截断候选。
- - **NVIDIA**:接口返回的是原始 logit 而非 [0,1] 概率。`normalizeNvidiaLogit` 用数值稳定的 sigmoid 归一化(负数走 `e^x/(1+e^x)` 分支避免溢出),否则 `RerankThreshold` 这类阈值配置在该厂商下完全失效。
-- **ASR**:所有厂商统一使用 OpenAI 兼容 `/v1/audio/transcriptions`(`asr/asr.go`:`NewASR` 直接 `NewOpenAIASR`)。
+报告对比 [models.dev](https://models.dev/api.json) 的公开元数据:`+` 是上游有而我们没有的模型,`~` 是数值差异,`?` 是上游没收录的条目(国内厂商和别名经常如此,不代表错)。脚本只读不写,也从不在运行时调用——**字段名、思考格式这类行为事实不会被自动同步**,必须以厂商文档为准手工维护,这是刻意的取舍:models.dev 不携带这些信息,自动同步会让线上请求悄悄改变行为。
+
+**厂商改了接口行为**(换了输出上限字段、新增 effort 取值、思考开关格式变化)。改 `vendor.go` 或对应模型条目的 `compat`,并同步更新包注释里的文档链接;`internal/models/api/openaicompletions/golden_test.go` 之类的快照测试会把出站 JSON 钉死,改动必须先改测试预期,评审时一眼能看到行为变化。
+
+**紧急情况不必等发版**:用下面的部署叠加在配置里先改,验证无误后再补回代码。
+
+#### 部署叠加 `config/models.json`
+
+不改代码也能加厂商、改地址、补模型:复制 `config/models.json.example` 到 `config/models.json`(或用 `MODELS_CONFIG` 指定路径),结构与 PI 的 `~/.pi/agent/models.json` 一致:`providers` 按厂商 id 键入,已知 id 打补丁,新 id 声明新厂商;支持 `base_url` / `base_urls`、`api_key`(`${ENV}` 插值)、`headers`、`compat`、`thinking_levels`、`models`(按 id upsert:已存在的 id 只覆盖你写出来的字段,没写的 `reasoning`、`thinking_levels`、`compat`、`input` 保持原样;新 id 则整条新建)、`model_overrides`、`icon`(内联 `<svg …>` 字符串,或相对于叠加文件所在目录的 `.svg` 路径——不接受绝对路径、不能越出该目录、必须是 256 KB 以内的 SVG,因为图标会以 data URI 下发给所有能打开模型页的人)。未知键在启动时报错。运行时不会自动从外部拉取模型数据:字段名、思考格式这类行为事实必须由人维护。
+
+#### 升级到目录化实现的注意事项
+
+老库里的模型行**不需要任何迁移**:`parameters` 列只增加了可选的 `spec` 字段,旧的 26 个 `provider` 取值全部仍然注册,`extra_config` 的历史键(`thinking_control` 的每个取值、`remote_model_name`、`api_version`、`secret_key`、`region`、`instruction`、`truncate_prompt_tokens`)语义不变,目录里已没有的模型 id(自定义微调、已退役型号)照常解析并保留思考开关。这些由 `internal/models/catalog/legacy_rows_test.go` 与 `internal/types/legacy_persisted_json_test.go` 钉住。
+
+但有四处**既有模型行的运行时行为会变**,升级时需要知会使用者:
+
+1. **`extra_config.api` 变成保留键**。它现在是协议选择器(`openai-completions` / `openai-responses` / `anthropic-messages` / `google-generative-ai` / `ollama`),取值非法会在创建、更新模型时返回 400。WeKnora 自身从未写过这个键,只有手工调 REST 或写 YAML 造出来的行会受影响——升级前删掉或改成合法取值。这里刻意选择报错而不是忽略:静默忽略会让人以为切换生效了。
+2. **Azure OpenAI 未填 `api_version` 的行改走 `/openai/v1` GA 数据面**,不再是 `/openai/deployments/{model}/...?api-version=2024-10-21`。旧默认版本根本不支持它同时声称的 `reasoning_effort` 与 `max_completion_tokens`,属于自相矛盾。要保留旧路径,在额外字段里显式填一个 `api_version`。
+3. **`api.openai.com` 的一方流量改走 Responses 协议**(`PreferAPI` 只对官方域生效)。各类中转 / 网关仍走 Chat Completions,`parity` 包里有断言钉住这一点。
+4. **7 家厂商的输出上限字段按文档纠正**:hunyuan、modelscope、qiniu、requesty、longcat、novita 由 `max_completion_tokens` 改回 `max_tokens`,moonshot 反向改为 `max_completion_tokens`。每一处在 `internal/models/parity/parity_test.go` 里都记了变更理由与厂商文档。aliyun 保持 `max_completion_tokens` 不变:兼容模式两个字段都收,但 DashScope 的参数表已经把 `max_tokens` 标为即将废弃并指名了继任者。
+
+另外 Azure OpenAI 不再声明支持 ASR(ASR 客户端只会构造标准 OpenAI 客户端,根本无法带上 Azure 的 `api-key` 头和部署路径,这类行此前就调不通)。
### 模型调用链
@@ -257,10 +277,11 @@ flowchart TD
S --> CF["ConfigFromModel<br/>(chat / embedding / rerank / vlm / asr)"]
CF --> F{"工厂函数<br/>NewChat / NewEmbedder / ..."}
F -->|"source = local"| OL["OllamaService<br/>(internal/models/utils/ollama)"]
- F -->|"source = remote"| PD{"provider 路由<br/>(显式 provider 或 DetectProvider)"}
- PD -->|"anthropic"| AN["AnthropicChat<br/>(Messages 协议)"]
- PD -->|"weknoracloud"| WC["WeKnoraCloud 实现<br/>(AppID + AppSecret 签名)"]
- PD -->|"其他厂商"| OA["RemoteAPIChat / OpenAIEmbedder ...<br/>(OpenAI 兼容 + providerAdapter)"]
+ F -->|"source = remote"| PD{"catalog.Resolve<br/>(厂商 + 模型 + 叠加 + 行覆盖)"}
+ PD -->|"anthropic-messages"| AN["anthropicmessages.Client"]
+ PD -->|"openai-responses"| RS["openairesponses.Client"]
+ PD -->|"google-generative-ai"| GG["googlegenai.Client"]
+ PD -->|"openai-completions"| OA["openaicompletions.Client<br/>(compat 驱动的方言)"]
F --> W1["debug 包装<br/>(LLM_DEBUG 日志)"]
W1 --> W2["Langfuse 包装<br/>(链路追踪)"]
W2 --> W3["concurrency 包装<br/>(limiter.GateNamedN 按模型限流)"]
diff --git a/website-docs/04-api/02-api-model-system.md b/website-docs/04-api/02-api-model-system.md
index f0e5eda41..fc7d4e1dc 100644
--- a/website-docs/04-api/02-api-model-system.md
+++ b/website-docs/04-api/02-api-model-system.md
@@ -10,14 +10,30 @@ API key:`manage_models` 或 full-access。
### GET /api/v1/models/providers
-用途:模型厂商列表。权限:Viewer+。查询参数:`model_type`(可选:`chat/embedding/rerank/vllm/asr`)。Handler: `internal/handler/model.go`
+用途:厂商目录(前端据此动态渲染厂商下拉、图标、额外字段与模型选择)。权限:Viewer+。查询参数:`model_type`(可选:`chat/embedding/rerank/vllm/asr`)。Handler: `internal/handler/model_catalog.go`
-响应:200 `{"success":true,"data":[{value,label,description,defaultUrls,modelTypes}]}`
+响应: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` | 按模型类型的默认地址与支持的类型 |
+| `extraFields` | 厂商额外配置字段定义(`key,label,type,required,default,options,model_types,secret`),值存入 `parameters.extra_config` |
+| `models` | 内置模型目录(`id,name,type,api,reasoning,input,context_window,max_output_tokens,dimension,thinking_levels,cost`) |
+| `thinking` | 厂商级思考编码摘要(`format`、`levels`) |
```bash
curl "$BASE/api/v1/models/providers?model_type=chat" -H "Authorization: Bearer $TOKEN"
```
+### GET /api/v1/models/catalog/resolve
+
+用途:按厂商、模型名、`base_url` 与 `extra_config` 解析有效接入配置(协议、思考等级、上下文),供模型编辑器实时展示。权限:Viewer+。查询参数:`provider`(必填)、`model`、`base_url`、`model_type`、`api`、`thinking_control`、`remote_model_name`。
+
+响应:200 `{"success":true,"data":{provider,api,base_url,remote_model,cataloged,model,capabilities}}`,其中 `capabilities` 为 `{provider,api,cataloged,reasoning,thinking_levels,thinking_format,input,context_window,max_output_tokens,max_tokens_field}`。同一结构也随对话/视觉模型的 `ModelResponse.capabilities` 返回。
+
### POST /api/v1/models
用途:创建模型。权限:Admin+。