diff --git a/README.md b/README.md index de8b4c03..d1854d33 100644 --- a/README.md +++ b/README.md @@ -74,13 +74,13 @@ CLIProxyAPI includes integrated support for [Amp CLI](https://ampcode.com) and A - **Model mapping** to route unavailable models to alternatives (e.g., `claude-opus-4.5` → `claude-sonnet-4`) - Security-first design with localhost-only management endpoints -When routing needs to stay deterministic, prefer the provider-specific paths over the merged `/v1/...` endpoints: +When you need the request/response shape of a specific backend family, use the provider-specific paths instead of the merged `/v1/...` endpoints: - Use `/api/provider/{provider}/v1/messages` for messages-style backends. - Use `/api/provider/{provider}/v1beta/models/...` for model-scoped generate endpoints. - Use `/api/provider/{provider}/v1/chat/completions` for chat-completions backends. -This matters when `oauth-model-alias`, alias pools, or fallback mappings reuse the same client-visible model name across multiple backends. In those cases, `/v1/models` may show the merged alias view instead of the executor you intend to hit. Treat the provider-specific request path as the source of truth for backend selection. +These routes help you select the protocol surface, but they do not by themselves guarantee a unique inference executor when the same client-visible model name is reused across multiple backends. Inference routing is still resolved from the request model/alias. For strict backend pinning, use unique aliases, prefixes, or otherwise avoid overlapping client-visible model names. **→ [Complete Amp CLI Integration Guide](https://help.router-for.me/agent-client/amp-cli.html)** diff --git a/README_CN.md b/README_CN.md index 463c7ad1..ea65408c 100644 --- a/README_CN.md +++ b/README_CN.md @@ -73,13 +73,13 @@ CLIProxyAPI 已内置对 [Amp CLI](https://ampcode.com) 和 Amp IDE 扩展的支 - 智能模型回退与自动路由 - 以安全为先的设计,管理端点仅限 localhost -当你需要确定地命中某个后端执行器时,优先使用 provider-specific 路径,而不是合并后的 `/v1/...` 端点: +当你需要某一类后端的请求/响应协议形态时,优先使用 provider-specific 路径,而不是合并后的 `/v1/...` 端点: - 对于 messages 风格的后端,使用 `/api/provider/{provider}/v1/messages`。 - 对于按模型路径暴露生成接口的后端,使用 `/api/provider/{provider}/v1beta/models/...`。 - 对于 chat-completions 风格的后端,使用 `/api/provider/{provider}/v1/chat/completions`。 -这一点在 `oauth-model-alias`、alias 池或 model fallback 让多个后端复用同一个客户端可见模型名时尤其重要。此时 `/v1/models` 可能展示的是合并后的别名视图,而不是你真正想命中的执行器。对于后端选择,请以 provider-specific 的请求路径为准。 +这些路径有助于选择协议表面,但当多个后端复用同一个客户端可见模型名时,它们本身并不能保证唯一的推理执行器。实际的推理路由仍然根据请求里的 model/alias 解析。若要严格钉住某个后端,请使用唯一 alias、前缀,或避免让多个后端暴露相同的客户端模型名。 **→ [Amp CLI 完整集成指南](https://help.router-for.me/cn/agent-client/amp-cli.html)** diff --git a/README_JA.md b/README_JA.md index 6380977a..895b4bbd 100644 --- a/README_JA.md +++ b/README_JA.md @@ -74,13 +74,13 @@ CLIProxyAPIは[Amp CLI](https://ampcode.com)およびAmp IDE拡張機能の統 - 利用できないモデルを代替モデルにルーティングする**モデルマッピング**(例:`claude-opus-4.5` → `claude-sonnet-4`) - localhostのみの管理エンドポイントによるセキュリティファーストの設計 -どのバックエンド実行系に送るかを確定させたい場合は、統合された `/v1/...` エンドポイントよりも provider-specific のパスを優先してください。 +特定のバックエンド系統のリクエスト/レスポンス形状が必要な場合は、統合された `/v1/...` エンドポイントよりも provider-specific のパスを優先してください。 - messages 系のバックエンドには `/api/provider/{provider}/v1/messages` - モデル単位の generate 系エンドポイントには `/api/provider/{provider}/v1beta/models/...` - chat-completions 系のバックエンドには `/api/provider/{provider}/v1/chat/completions` -これは `oauth-model-alias`、alias プール、model fallback によって複数のバックエンドが同じクライアント向けモデル名を共有する場合に特に重要です。その場合、`/v1/models` は実際に狙っている実行系ではなく、統合後のエイリアス表示を返すことがあります。バックエンド選択の基準としては provider-specific のリクエストパスを使ってください。 +これらのパスはプロトコル面の選択には役立ちますが、同じクライアント向けモデル名が複数バックエンドで再利用されている場合、それだけで推論実行系が一意に固定されるわけではありません。実際の推論ルーティングは、引き続きリクエスト内の model/alias 解決に従います。厳密にバックエンドを固定したい場合は、一意な alias や prefix を使うか、クライアント向けモデル名の重複自体を避けてください。 **→ [Amp CLI統合ガイドの完全版](https://help.router-for.me/agent-client/amp-cli.html)** diff --git a/config.example.yaml b/config.example.yaml index 0493c544..1b365d87 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -282,8 +282,9 @@ nonstream-keepalive-interval: 0 # Supported channels: gemini-cli, vertex, aistudio, antigravity, claude, codex, qwen, iflow, kimi. # NOTE: Aliases do not apply to gemini-api-key, codex-api-key, claude-api-key, openai-compatibility, vertex-api-key, or ampcode. # NOTE: Because aliases affect the merged /v1 model list and merged request routing, overlapping -# client-visible names can become ambiguous across providers. When you need deterministic backend -# selection, prefer /api/provider/{provider}/... instead of the generic /v1/... endpoints. +# client-visible names can become ambiguous across providers. /api/provider/{provider}/... helps +# you select the protocol surface, but inference backend selection can still follow the resolved +# model/alias. For strict backend pinning, use unique aliases/prefixes or avoid overlapping names. # You can repeat the same name with different aliases to expose multiple client model names. # oauth-model-alias: # gemini-cli: