WeKnora/website-docs/03-features/06-models.md

350 lines
34 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 模型管理
在「设置 → 模型」添加对话、向量、重排、视觉和语音模型,再由知识库或智能体按需选用。本地 Ollama 和远程模型可以组合使用,例如由本地模型生成向量、远程模型生成回答。
<Screenshot
src="/screenshots/settings-models.png"
caption="模型设置:按类型管理已添加的模型"
hint="展示模型列表(名称、类型、来源、默认标记)与「添加模型」表单,含连通性测试结果。" />
添加模型时应检查连接配置和索引兼容性:
- **更换向量模型需要重建索引**。模型决定向量的语义空间与维度,新旧向量不能直接混用;
- **保存前测试连接**。确认服务地址、凭据和模型名称可用后,再将模型用于知识库或智能体。
模型类型、配置字段和使用状态可按以下说明查询。
## 选择模型类型
| 类型 | 用途 |
| --- | --- |
| 对话模型 | 生成问答、摘要和智能推理内容 |
| 向量模型 | 将文档与问题转换为向量,支持语义检索 |
| 重排模型 | 对召回片段重新排序 |
| 视觉模型 | 识别文档或对话中的图片 |
| 语音模型 | 将音频转写为文本 |
## 添加与验证连接
在模型设置中选择类型和提供商,填写实际模型名称、服务地址与凭据,测试通过后保存。向量模型需要匹配索引维度;对话与视觉模型的上下文窗口应使用服务实际支持的大小,以便正确触发历史压缩。
修改连接地址时,测试可复用已保存凭据。模型调试器会实际发起请求,显示耗时、脱敏请求和响应结果,可用于检查向量维度、重排得分或流式输出。
## 查看引用与调整配置
知识库和智能体保存对模型的引用。删除模型前需检查依赖详情;内置模型由 YAML 配置管理,应在配置文件中维护。调用量和缓存使用情况可结合[可观测性与审计](16-observability.md)查看。
## 配置与调用参考
### 模型类型与用途
模型类型定义在 `internal/types/model.go`:
```go
const (
ModelTypeEmbedding ModelType = "Embedding" // Embedding model
ModelTypeRerank ModelType = "Rerank" // Rerank model
ModelTypeKnowledgeQA ModelType = "KnowledgeQA" // KnowledgeQA model
ModelTypeVLLM ModelType = "VLLM" // VLLM model
ModelTypeASR ModelType = "ASR" // ASR model
)
```
| 类型 | 前端标识 | 客户端包 | 接口 | 用途 |
|------|---------|---------|------|------|
| `KnowledgeQA` | `chat` | `internal/models/chat` | `Chat` / `ChatStream`(支持 Tools、Thinking、多模态消息) | 知识问答、Agent 推理、摘要 / 问题生成 / 图谱抽取等一切 LLM 调用 |
| `Embedding` | `embedding` | `internal/models/embedding` | `Embed` / `BatchEmbed`(含 `GetDimensions`) | 文本向量化,供向量检索索引与查询 |
| `Rerank` | `rerank` | `internal/models/rerank` | `Rerank(query, documents)` 返回 `RankResult` | 检索结果精排 |
| `VLLM` | `vllm` | `internal/models/vlm` | `Predict(imgBytes, prompt)` | 视觉语言模型(VLM),文档图片理解 / 多模态解析 |
| `ASR` | `asr` | `internal/models/asr` | `Transcribe(audioBytes, fileName)` 返回文本;模型提供时附带分段时间戳(如 OpenAI `whisper-1`) | 音频转写(自动语音识别) |
前后端类型映射见 `internal/handler/model.go` 的 `modelTypeToFrontend()`(`KnowledgeQA -> chat` 等)。
模型来源(`ModelSource`)核心取值为两个:`local`(本地 Ollama 拉起)与 `remote`(远程 API);其余历史值(`aliyun`、`zhipu`、`openai` 等)为兼容保留,路由行为等同 `remote` + 对应 provider。
### 模型配置字段
模型实体 `types.Model` 的 `Parameters`(`internal/types/model.go` 的 `ModelParameters`):
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `base_url` | string | 空(可用 Provider 的 `DefaultURLs`) | 模型 API 地址,创建/更新时经过 SSRF 校验(`ValidateURLForSSRF`) |
| `api_key` | string | 空 | API 密钥,**AES-256-GCM 加密落库**(`ModelParameters.Value/Scan`),仅通过 `PUT /models/:id/credentials` 子资源修改 |
| `interface_type` | string | 空(VLM:local 默认 `ollama`,remote 默认 `openai`) | 接口协议类型 |
| `embedding_parameters.dimension` | int | 0 | 向量维度 |
| `embedding_parameters.truncate_prompt_tokens` | int | 0 | 服务端截断 token 数。这是 vLLM 的扩展参数,只发给 `generic`、`gpustack`(为 0 时沿用历史值 511);托管厂商的文档里没有它,一律不发 |
| `embedding_parameters.supports_dimension_override` | bool | false | 是否在请求里指定向量维度。字段名由厂商决定(OpenAI 系 `dimensions`、Gemini `outputDimensionality`、百炼多模态 `parameters.dimension`);厂商文档里没有该参数的模型(NVIDIA NIM、混元、Novita、ada-002 等)即使勾选也不发 |
| `parameter_size` | string | 空 | Ollama 模型参数规模(如 "7B"),后端维护、前端不可改 |
| `provider` | string | 空(按 BaseURL 自动检测) | 厂商标识 |
| `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。应填写服务实际支持的窗口大小,过高会导致压缩无法及时触发 |
| `max_concurrency` | int | 0(回落到全局 `model.max_concurrency`) | 该模型后台任务并发上限(仅 chat/vlm/embedding 生效) |
| `app_id` / `app_secret` | string | 空 | WeKnoraCloud 专用凭证,`app_secret` AES 加密存储 |
模型级字段还包括 `name`(运行期实际调用的模型名)、`display_name`、`type`、`source`、`is_default`(同一 `(tenant_id, type)` 桶内唯一默认)、`is_builtin`、`managed_by`、`status`(`active` / `downloading` / `download_failed`)。
#### 管理 API(`internal/router/router.go`)
| 方法 & 路径 | 说明 |
|-------------|------|
| `GET /models/providers` | 按 `model_type` 查询支持的厂商列表(`ListModelProviders`) |
| `POST /models` / `GET /models` / `GET /models/:id` / `PUT /models/:id` / `DELETE /models/:id` | 模型 CRUD |
| `PUT /models/:id/credentials`、`DELETE /models/:id/credentials/:field` | 凭证子资源;`PUT /models/:id` 请求体中的 `api_key` 会被强制忽略并告警 |
| `POST /models/:id/debug` | 模型调试(见下文) |
| `GET /models/weknoracloud/status` | WeKnoraCloud 凭证状态 |
### 模型健康检查 / 连通性测试
两套机制,均在服务端持有凭证、不回传明文密钥:
1. **测试连接**(`internal/handler/initialization.go`,供模型创建/编辑表单的 "Test connection" 按钮):
- `POST /initialization/remote/check` — Chat 模型(`CheckRemoteModel` / `checkChatModelConnection`)
- `POST /initialization/embedding/test` — Embedding(`TestEmbeddingModel`)
- `POST /initialization/rerank/check` — Rerank(`CheckRerankModel`)
- `POST /initialization/asr/check` — ASR(`CheckASRModel`)
- `POST /initialization/multimodal/test` — VLM 多模态解析(`TestMultimodalFunction`)
请求体 `ModelTestRequest` 可携带 `modelId`:`fillSecretsFromStoredModel` 会把请求中缺失的 `APIKey` / `AppSecret` 从已存模型(解密后)补齐,实现"改 BaseURL 用旧密钥一键验证",前端无需也无法拿到明文密钥。`buildTestModel` 把请求转换为**不落库**的临时 `*types.Model`,与生产路径共享同一套 `ConfigFromModel` 映射。
2. **模型调试器**(`POST /models/:id/debug`,`ModelHandler.DebugModel`):对已保存模型按类型发起真实调用并返回完整归一化响应——Chat 走流式并聚合 `stream_events` / thinking 观测项;Embedding 返回向量与维度;Rerank 返回打分结果;VLM / ASR 接受上传文件。响应含 `elapsed_ms`、脱敏后的请求预览(`redactedDebugConfig` 隐去 secret/token/api_key 类字段)与 `observations`。
### 内置模型机制
`internal/types/builtin_models_config.go` 实现了声明式内置模型:启动时读取 `config/builtin_models.yaml`(或 `BUILTIN_MODELS_CONFIG` 指定路径,模板见 `config/builtin_models.yaml.example`),把每个条目 UPSERT 到 `models` 表,`is_builtin=true`、`managed_by="yaml"`、默认 `tenant_id=10000`(`DefaultBuiltinModelTenantID`),对所有租户可见。
关键行为(`LoadBuiltinModelsConfig`):
- 任意字符串字段支持 `${ENV_NAME}` 环境变量插值;未设置的变量保留字面量以便暴露配置错误。
- 每次启动按 `id` UPSERT,并把 `deleted_at` 强制重置为 NULL(文件中重新出现的条目会复活)。
- **漂移清理**:`managed_by='yaml'` 但 id 已不在文件中的行被软删除——从 YAML 删除条目即是下线内置模型的正规方式。
- 管理员在运行时接管某行(`managed_by` 置空)后,YAML 加载器会跳过该行("preserving runtime override")。
- `is_default: true` 条目会先清掉同 `(tenant_id, type)` 桶内其他默认,保持与 API 路径一致的唯一默认不变式。
- 校验规则:id 非空且 ≤64 字符(`ModelIDMaxLen`)、type 必须是 `KnowledgeQA | Embedding | Rerank | VLLM | ASR`、status 合法或为空;YAML 解析失败时中止对账(不执行漂移清理)。
YAML 示例(摘自 `builtin_models.yaml.example`):
```yaml
builtin_models:
- id: builtin-llm-default
type: KnowledgeQA
source: remote
is_default: true
name: ${LLM_MODEL_NAME}
parameters:
base_url: ${LLM_BASE_URL}
api_key: ${LLM_API_KEY}
provider: ${LLM_PROVIDER}
```
#### 本地模型下载(Ollama)
本地模型的生命周期由 `internal/models/utils/ollama/ollama.go` 的 `OllamaService` 管理(`IsModelAvailable` / `PullModel` / `EnsureModelAvailable` / `ListModelsDetailed` / `DeleteModel` 等),HTTP 入口在 `internal/handler/initialization.go`:
| 路径 | 说明 |
|------|------|
| `GET /initialization/ollama/status` | Ollama 服务可用性 |
| `GET /initialization/ollama/models` | 列出本地已有模型 |
| `POST /initialization/ollama/models/check` | 批量检查模型是否已下载 |
| `POST /initialization/ollama/models/download` | 异步下载(`downloadModelAsync` + `pullModelWithProgress`,写入模型 `status=downloading`) |
| `GET /initialization/ollama/download/progress/:taskId`、`GET /initialization/ollama/download/tasks` | 下载进度 / 任务列表 |
> 注意:`cmd/download/duckdb/duckdb.go` 与模型无关——它在构建镜像时预下载 DuckDB 的 `spatial`、`excel` 扩展,供数据分析工具使用。模型权重下载只发生在 Ollama 路径。
### 模型用量统计
- **Token 用量**:`types.TokenUsage`(`internal/types/chat.go`)记录 `prompt_tokens / completion_tokens / total_tokens` 及 prompt cache 细分(`cache_read_tokens / cache_write_tokens / cache_miss_tokens / cache_status`)。每个 Chat 实现通过 `internal/models/chat/usage.go` 的 `logUsage` 输出统一的结构化日志行:
```go
logger.Infof(ctx,
"[LLM Usage] model=%s, purpose=%s, prompt_prefix=%s, prompt_tokens=%d, completion_tokens=%d, ...",
...)
```
其中 `purpose` 来自 `types.WithLLMCallMetadata`(如 `document_summary`、`entity_extraction`),可按用途聚合。
- **链路追踪**:启用 Langfuse 时,每类模型都有 `langfuse_wrapper.go` 装饰器把调用(含 usage)上报为 trace/span。
- **流式响应**:usage 随最后的 `StreamResponse` 事件返回(模型调试器会将其聚合进 `usage` 字段)。
- **并发水位**:如上节所述,`GET /system/admin/runtime/queues` 暴露每模型实时 `active / waiting / limit`。
## 模型调用与实现参考
### 厂商目录(catalog)
模型接入分三层,每层只做一件事:
| 层 | 位置 | 职责 |
|----|------|------|
| 协议层 | `internal/models/api/<protocol>` | 一个 wire 协议一个包。对话:`openaicompletions`、`openairesponses`、`anthropicmessages`、`googlegenai`;重排:`cohererank`、`dashscoperank`、`nimrerank`;向量:`openaiembeddings`、`dashscopeembeddings`、`arkembeddings`、`googleembeddings`;语音:`openaitranscriptions`。各自持有请求/响应结构与解析,不含任何厂商名 |
| 厂商层 | `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` | 每次请求都钉开关;非流式强制关 | 百炼混合思考模型 |
| `thinking_budget_excludes_effort` | 厂商禁止 `thinking_budget` 与 `reasoning_effort` 同发,发了报错;置真时按档位优先、丢掉预算 | 百炼 qwen3.8 系列 |
| `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` 可强制指定对话协议,只对 chat / VLM 行生效;embedding 行的协议覆盖写在 `spec.compat` 的 `"api"` 里,取值是向量协议(`openai-embeddings`、`dashscope-embeddings`、`ark-embeddings`、`google-embeddings`)。
目录条目按模型类型查找:embedding 行只匹配 embedding 条目,不会被同名前缀的对话通配(如百炼的 `qwen3*`、OpenAI 的 `gpt-5*`)套上对话的 compat。目录里还没有的新 id、带日期的快照照常按厂商默认解析。
#### 新增厂商
代码侧新增一个厂商只需要一个目录,四个文件,不用改协议层和前端:
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
```
它包含三层校验:`vendors` 的注册与图标检查;`catalog` 的解析与叠加;`parity` 包的**不变量**(每个模型条目的字段合法性、compat 键名可解码、上下文与最大输出自洽)和**逐模型出站请求检查**(每个对话模型在思考开 / 关两种情况下,只能出现一个输出上限字段;不支持采样参数的模型不得带 temperature;始终思考的模型不得收到关闭开关等)。新加的厂商和模型一旦违反这些规则,测试直接失败。
前端不需要任何改动:厂商下拉、图标、额外字段、内置模型列表都由 `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 # 只看一家
```
报告对比 [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` 标为即将废弃并指名了继任者。
Rerank 行(逐厂商的出站请求由 `internal/models/rerank/wire_test.go` 钉住,含火山与 LKEAP 两个签名 SDK 客户端):
1. **OpenAI 不再出现在 rerank 的厂商列表里**。OpenAI 的 API 没有 rerank 接口,在这里建的行只会 404;架在 OpenAI 风格地址后面、自带 rerank 的中转请建成 generic 行。已有的行照常解析。
2. **火山 rerank 每次最多 200 条**(文档:datas「数组长度不超过 200」),旧实现按自己定的 50 条切分。
3. **火山 rerank 的默认指令改为控制台原文** `Whether the document answers the query or matches the content retrieval intent`,文档要求「如需对齐控制台效果,请使用相同指令」;旧默认值把 Document / Query 写成了大写。已在额外字段里保存了指令的行不受影响。
Embedding 行也有几处按厂商文档纠正的行为变化(逐厂商的出站请求由 `internal/models/embedding/wire_test.go` 钉住):
1. **托管厂商不再收到 `truncate_prompt_tokens`**。此前所有 OpenAI 兼容厂商都被塞了一个 511,它只是 vLLM 的扩展参数;`generic`、`gpustack` 照旧发送。
2. **NVIDIA NIM 的检索查询改用 `input_type: query`**。文档侧照旧是 `passage`,已有索引不受影响;这一标记在一次检索重构里丢失过,现在由 `types.WithEmbedQuery` 在三处查询入口设置。超长输入改为 `truncate: END` 截断而不是报错;`dimensions` 不再发送(NIM 没有这个参数)。目录里已被 NVIDIA 标记下线的 `nv-embed-v1`、`llama-3.2-nemoretriever-300m-embed-v1`、`baai/bge-m3` 已移除。
3. **阿里云按模型分流**:文本模型走 `/compatible-mode/v1/embeddings`,`qwen3-vl-embedding`、`qwen2.5-vl-embedding`、`tongyi-embedding-vision*`、`multimodal-embedding*` 走原生多模态接口。`base_url` 只填主机、国际站或业务空间域名时保留该主机,不再被替换成北京默认地址。
4. **火山方舟的文本向量接口已归档下线**,当前只有多模态接口。沿用老的 `doubao-embedding-text*` / `doubao-embedding-large-text*` 的行改发到它们归档文档里的 `/api/v3/embeddings`;此前它们被发往多模态接口。
5. **Gemini 的缩维放进 `embedContentConfig.outputDimensionality`**。请求顶层的同名字段已被文档标为 deprecated;旧实现发的是顶层 `output_dimensionality`。
6. **SiliconFlow 每次最多 32 条、百炼 `text-embedding-v1/v2` 最多 25 条**,超出时自动拆批;v1/v2 固定 1536 维,不发 `dimensions`。
7. **OpenAI 兼容回复里没有 `index` 时按顺序取**(和旧实现一致);有 `index` 就按它放回,重复或缺位报错。
8. **Jina 的 `task`、Gemini 的 `taskType`、OpenRouter 的 `input_type`、火山的 `instructions`、百炼原生接口的 `text_type` / `instruct` 都不发**。它们会改变文档侧向量,开启后同一个知识库里新旧向量不在同一空间;需要按行显式开启的设计另见 Tencent/WeKnora#1401。
ASR 行的变化(逐厂商的出站表单由 `internal/models/asr/wire_test.go` 钉住):
1. **不再一律发 `response_format=verbose_json`**。OpenAI 文档写明 gpt-4o-transcribe / gpt-4o-mini-transcribe「only supported format is json」,旧实现发给它们必然 400;GPUStack 的音频后端 vox-box 在 FunASR 模型(SenseVoice、Paraformer)上对 `verbose_json` 返回裸字符串,旧实现解不开。现在只有文档写明支持的模型声明它(OpenAI `whisper-1`),其余走默认 json,Langfuse 里的音频时长因此只在返回分段的模型上有。需要分段的自建行可以在 `spec.compat` 里写 `{"response_format": "verbose_json"}`。
2. **按厂商文档的上限和格式在上传前拒绝**:文件大小(OpenAI / 智谱 / OpenRouter 25 MB、Requesty 32 MB、SiliconFlow / MiniMax 50 MB;阿里与小米按整段 `data:` URI 计 10 MB),以及文档给出封闭格式清单的厂商(智谱、小米只收 wav/mp3,OpenAI、Requesty、MiniMax 各有列表)。
3. **回复里没有 `text` 字段即报错**,不再当成「未检测到语音」入库;静音音频返回的是空字符串 `text`,照常处理。
4. ASR 行现在带上 provider 走目录解析,go-openai 依赖随之移除。provider 没有声明 ASR 的行:显式填了该厂商的直接报错;没填、靠 URL 识别到的,按 OpenAI 形状打到它的 URL(与旧实现一致),不走该厂商的 Endpoint 钩子。
5. **支持 ASR 的厂商按文档补齐**。OpenAI 形状(multipart `file` + `model`):openai、siliconflow、gpustack、generic、智谱(`glm-asr-2512`,单文件 ≤30 秒)、MiniMax(`asr-1.0`,路径是 `/v1/speech_to_text`)、OpenRouter、Requesty、LiteLLM。经 chat completions 的 `input_audio`(base64 data URI,编码后 ≤10 MB):阿里云 `qwen3-asr-flash`、小米 `mimo-v2.5-asr`。
6. **知识库的「音频语言提示」终于发出去了**(此前从未接线)。位置按厂商文档:OpenAI / Requesty / OpenRouter / GPUStack / generic 是 `language` 表单字段,MiniMax 是 `language` 请求头,阿里与小米是 `asr_options.language`;智谱、SiliconFlow、LiteLLM 文档没有这个参数,不发。填 `auto` 等同留空。
7. **音频时长从回包里读**:MiniMax 的 `duration`、OpenAI 系与阿里的 `usage.seconds`,Langfuse 不再只靠 `verbose_json` 的分段。
阿里只有 `qwen3-asr-flash` 能直接带音频调用;其余 ASR 模型名由一条兜底条目拒绝并说明原因。
查过但没有接的:火山豆包语音(独立域名与密钥,当前文档的请求体只收音频 URL)、千帆(`vop_asr` 挂在应用实例下要 `app_id`;短语音接口 ≤60 秒且只收 pcm/wav/amr/m4a)、七牛(只收音频 URL)、Novita(GLM-ASR 自有接口,≤30 秒)、腾讯云 ASR(与混元不是同一套鉴权)、NVIDIA 托管 Riva(gRPC)、Gemini(没有专用转写接口,只能让对话模型听音频)、Azure(见下)。阿里 Paraformer / Fun-ASR / `*-filetrans` 是异步任务,同样要公网 URL。
Azure OpenAI 仍不声明 ASR:音频转写只出现在 v1 **preview** 参考里(`/openai/v1/audio/transcriptions?api-version=preview`),v1 GA 参考没有;未填 `api_version` 的行会被钩子发到不带版本的 v1 路径,能否调通没有核实。
### 模型调用链
```mermaid
flowchart TD
H["Handler 层<br/>(model.go / session / agent)"] --> S["modelService.GetChatModel /<br/>GetEmbeddingModel / GetRerankModel /<br/>GetVLMModel / GetASRModel"]
S --> R["ModelRepository<br/>(models 表, APIKey AES-GCM 解密)"]
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{"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 按模型限流)"]
W3 --> P["模型厂商 API"]
```
工厂函数在真实客户端外层依次套上三个装饰器(见 `chat.NewChat` / `embedding.NewEmbedder` / `vlm.NewVLM`):
```go
c, err = wrapChatDebug(c, err)
c, err = wrapChatLangfuse(c, err)
// Outermost: hold the per-model concurrency slot only around the real
// provider round-trip, so the wait is excluded from debug/langfuse timing.
return wrapChatConcurrency(c, config.MaxConcurrency, err)
```
### 并发与限流(limiter)
`internal/models/limiter` 提供**按模型 ID 的分布式后台并发闸门**,核心设计(`limiter.go` 包注释):共享的稀缺资源是模型厂商的请求预算,因此在模型客户端层(唯一能看到所有任务类型的位置)限流,而不是在 asynq 队列层。
- **Redis 后端**(`NewRedisLimiter`):自愈式分布式信号量。每个持有的槽位是 ZSET 成员(唯一 token),score 为租约到期时间;`acquireScript` Lua 脚本原子地清理过期租约、计数、在限额内准入。租约 TTL 30s,持有方每 TTL/3 心跳续租(同时续 ZSET key 自身的 TTL),进程崩溃后租约自然过期回收。**任何后端错误都 fail-open**——限流器故障绝不能阻断模型流量。
- **Local 后端**(`NewLocalLimiter`):Lite 模式(单进程无 Redis)下的进程内计数信号量。
- **仅后台任务被限流**:`GateNamedN`(`governor.go`)只在 `types.IsBackgroundTask(ctx)` 为真(asynq worker:摘要、问题生成、图谱抽取、多模态增强等)时排队;交互式用户请求永不被闸门阻塞。
- 限额优先取模型自身 `parameters.max_concurrency`,为 0 时回落进程级默认 `model.max_concurrency`(可经系统设置在运行时通过 `SetGlobalLimit` 热更新)。
- 运行时观测:`GET /system/admin/runtime/queues`(`internal/handler/system.go`)返回 `limiter.RuntimeStats()` 的每模型 `active / waiting / limit`(Redis 后端 active 为集群级,waiting 为进程本地)。
### rerank_server_demo.py 的用途
仓库根目录的 `rerank_server_demo.py` 是一个**自托管 Rerank 服务的最小参考实现**:FastAPI + HuggingFace `AutoModelForSequenceClassification`,暴露 `POST /rerank`,请求体 `{query, documents}`,返回 `{"results": [{index, document: {text}, score}]}`。
示例服务返回 `score` 字段,可用于验证客户端兼容性。`RankResult.UnmarshalJSON` 优先读取 `relevance_score`,缺失时读取 `score`;`DocumentInfo.UnmarshalJSON` 同时接受字符串和 `{text}` 对象。遵循此协议的私有重排服务可通过 `generic` provider 接入。