简体中文

English

简体中文

English

外观

模型与场景配置 ​

1. 先建 Provider Profile ​

进入模型提供商页面，先创建一个 Provider Profile。它代表一个可调用的模型服务商或一组 API 配置。

当前常用类型包括：

  • OpenAI-compatible：适合 OpenAI API 兼容服务，例如 OpenAI、部分中转服务、z.ai 等。
  • Anthropic：适合 Claude / Anthropic 体系。

一个 Profile 至少需要填写：

字段怎么填注意点
name自己能看懂的名称建议写清服务商和用途，例如 z.ai-coding、openai-main。
baseUrl服务商提供的 API 地址兼容 OpenAI 的服务通常写到版本层，例如 /v1；特殊服务见下文。
apiKey服务商的密钥复制后检查前后空格、换行和不可见字符。
模型 ID服务商暴露的真实模型名必须是 API 实际使用的 ID，不一定等于网页上的展示名。

如果页面支持同步远端模型，可以先同步一次；如果同步失败，就手动填写模型 ID。很多兼容服务并不完整支持模型列表接口，同步失败不一定代表聊天接口不可用。

2. Base URL 怎么填 ​

兼容 OpenAI 的服务商虽然都叫“OpenAI-compatible”，但路径规则并不完全一样。小万会根据 Provider 类型拼接请求地址，所以 Base URL 要按服务商形态来填。

常见情况：填到版本层 ​

大多数兼容 OpenAI 的服务，把 Base URL 填到 /v1 这一层即可：

text
https://api.example.com/v1

这种情况下，小万会按 OpenAI 兼容协议调用聊天、模型列表等接口。首次配置时优先使用这种写法，最容易排查。

特殊情况：服务商已经给出完整聊天接口 ​

有些服务商的 OpenAI 兼容入口不在标准 /v1 路径，或者文档直接给的是完整的 chat/completions endpoint。比如 z.ai 订阅里常见的 Base URL 形如：

text
https://api.z.ai/api/coding/paas/v4

如果直接填写这个地址后，请求里出现了 v4 和 v1 混用，或者应用继续自动追加 v1/chat/completions 导致 404 / 版本错误，可以改成完整聊天接口，并在末尾加 #：

text
https://api.z.ai/api/coding/paas/v4/chat/completions#

末尾的 # 用来告诉应用：这个地址已经是最终 endpoint，不要再自动追加 v1/chat/completions。这是处理兼容 OpenAI API 版本差异时最直接的做法，尤其适合 z.ai 这类路径里已经包含自定义版本号的服务。

TIP

使用完整 endpoint 时，如果模型同步失败，可以手动添加模型 ID。先用聊天或 Agent 场景验证调用是否成功，再决定是否继续细化其他场景。

Base URL 排查清单 ​

如果模型调用失败，先检查这些点：

  • Base URL 是否少了 /v1，或者多填了一段不该有的路径。
  • 服务商文档给的是“API 根地址”还是“完整聊天 endpoint”。
  • 兼容 OpenAI 的服务是否需要用 # 阻止自动追加路径。
  • API Key 是否复制进了空格、换行或中文引号。
  • 模型 ID 是否写成了展示名，而不是接口真实 ID。
  • 当前模型是否支持你绑定的场景，例如文本模型不能承担视觉操作。

3. 模型列表怎么维护 ​

Provider 创建好以后，还需要让小万能看到可用模型。

优先顺序建议是：

  1. 能同步远端模型，就先同步。
  2. 同步失败但你知道模型 ID，就手动添加。
  3. 同一个服务商里有多个用途不同的模型，可以都放在一个 Profile 里，再在场景配置里分别绑定。
  4. 如果服务商路径、密钥或请求格式差异很大，分成多个 Profile，避免混用。

手动添加模型时，建议顺手标注用途：

  • 推理 / 规划模型：给 Agent。
  • 多模态 / 视觉模型：给 Operation。
  • 快速便宜的文本模型：给 Compactor、Chat Compactor、Loading。
  • embedding 模型：只给 Memory Embed。

4. 场景模型怎么分 ​

创建 Provider 只是告诉小万“有哪些模型可用”，真正决定体验的是场景绑定。

进入 场景模型配置 后，可以看到当前版本按场景列出 Agent、Voice、Operation、Compactor、Chat Compactor、Loading、Memory Embed 和 Memory Rollup。每一行右侧都是模型选择按钮，可以按 Provider 搜索、折叠并选择具体模型。

