配置模型
Anyy 运行在可配置的模型后端之上。你来选择由哪个供应商和模型驱动这个助手； Anyy 自身始终标识为 Anyy，供应商或模型的名称只是后端标签，绝不是助手的身份。
本页讲解模型配置工作流：如何设置回答日常请求的主模型、如何启用可选的辅助能力 （图像、视频、图像生成、语音），以及如何设置回退链，让供应商的临时故障可以路由到另一个模型。
本页全程把三个不同的概念区分开来，它们由三条不同的命令分别配置：
| 概念 | 作用 | 配置位置 | 命令 |
|---|---|---|---|
| 主模型 | 回答普通对话和工具调用回合 | main_model / default_model | anyy setup model |
| 辅助能力 | 可选的媒体能力（image/video/imagegen/tts/stt） | auxiliary_models.*、media_understanding、tts、media_generation | anyy setup aux |
| 回退链 | 主模型遇到供应商错误时的备用模型 | auxiliary_models.fallback | anyy setup model fallback |
本页负责工作流本身。延伸阅读：
Models 页面
有两个只读界面可以查看当前的模型配置，而不会改动它。
运行 anyy config 可打印当前 home 已解析的配置。其中 Model 一节会报告默认模型、
其供应商、base URL、API 模式，以及供应商的鉴权方式：
◆ Model
Default model example-provider/example-model
Provider example-provider
Base URL https://api.example.com/v1
API mode openai-compatible
Auth env:EXAMPLE_API_KEY (not set)
Max turns 90
anyy config 视图是只读的——它绝不会修改文件。要做修改，请使用下文的 setup 命令。
当常驻网关在运行时，仪表盘的 Models 页面会以卡片形式呈现同样的信息：主模型、所有回退条目，
以及每个已配置的辅助能力（图像理解、视频理解、图像生成、文本转语音、语音转文本），按类别分组。
你还可以在此设置主模型（全局保存）、重新配置 provider（其 API Key、Base URL 与模型）以及测试连接——与 setup model 流程一致。
设置主模型
主模型回答普通对话和使用工具的回合。用以下命令配置它：
anyy setup model
anyy setup model
Configure provider, auth, and default model.
Usage:
anyy setup model [--home PATH]
anyy setup model fallback [--home PATH]
向导分三步进行：
- 选择供应商。 从内置的供应商模板中选择，与当前配置匹配的那个会标注
currently active。 - 鉴权。 视供应商而定，输入 API 密钥（存为 profile 本地的密钥文件，
config.yaml中只写入一个引用），或完成供应商的登录流程。凭据处理见 凭据与鉴权。 - 选择模型。 向导会加载供应商的模型目录供你选取；当目录为空或你的模型不在列表中时， 可选择 Enter model id 手动输入。
setup model 需要交互式终端——供应商鉴权和模型选择都是交互式提示：
✗ Setup model needs an interactive terminal
Reason:
provider authentication and model selection require interactive prompts
Next:
run anyy setup model from an interactive terminal
确认后，向导会同时写入主模型设置的两种形式，使其保持同步：
default_model: example-provider/example-model # "provider/model" 简写
main_model:
provider_id: example-provider
model: example-model
default_model 和 main_model 你只需手动设置其一——Anyy 在加载时会从一者推导出另一者。
default_model 是 provider/model 简写；main_model 是结构化形式。
命令标志要放在子命令之后：anyy setup model --home PATH，而不是
anyy --home PATH setup model。开头的 --home/--socket/--resume 标志保留给默认入口使用。
设置辅助模型
辅助能力是面向媒体的可选模型角色，主模型可能无法处理这些媒体。它们与主模型分开配置，
存储在 auxiliary_models.*（以及相关的 media_understanding、tts、media_generation 各节）下。
anyy setup aux
anyy setup aux
Configure optional model capabilities.
Usage:
anyy setup aux [--home PATH] [--probe]
anyy setup aux CAP [--home PATH] [--probe]
Capabilities:
image image understanding
video video understanding
imagegen image generation
tts text-to-speech
stt speech-to-text
search web search (coming soon)
不带能力名运行 anyy setup aux 会打开包含全部能力的多选菜单，已配置的能力会被预先勾选。
传入特定的 CAP 可直接跳到某个能力，例如 anyy setup aux image 或
anyy setup aux tts。search 虽然列出，但标记为 coming soon，目前尚不能配置。
对每个能力，向导会询问使用哪个连接。你可以：
- 复用已配置的供应商（包括主模型的连接），或
- 选择 + Add a new connection 输入单独的 base URL 和密钥，或
- Skip / keep current 保持不变。
支持连接测试的能力可接受 --probe，在设置时验证绑定（当前为 imagegen 和 tts）。
常见覆盖模式
你不配置的能力，在主模型能处理该媒体时会直接继承主模型。setup aux 菜单会以提示
inherits main: <provider/model> 显示这一点。只有当你希望某种媒体类型使用与主模型不同的模型时
才需要显式配置该能力——例如为图像理解配置专用的视觉模型，而主模型仍以文本为主。
单任务覆盖
只想改动某一个能力而不影响其他能力时，直接传入它的键名：
anyy setup aux image # 仅图像理解
anyy setup aux tts # 仅文本转语音
anyy setup aux imagegen --probe # 配置图像生成并进行测试
这只会打开该能力的提示，其余角色保持原样。
重置为自动路由
要停用某个专用辅助模型、改回主模型的自动路由，请清除 config.yaml 中该能力的条目。例如，
移除 auxiliary_models 下的 image_understanding 列表（以及对应的
media_understanding.image.models），即可让图像处理回归主模型。编辑后运行 anyy config
确认该能力不再显示专用模型。
Provider 认证
每个供应商都独立鉴权。主模型的供应商、每个辅助连接、每个回退供应商都可以各自持有自己的凭据。 存在两种鉴权形态：
- API 密钥——在向导中输入，存为 profile 本地的密钥文件，并从
config.yaml中引用 （例如api_key_ref: env:EXAMPLE_API_KEY，或file:/secret:引用）。密钥值本身绝不会进入config.yaml。 - 供应商登录——对于提供账号登录而非原始密钥的供应商，向导会执行登录流程并记录所得凭据。
anyy config 会报告每个供应商的凭据状态（例如当被引用的环境变量缺失时显示
env:EXAMPLE_API_KEY (not set)），让你一眼看出哪些供应商已就绪。
完整的凭据模型——引用方案、密钥在磁盘上的位置、登录流程以及脱敏——记录在 凭据与鉴权中。
模型路由
运行时，Anyy 按以下顺序将请求解析到具体模型：
- 主模型默认处理请求。
- 如果请求需要绑定到辅助模型的能力（例如图像或视频理解），该媒体会被路由到为该角色配置的 辅助模型；否则保留在主模型上。
- 如果主模型的供应商返回了可重试、且提示回退的供应商错误，路由会沿回退链向下移动（见下一节）。
你也可以即时切换当前模型而无需重跑向导。TUI 的模型选择器可以把模型固定到当前
会话；仪表盘的 Models 页面保存的是全局主模型。两条路径使用的都是你通过
setup model 设置的同一种 provider/model 形态。
Fallback 路由
回退链让主模型的临时故障可以路由到另一个模型，而不是直接抛出错误。它针对主模型配置，存储在
auxiliary_models.fallback 下：
anyy setup model fallback
anyy setup model fallback
Configure fallback routing for the main model.
Usage:
anyy setup model fallback [--home PATH]
回退设置要求主模型已配置——它必须有一个归属者。若尚未设置，向导会提示你先运行
anyy setup model。
编辑器提供三种操作：
- Keep current fallback routing——保持回退链不变。
- Replace fallback routing——构建新的有序回退链。向导会列出你已配置、且带有默认模型的供应商； 按优先级顺序选取，并通过确认 Add another fallback provider? 来延长回退链。
- Clear fallback routing——完全移除辅助回退。
最终的回退链在 config.yaml 中如下所示：
auxiliary_models:
fallback:
- provider_id: backup-provider
model: backup-model
max_attempts: 1
回退只在可触发回退的供应商错误时启用，且 Anyy 会按顺序挑选第一个兼容的候选。 当某候选无法满足在途请求的需求时会被跳过——例如正在使用工具但它不支持工具调用、本回合携带图像或视频 而它不支持该媒体输入，或它的上下文窗口比当前模型更小。两个可选开关可按条目放宽后两项检查：
| 字段 | 效果 |
|---|---|
allow_context_drop | 允许上下文窗口更小的回退模型 |
allow_reasoning_drop | 允许无法重放既往推理的回退模型 |
max_attempts | 在转向下一条目之前对本条目的尝试次数 |
这些按条目字段的完整说明见 供应商配置参考。
能力缓存
当 Anyy 需要知道某模型是否支持图像或视频输入（例如判断某回退候选是否兼容）时，会把所学到的信息
记录到模型能力缓存中，位于 <home>/cache/model_capabilities.json。该缓存以供应商、模型和 base URL
为键，因此再次探测同一模型的开销很小。
该缓存是一种优化，而非配置——你不需要手动编辑它。如果某供应商的能力发生变化，删除该文件即可让 Anyy 在下次使用时重新学习。
何时生效
setup 各命令在你到达最终确认之前不会写入任何内容；取消会让配置保持原样。确认写入后，运行时会重新读取
配置——当常驻网关在运行时，模型和供应商的改动会对后续请求生效而无需手动重启，仪表盘的 Models 页面也会
反映新状态。已通过 TUI 模型选择器固定了某模型的会话，会保留该模型直到会话结束或你再次切换。
随时运行 anyy config 可确认已解析的主模型、供应商和鉴权状态。
故障排查
- “Setup model needs an interactive terminal.”
setup model需要真实的提示。请从交互式终端 运行它，而不是管道或非交互式脚本。 - “Default TUI flag used with a command.” 你把
--home（或--socket/--resume）放到了 子命令之前。把命令标志移到命令之后：anyy setup model --home PATH。 - 回退设置拒绝运行。 它要求先有已配置的主模型；请先运行
anyy setup model，再运行anyy setup model fallback。 - 回退从不触发。 回退只在可触发回退的供应商错误时启用，且只会转向兼容的候选。如果备用模型上下文
窗口更小，或缺少该回合所需的工具 / 图像 / 视频支持，它会被跳过；如果这种降级可以接受，请在该条目上设置
allow_context_drop或allow_reasoning_drop。 - 鉴权显示 “(not set)”。 供应商被引用的凭据（例如某环境变量）缺失。重新运行
anyy setup model重新输入，或提供被引用的密钥。见 凭据与鉴权。 - 某辅助能力被忽略。 用
anyy config确认它已配置；未配置的能力会回退到主模型，而search目前尚不可用。