Provider 集成

Provider 集成是 Anyy 发起模型请求时使用的后端连接。一个 provider entry 定义如何访问模型服务、如何认证、使用哪种 wire protocol，以及可用的模型 id。

本页是 provider setup 和 provider 配置的主入口。主模型、辅助模型和 fallback 路由的选择流程见配置模型。紧凑字段表见 Provider 配置参考。

心智模型

请区分这些概念：

Provider entry：providers 下的一条后端连接配置。
主模型：普通聊天和工具轮次使用的 provider/model。
辅助模型：媒体相关能力可选使用的专用模型。
Fallback 链：主模型 provider 失败时的有序备用模型。

Provider entry 不会改变 Anyy 的身份。助手始终识别为 Anyy。

Setup 流程

常规 provider setup 使用向导：

anyy setup model

向导会依次询问 provider template、认证方式和模型 id。确认后，它会写入 provider entry，并同步主模型字段。

用下面命令检查解析后的状态：

anyy config

Dashboard 的 Models 页面使用同一套 provider 配置。它可以设置全局主模型、重新配置 provider 认证/base URL/model、测试连接，并显示已配置的 fallback 和辅助模型条目。

配置形态

典型 API key provider：

providers:
  - id: openrouter
    profile: openrouter
    credential_ref: env:OPENROUTER_API_KEY
    default_model: anthropic/claude-sonnet-4

main_model:
  provider_id: openrouter
  model: anthropic/claude-sonnet-4

profile 会带入已知的 API mode、base URL、model catalog URL 和默认认证形态。如果不使用 profile，需要显式提供必需字段：

providers:
  - id: local
    api_mode: openai-compatible
    auth_mode: none
    base_url: http://127.0.0.1:1234/v1
    default_model: local-model

main_model:
  provider_id: local
  model: local-model

default_model: provider/model 仍作为主模型简写被接受。Anyy 加载配置时会把它与 main_model 规范化到同一视图。

Provider Profiles

当前可用于 setup 的 profile id 包括：

openrouter、novita、lmstudio、anthropic、openai-codex、openai-api、 alibaba、xiaomi、tencent-tokenhub、nvidia、huggingface、gemini、 deepseek、xai、zai、kimi-coding、kimi-coding-cn、stepfun、minimax、 minimax-cn、ollama-cloud、arcee、gmi、kilocode、opencode-zen、 opencode-go、azure-foundry、alibaba-coding-plan 和 ai-gateway。

有两个 setup template 故意没有 profile id：anthropic-compatible 和 custom-openai-compatible。它们会写入显式的 api_mode、base_url 和认证字段。

Profile alias 只是便利入口。提交到文档或示例里的配置应优先使用 canonical id：

Alias	Canonical profile
`openai`	`openai-api`
`codex`	`openai-codex`
`qwen`, `qwen-cloud`	`alibaba`
`xiaomi-mimo`	`xiaomi`
`nvidia-nim`	`nvidia`
`google-ai-studio`, `google-gemini`	`gemini`
`zai-glm`	`zai`
`kimi-cn`	`kimi-coding-cn`

部分 catalog entry 可能因为认证流尚不可用而显示为 blocked。Blocked entry 不是可用 provider，直到对应认证路径实现并启用。

API Modes

api_mode 选择 wire protocol：

值	用途
`openai-compatible`	OpenAI-compatible chat/completions endpoint 和很多 hosted router。
`anthropic-messages`	Anthropic Messages-compatible endpoint。
`google-gemini`	原生 Google Gemini API。
`openai-responses`	OpenAI Responses API。
`codex-responses`	`openai-codex` profile 使用的 Codex Responses 后端。

不要发明 adapter 名称。例如 DeepSeek 使用 openai-compatible；deepseek-compatible 会被拒绝。

认证

Provider 凭据字段接受引用，不接受裸密钥：

引用	用途
`env:NAME`	由 shell 或 service manager 提供的凭据。
`file:/absolute/path`	存放在 profile home 外部的凭据。
`secret:name`	Anyy 管理的 profile-local secret。

优先使用 credential_ref。api_key_ref 仍被 API-key provider 接受。Provider 凭据字段拒绝 literal:。

Auth mode：

`auth_mode`	凭据规则
`api_key`	使用 `credential_ref` 或 `api_key_ref`。
`oauth`	需要引用时使用 `credential_ref`；拒绝 `api_key_ref`。
`external_process`	需要引用时使用 `credential_ref`；拒绝 `api_key_ref`。
`aws_sdk`	需要时使用 `credential_ref`。
`none`	不允许 credential ref。Base URL 必须是本地或私有地址。

Secret 存储位置和 redaction 行为见凭据与鉴权。

自定义与本地 Endpoint

当 endpoint 是 OpenAI-compatible、但不是内置 profile 时，使用自定义 provider：

providers:
  - id: custom-openai
    api_mode: openai-compatible
    auth_mode: api_key
    base_url: https://models.example.com/v1
    credential_ref: env:CUSTOM_OPENAI_API_KEY
    default_model: team-model

auth_mode: none 只用于本地或私有 endpoint：

providers:
  - id: lmstudio
    profile: lmstudio
    auth_mode: none
    base_url: http://127.0.0.1:1234/v1
    default_model: local-model

公开互联网 endpoint 如果没有认证，会被配置校验拒绝。

模型目录与覆盖

当 provider 有 model catalog 时，anyy setup model 可以列出模型。如果 catalog 为空、不可用，或没有你需要的模型，请在向导里选择 Enter model id，或添加手写模型条目：

providers:
  - id: local
    profile: lmstudio
    models:
      - id: local-model
        display_name: Local Model
        capabilities:
          tool_calls: true
          streaming: true
          max_context_tokens: 32768

Capability override 是精确覆盖。省略某个 key 表示保留 profile 或 provider adapter 的默认判断；只有确认 provider 行为时才设置 true 或 false。

路由与 Fallback

模型路由归配置模型负责。那一页覆盖：

设置 main_model
配置 auxiliary_models.*
配置 auxiliary_models.fallback
理解 fallback 何时触发

Provider-local fallback_chain 仍作为兼容输入被接受，字段与 auxiliary_models.fallback 相同。推荐 setup 路径会把 canonical fallback 写入 auxiliary_models.fallback。

Fallback 是容错路径，不是绕过能力要求的方式。如果候选模型无法满足本轮所需的工具、媒体、上下文或 reasoning 连续性要求，它仍可能被跳过。

运行检查

Provider 编辑后运行：

anyy config
anyy doctor

anyy config 会报告解析后的 provider、model、API mode、base URL、认证引用状态和 max-turn 设置。Provider 请求失败仍会在模型实际使用时暴露；config.yaml 里没有单独的 provider health-check 配置块。

故障排查

Auth 显示 “(not set)”：引用的环境变量、文件或 secret 不存在。
Unknown provider profile：使用上方 canonical profile id，或显式配置 api_mode 和 base_url。
模型列表为空：手动输入模型 id。Provider catalog 只是便利入口，不是唯一来源。
Fallback 从不触发：fallback 只在 fallback-eligible provider error 时触发，且只会转向兼容候选。

心智模型​

Setup 流程​

配置形态​

Provider Profiles​

API Modes​

认证​

自定义与本地 Endpoint​

模型目录与覆盖​

路由与 Fallback​

运行检查​

故障排查​