服务商协议与模型接口
面对“这个模型能不能用”，先分清要做的是普通对话、Codemode 图片/分类操作，还是产品媒体工具。三者共享部分目录与凭据机制，但接口不能互换。
v0.1.107 的共同参考是固定 Pi v1.2.0，提交 06a466935536f8c9bcacb2d5efc0fc021be1bdff。下列内容说明已实现接口，不把目录条目或本地测试扩大成对所有真实 Endpoint、账号、认证变体的验收。
有类型的模型目录
模型目录按 type 区分操作：
| 类型 | 用途 | 边界 |
|---|---|---|
chat | 对话及工具调用 | 省略 type 时的默认类型；主模型/fallback 选择该类型 |
image | 有类型的图片生成 | 供 models.generateImages() 使用 |
classifier | 结构化选择、评分和布尔分类 | 供 models.classify() 使用 |
模型 ID 与 provider、type 一起解析。同一 ID 可属于不同类型，图片或分类条目不会静默变成对话模型。目录描述包含 API、输入/输出类型、限制、费用、兼容元数据和采样设置；这些声明描述路由，不会探测远端可用性。
高级 providers[].models[] 字段包括 type、api、base_url、input、output、headers、input_limits、sampling_params、sampling_params_by_thinking_level、compat、capabilities、cost。请遵循所声明的线上协议和服务商参数。原生采样依次合并模型默认值、实际推理等级参数、请求参数，后者覆盖前者；这些字段不会新增协议，也不保证远端接受任意选项。
Codemode Models Helpers
Codemode 提供 Models helpers 时，下列异步函数使用同一份配置目录与凭据：
| 函数 | 结果 |
|---|---|
models.getModelsOfType(type, provider?) | chat、image 或 classifier 目录条目 |
models.getAvailableOfType(type, provider?) | 按服务商启用状态与可解析凭据筛选的条目 |
models.getModelOfType(type, provider, id) | 精确条目，不存在时为 undefined |
models.classify(model, context) | 有类型的分类结果 |
models.generateImages(model, context) | 有类型的图片结果 |
“Available”是本地凭据/启用状态检查，不是在线推理测试。脚本收到的目录描述不含配置 Header；执行时重新解析原始配置模型，修改返回描述不能把操作重定向到另一 Endpoint。
已实现的图片 API 是 openrouter-images；分类 API 为 typesafe-system-one、cloudflare-workers-ai-system-one、llama-cpp-classify 和 openai-decisions。它们的本地请求/结果检查不代表任意外部部署和账号都已验收。
需要先确认有哪些分类模型时，可以在 Codemode 内查询：
const candidates = await models.getAvailableOfType("classifier");
return candidates.map(model => ({
provider: model.provider,
id: model.id,
api: model.api,
}));
生成图片时，generateImages 的 context 为 { input: [...] }，其中接受文字和可选的 base64 参考图片块。将结果 output 中的图片块传给 image(block) 才会展示图片。classify 接受 state、questions 和模型支持的可选图片；问题类型为 choice、score、bool。原生失败保留为有类型的 error/aborted 结果，使用输出前应检查 stopReason。这些 helpers 不提供通用 models.chat() 接口。
调用分类时，context 必须有对象 state 和非空对象 questions；每个问题填写 type、instructions、criteria。choice 的 criteria 是非空的“标签 → 字符串含义”对象，score 是非空且从低到高排列的字符串描述数组，bool 是含 true、false 含义的对象。
图片分类还要求模型支持图片，images 中使用 { type: "image", data: "<base64>", mimeType: "image/png" }。分类输出在 answers，图片生成输出在 output；后端提供用量时，结果还会包含 usage。
产品图片生成工具是另一条路径，当前使用 OpenAI Responses 并保存会话附件。它的 Dashboard 路由不会配置 openrouter-images 或分类记录。
对话协议
Anyy api_mode | 对应 Pi API | 请求家族 |
|---|---|---|
openai-compatible | openai-completions | OpenAI 风格 Chat Completions，包括兼容本地服务 |
openai-responses | openai-responses | OpenAI Responses |
codex-responses | openai-codex-responses | Codex 订阅 Responses 及其传输/会话行为 |
anthropic-messages | anthropic-messages | Anthropic Messages |
google-gemini | google-generative-ai | Gemini Generative AI |
同一品牌可能提供多种 Endpoint 契约，选择品牌不代表协议可以混用。Ollama 和 Ollama Cloud 使用既有 OpenAI 兼容家族；Ollama /api/tags 只用于发现模型。
Pi 另外五种 API azure-openai-responses、bedrock-converse-stream、google-vertex、mistral-conversations、pi-messages 在本版没有独立原生实现或验收。兼容网关确实实现现有五类之一时，可以使用对应契约，但这不代表新增该服务的独立原生 API。包括原生 Azure、Bedrock 在内的阻止选项仍不可用。
Endpoint 与认证细节
填写所选 Endpoint 要求的 API 根地址。原生 Anthropic Messages 在所给 Base URL 后追加 /v1/messages?beta=true，不会删除已有路径前缀。Anthropic 直连根地址为 https://api.anthropic.com，不要重复添加 /v1；自定义代理必须提供最终得到的路径。
Anyy 在准备请求前解析凭据。原生 Anthropic 认证遵循有效 Key 和原生 Header/beta 规则，auth_transport 不是强制改变原生 Messages 认证形式的开关。OAuth/订阅设置仍与 Endpoint 绑定。Codex 使用独立订阅凭据，并发送 Anyy 自己的客户端身份，默认 originator: anyy，不冒充服务商客户端。先应用配置的 model headers，再应用 request headers；后者可覆盖或删除该标记。认证与真实的 Anyy User-Agent 仍由 Anyy 管理。
重试、fallback 与虚拟路由
这些机制有不同职责：
| 机制 | 控制范围 |
|---|---|
| 会话自动重试 | 重试可重试的助理错误；默认开启，最多 3 次，从 2,000 ms 开始指数退避，上限 60,000 ms |
| Provider SDK 重试 | 按 retry.provider 重试符合条件的初始传输/HTTP 失败，不重放已经开始流式读取的响应正文 |
| 配置 fallback | 错误策略允许时，按顺序尝试兼容 provider/model |
| 虚拟模型回调 | 把已注册虚拟选择解析为物理目录模型及实际推理等级 |
初始请求不计入会话重试次数。计费/账号限额错误不属于普通暂时性重试，上下文溢出进入上下文恢复路径；取消会结束重试等待。retry.enabled: false 关闭会话自动重试，不会同时关闭所有 Provider SDK 行为或已配置 fallback。
高级 Profile 配置使用以下准确的 camelCase 键：
retry:
enabled: true
maxRetries: 3
baseDelayMs: 2000
maxAgentDelayMs: 60000
provider:
maxRetries: 0
maxRetryDelayMs: 60000
httpIdleTimeoutMs: 300000
retry.provider.timeoutMs 可选，用于 Provider 请求超时。httpIdleTimeoutMs 默认 300,000 ms，0 或 disabled 关闭空闲计时器；媒体路由有自己的限制。会话重试、SDK 尝试、fallback 尝试和 Codex 原生传输恢复相互区分，因此一个设置不是总请求次数或总耗时上限。
虚拟模型使用内部 pi-virtual 注册/回调接口。它不是第六种远端推理协议，v0.1.107 没有 YAML 虚拟路由声明、CLI 向导或 Dashboard 路由编辑器。已注册回调可获得 user/continuation/retry/direct 上下文并保留分支路由状态，但必须返回具有可用凭据的物理目录模型，不能指向未注册模型或递归进入另一个虚拟模型。配置 fallback 列表本身不会注册这种回调。
日常设置见模型配置与 Dashboard 模型。