场景建议选择作用
Agent稳定的强推理模型理解用户任务、规划步骤、调度工具，是主脑。
Operation支持视觉 / UI 操作的多模态模型判断屏幕内容，决定点击、输入、滚动等动作。
Voice适合语音输出链路的模型或默认模型处理语音回复相关能力；暂时不用语音时可先保持默认。
Compactor快速、成本较低的总结模型压缩通用上下文，避免长任务越跑越慢。
Chat Compactor快速、稳定的聊天总结模型压缩聊天上下文，让长对话保持可继续性。
Loading默认模型或轻量模型支撑加载、等待或过渡状态中的轻量调用。
Memory Embed真正的 embedding 模型生成向量，用于记忆和工作区检索。
Memory Rollup成本较低的总结模型整理长期记忆和阶段性摘要。

第一次配置时，最重要的是让 Agent 和 Operation 可用。前者决定小万能不能理解和规划，后者决定它能不能看懂屏幕并执行手机操作。

5. 三套推荐配置 ​

最小可用配置 ​

如果你只想先跑通：

  1. Agent 绑定一个稳定的大模型。
  2. Operation 先绑定同一个模型；如果它不支持视觉，再换成多模态模型。
  3. Voice、Compactor、Chat Compactor、Loading、Memory Rollup 暂时共用这个模型。
  4. Memory Embed 尽量单独绑定 embedding 模型；如果暂时没有，可以先不启用记忆相关验证。

这套配置的目标不是省钱或性能最好，而是先确认 API、权限、工作区和执行链路都能跑通。

更均衡的远端配置 ​

日常使用时，可以按场景拆开：

  • Agent：强推理、工具调用稳定、上下文足够长的模型。
  • Operation：多模态模型，最好能稳定理解截图、UI 文本和操作意图。
  • Compactor / Chat Compactor：速度快、成本低、总结质量够用的文本模型。
  • Memory Embed：服务商明确标注的 embedding 模型。
  • Memory Rollup：便宜稳定的总结模型。
  • Loading：轻量模型，降低等待状态的成本。

这套配置更适合长期使用：主任务质量交给强模型，重复性的压缩和整理交给便宜模型。

远端 + 本地配置 ​

本地模型跑通以后，可以把一部分轻量任务迁到本地：

  • 远端强模型继续负责 Agent 和复杂 Operation。
  • 本地小模型可以尝试承担 Loading、部分总结或低风险文本任务。
  • 本地 embedding 模型只有在向量维度、检索链路和性能都稳定时，再绑定到 Memory Embed。

第一次排查问题时，不建议远端和本地同时改。先确认远端链路稳定，再逐步替换单个场景。

6. Memory Embed 一定要单独看 ​

Memory Embed 是最容易误配的一项。它不是普通聊天模型，而是要输出向量，用于记忆和工作区检索。

如果这里配置成普通聊天模型，经常会表现为：

  • 记忆检索没效果。
  • embedding 配置显示不完整。
  • 长期记忆看起来存在，但回答时用不上。

判断方法很简单：服务商文档里如果没有明确说这个模型是 embedding / text embedding / vector model，就不要把它放到 Memory Embed。

7. 语音场景怎么理解 ​

Voice 是单独的场景，说明小万把“回复文本的语音合成与播放”也视作可配置能力，而不是固定功能。

这意味着：

  • 文字理解模型和语音输出模型可以拆开。
  • 不使用语音时，可以先保持默认，减少首次配置变量。
  • 后续做多音色、多角色或 TTS 策略切换时，可以单独调整这条链路。

8. 本地模型怎么启用 ​

本地模型页通常划分为两块：

  • Service
  • Market

Service ​

重点看：

  • 本地服务端口是否启动。
  • 已安装模型是否可用。
  • 模型状态轮询是否正常。
  • 当前安装包是否包含本地推理能力。

Market ​

重点看：

  • 能否浏览模型市场。
  • 能否按类别筛选。
  • 下载和刷新是否正常。
  • 模型资产是否落在工作区预期目录。

后端选择建议 ​

omniinfer-mnn 更适合把移动端模型运行能力直接纳入产品流程，当前代码和资产里能看到完整市场数据支持。

llama.cpp 适合偏通用的大语言模型本地运行，对开发者来说生态熟悉，调试也直观。

executorch-qnn 更偏 Qualcomm NPU 加速场景。它对设备兼容性、构建配置和运行环境要求更高，建议在远端主链路稳定后再验证。

9. 一套实用的入门流程 ​

如果你是第一次配置，可以按下面顺序：

  1. 新建一个远端 OpenAI-compatible Provider。
  2. Base URL 先按服务商文档填写到版本层；如果是 z.ai 这类完整 endpoint 场景，用 .../chat/completions#。
  3. 同步模型；同步失败就手动添加模型 ID。
  4. 先绑定 Agent 和 Operation。
  5. 发一条简单请求，确认小万能正常回复。
  6. 再测试一次需要看屏幕或操作页面的任务，确认 Operation 生效。
  7. 单独配置 Memory Embed。
  8. 最后再细化 Compactor、Chat Compactor、Loading、Voice 和本地模型。

Built with VitePress. 文档内容以当前仓库代码为准。

Copyright © OmnibotApp Docs