34 KiB
模型管理
在「设置 → 模型」添加对话、向量、重排、视觉和语音模型,再由知识库或智能体按需选用。本地 Ollama 和远程模型可以组合使用,例如由本地模型生成向量、远程模型生成回答。
添加模型时应检查连接配置和索引兼容性:
- 更换向量模型需要重建索引。模型决定向量的语义空间与维度,新旧向量不能直接混用;
- 保存前测试连接。确认服务地址、凭据和模型名称可用后,再将模型用于知识库或智能体。
模型类型、配置字段和使用状态可按以下说明查询。
选择模型类型
| 类型 | 用途 |
|---|---|
| 对话模型 | 生成问答、摘要和智能推理内容 |
| 向量模型 | 将文档与问题转换为向量,支持语义检索 |
| 重排模型 | 对召回片段重新排序 |
| 视觉模型 | 识别文档或对话中的图片 |
| 语音模型 | 将音频转写为文本 |
添加与验证连接
在模型设置中选择类型和提供商,填写实际模型名称、服务地址与凭据,测试通过后保存。向量模型需要匹配索引维度;对话与视觉模型的上下文窗口应使用服务实际支持的大小,以便正确触发历史压缩。
修改连接地址时,测试可复用已保存凭据。模型调试器会实际发起请求,显示耗时、脱敏请求和响应结果,可用于检查向量维度、重排得分或流式输出。
查看引用与调整配置
知识库和智能体保存对模型的引用。删除模型前需检查依赖详情;内置模型由 YAML 配置管理,应在配置文件中维护。调用量和缓存使用情况可结合可观测性与审计查看。
配置与调用参考
模型类型与用途
模型类型定义在 internal/types/model.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 凭证状态 |
模型健康检查 / 连通性测试
两套机制,均在服务端持有凭证、不回传明文密钥:
-
测试连接(
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映射。 -
模型调试器(
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}环境变量插值;未设置的变量保留字面量以便暴露配置错误。 - 每次启动按
idUPSERT,并把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):
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输出统一的结构化日志行: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}) 的合并顺序从低到高:
- 协议默认值(
DefaultOpenAICompletions()等); - 厂商级
Compat(vendor.go里声明,例如 DeepSeek 的max_tokens_field: max_tokens); models.json里匹配到的条目(精确 id →aliases→match通配,最长字面前缀优先);- 部署叠加
config/models.json(见下); - 模型行上的
parameters.spec(UI「高级」里的协议覆盖与 compat JSON); 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、带日期的快照照常按厂商默认解析。
新增厂商
代码侧新增一个厂商只需要一个目录,四个文件,不用改协议层和前端:
- 复制一个相近的目录到
internal/models/vendors/<id>/,改vendor.go的 id、名称(Names放中文名)、Description、默认地址、Auth、Compat、ThinkingLevels、URLPatterns,并在包注释里逐条写清依据的厂商文档链接;无法从文档确认的字段标unverified:,不要臆测; - 按厂商文档填
models.json(id、reasoning、input、context_window、max_output_tokens、cost、thinking_levels、compat、source),同一家族用match通配(如"match": "gpt-5*"),精确 id 优先于通配; - 放一个
icon.svg(LobeHub icons 或手绘,6 KB 以内),会go:embed进二进制并以 data URI 下发给前端; - 在
vendors/all.go加一行 blank import; - 需要特殊 URL、协议选择或签名时实现
Endpoint/PreferAPI/Signer钩子(参考azure_openai、openai、weknoracloud)。
然后跑一条命令,目录层的守护测试会自动覆盖新厂商,无需为它单独写用例:
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:
make model-catalog-diff # 全部厂商
make model-catalog-diff VENDOR=deepseek # 只看一家
报告对比 models.dev 的公开元数据:+ 是上游有而我们没有的模型,~ 是数值差异,? 是上游没收录的条目(国内厂商和别名经常如此,不代表错)。脚本只读不写,也从不在运行时调用——字段名、思考格式这类行为事实不会被自动同步,必须以厂商文档为准手工维护,这是刻意的取舍: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 钉住。
但有四处既有模型行的运行时行为会变,升级时需要知会使用者:
extra_config.api变成保留键。它现在是协议选择器(openai-completions/openai-responses/anthropic-messages/google-generative-ai/ollama),取值非法会在创建、更新模型时返回 400。WeKnora 自身从未写过这个键,只有手工调 REST 或写 YAML 造出来的行会受影响——升级前删掉或改成合法取值。这里刻意选择报错而不是忽略:静默忽略会让人以为切换生效了。- Azure OpenAI 未填
api_version的行改走/openai/v1GA 数据面,不再是/openai/deployments/{model}/...?api-version=2024-10-21。旧默认版本根本不支持它同时声称的reasoning_effort与max_completion_tokens,属于自相矛盾。要保留旧路径,在额外字段里显式填一个api_version。 api.openai.com的一方流量改走 Responses 协议(PreferAPI只对官方域生效)。各类中转 / 网关仍走 Chat Completions,parity包里有断言钉住这一点。- 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 客户端):
- OpenAI 不再出现在 rerank 的厂商列表里。OpenAI 的 API 没有 rerank 接口,在这里建的行只会 404;架在 OpenAI 风格地址后面、自带 rerank 的中转请建成 generic 行。已有的行照常解析。
- 火山 rerank 每次最多 200 条(文档:datas「数组长度不超过 200」),旧实现按自己定的 50 条切分。
- 火山 rerank 的默认指令改为控制台原文
Whether the document answers the query or matches the content retrieval intent,文档要求「如需对齐控制台效果,请使用相同指令」;旧默认值把 Document / Query 写成了大写。已在额外字段里保存了指令的行不受影响。
Embedding 行也有几处按厂商文档纠正的行为变化(逐厂商的出站请求由 internal/models/embedding/wire_test.go 钉住):
- 托管厂商不再收到
truncate_prompt_tokens。此前所有 OpenAI 兼容厂商都被塞了一个 511,它只是 vLLM 的扩展参数;generic、gpustack照旧发送。 - 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已移除。 - 阿里云按模型分流:文本模型走
/compatible-mode/v1/embeddings,qwen3-vl-embedding、qwen2.5-vl-embedding、tongyi-embedding-vision*、multimodal-embedding*走原生多模态接口。base_url只填主机、国际站或业务空间域名时保留该主机,不再被替换成北京默认地址。 - 火山方舟的文本向量接口已归档下线,当前只有多模态接口。沿用老的
doubao-embedding-text*/doubao-embedding-large-text*的行改发到它们归档文档里的/api/v3/embeddings;此前它们被发往多模态接口。 - Gemini 的缩维放进
embedContentConfig.outputDimensionality。请求顶层的同名字段已被文档标为 deprecated;旧实现发的是顶层output_dimensionality。 - SiliconFlow 每次最多 32 条、百炼
text-embedding-v1/v2最多 25 条,超出时自动拆批;v1/v2 固定 1536 维,不发dimensions。 - OpenAI 兼容回复里没有
index时按顺序取(和旧实现一致);有index就按它放回,重复或缺位报错。 - Jina 的
task、Gemini 的taskType、OpenRouter 的input_type、火山的instructions、百炼原生接口的text_type/instruct都不发。它们会改变文档侧向量,开启后同一个知识库里新旧向量不在同一空间;需要按行显式开启的设计另见 Tencent/WeKnora#1401。
ASR 行的变化(逐厂商的出站表单由 internal/models/asr/wire_test.go 钉住):
- 不再一律发
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返回裸字符串,旧实现解不开。现在只有文档写明支持的模型声明它(OpenAIwhisper-1),其余走默认 json,Langfuse 里的音频时长因此只在返回分段的模型上有。需要分段的自建行可以在spec.compat里写{"response_format": "verbose_json"}。 - 按厂商文档的上限和格式在上传前拒绝:文件大小(OpenAI / 智谱 / OpenRouter 25 MB、Requesty 32 MB、SiliconFlow / MiniMax 50 MB;阿里与小米按整段
data:URI 计 10 MB),以及文档给出封闭格式清单的厂商(智谱、小米只收 wav/mp3,OpenAI、Requesty、MiniMax 各有列表)。 - 回复里没有
text字段即报错,不再当成「未检测到语音」入库;静音音频返回的是空字符串text,照常处理。 - ASR 行现在带上 provider 走目录解析,go-openai 依赖随之移除。provider 没有声明 ASR 的行:显式填了该厂商的直接报错;没填、靠 URL 识别到的,按 OpenAI 形状打到它的 URL(与旧实现一致),不走该厂商的 Endpoint 钩子。
- 支持 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。 - 知识库的「音频语言提示」终于发出去了(此前从未接线)。位置按厂商文档:OpenAI / Requesty / OpenRouter / GPUStack / generic 是
language表单字段,MiniMax 是language请求头,阿里与小米是asr_options.language;智谱、SiliconFlow、LiteLLM 文档没有这个参数,不发。填auto等同留空。 - 音频时长从回包里读: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 路径,能否调通没有核实。
模型调用链
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):
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 为租约到期时间;acquireScriptLua 脚本原子地清理过期租约、计数、在限额内准入。租约 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 接入。