概述

模型代理为 AI 应用提供统一的大模型访问入口，用于集中管理模型供应商凭证、可访问模型、入站鉴权、流量策略和运行观测。将模型代理关联到 AI 应用后，应用无需在代码中保存模型供应商的访问凭证，即可通过环境变量获取代理信息和默认模型。

使用场景

• 同一个 AI 应用需要切换或使用多个模型。
• 希望集中管理模型供应商凭证，避免在应用代码中配置密钥。
• 需要限制 AI 应用可调用的模型范围。
• 需要为模型调用配置 API Key 鉴权、Token 限流、重试或容灾策略。
• 需要统一查看模型调用量、延迟和异常情况。

工作原理

模型代理位于 AI 应用和模型供应商之间。AI 应用向模型代理发起请求，模型代理完成身份认证、模型校验和策略处理后，再将请求转发到对应的模型供应商。

1AI 应用 -> 模型代理 -> 模型供应商 -> 大语言模型
2             |
3             +-- 凭证托管、模型控制、流量策略和观测

模型供应商和模型代理承担不同职责：

创建模型代理前，需要先添加模型供应商。一个模型供应商可以被多个模型代理关联，不同模型代理可以基于同一供应商配置不同的可访问模型和访问策略。

关联模型代理后，AX 会向 AI 应用注入以下环境变量：

重要

模型代理的调用地址暂不对外开放，不能从公网、本地开发环境或非 AX 托管的应用直接访问。当前仅支持 AX 平台创建的 AI 应用访问模型代理。应用关联模型代理后，AX 会通过上述两个环境变量注入内部调用地址和默认模型名称，应用无需自行填写模型代理调用地址。

说明

模型代理是推荐的模型接入方式。AI 应用也可以通过自定义环境变量直连自有模型服务，但此方式需要自行管理凭证、访问地址和调用策略。

前提条件

• 已进入目标工作空间。
• 已开通需要使用的模型服务。
• 已从模型供应商获取 API Key，并确认 API Key 具有目标模型的调用权限。
• 使用“其他（OpenAI 兼容）”类型时，已准备兼容 OpenAI API 的 Base URL。
• 如需开启入站 API Key 鉴权，已在 调用凭证 页面创建 API Key。

创建模型代理

步骤一：添加模型供应商

模型供应商用于保存上游模型服务的访问地址和 API Key。模型代理通过模型供应商连接百度千帆、深度求索、智谱 AI 或其他兼容 OpenAI API 的模型服务。

支持的供应商类型

说明 页面会根据供应商类型自动填充预置 Base URL。实际地址可能因供应商服务版本、地域或专属部署方式而不同，请以模型供应商提供的接口文档为准。

配置模型供应商

1. 在左侧导航栏选择 模型与工具 > 模型代理。
2. 选择 模型供应商 页签，然后单击 添加模型供应商。

3. 按照以下说明完成配置：

   配置项	是否必填	说明
   名称	是	模型供应商在当前工作空间内的资源名称。必须以字母或数字开头和结尾，仅支持大小写字母、数字、下划线（_）和连字符（-），长度为 2～63 个字符。创建后不支持修改。
   供应商类型	是	选择百度千帆、深度求索、智谱 AI 或其他（OpenAI 兼容）。创建后不支持修改。
   Base URL	是	上游模型服务的 API 基础地址。使用预置地址时也应确认该地址与供应商当前文档一致。
   API Key	是	模型供应商签发的访问凭证。可以配置多个 API Key；模型代理调用上游服务时会随机选择其中一个。

4. 如需配置多个供应商 API Key，单击 添加 API Key 并逐个填写。
5. 单击 确定。

安全提示 模型供应商 API Key 用于访问上游模型服务，与模型代理的入站 API Key 用途不同。不要将供应商 API Key 写入应用代码、镜像、日志或公开文档，并按照最小权限原则配置模型访问权限。

管理模型供应商

在 模型供应商 页签可以查看供应商名称、供应商类型、API Endpoint、关联模型代理数和创建时间，并执行编辑或删除操作。

• 编辑：可以修改 Base URL 和 API Key，不能修改名称和供应商类型。
• 更新 API Key：保存时会使用本次填写的 API Key 列表覆盖原有配置。编辑时应重新填写所有需要保留的 API Key。
• 删除：当关联模型代理数大于 0 时不能删除。请先删除关联的模型代理，或将相关配置迁移到其他模型代理后再删除。

步骤二：配置模型代理

1. 在 模型代理 页签单击 创建模型代理。
2. 在 基本信息 区域填写模型代理名称和描述。注意：模型代理名称创建后不支持修改。

3. 在 后端供应商 区域选择模型供应商，并选择或填写可访问的模型。

   注意：调用方传入的 model 参数必须包含在可访问模型列表中，否则模型代理将拒绝请求。可以单击 同步模型列表 获取供应商当前支持的模型。

4. 在 入站访问凭证 区域选择鉴权方式：

   鉴权方式	说明
   不鉴权	调用方无需提供凭证。访问地址泄露后可能被未授权调用，不建议用于生产环境。
   API Key	调用方需要提供所选 API Key，推荐用于生产环境。

5. 按需配置 Token 限流等高级策略。
6. 单击 确定。

在 AI 应用中关联模型代理

模型代理在创建 AI 应用版本时关联。关联信息属于版本配置，修改后需要完成新版本构建和发布，运行实例才会使用新配置。

1. 在左侧导航栏选择 AI 应用。
2. 创建 AI 应用，或进入已有应用并创建新版本。
3. 展开 高级配置。

4. 在 关联平台资源 区域完成以下配置：

   • 模型代理：选择已创建的模型代理。
   • 默认模型：选择该模型代理可访问的模型。

保存应用配置后，AX 会将模型代理的内部调用地址作为 AX_MODEL_PROXY_NAME 的值注入应用运行环境，并将默认模型名称作为 AX_MODEL_NAME 的值注入应用运行环境。

5. 完成其他应用配置，然后提交并等待版本构建完成。
6. 发布版本并启动实例。

在 AI 应用中获取关联信息

AI 应用关联模型代理和默认模型后，AX 会将对应信息注入应用运行环境：

• AX_MODEL_PROXY_NAME：已关联的模型代理信息。
• AX_MODEL_NAME：已选择的默认模型信息。

AX_MODEL_PROXY_NAME 对应的地址仅在 AX 平台创建的 AI 应用运行环境内可访问，不是公网调用地址。应用如何读取和使用这些信息，取决于应用采用的开发语言、模型客户端和 Agent 框架。AX 当前不提供统一的 Python SDK 或固定初始化代码。请按照应用自身的运行方式完成配置，不要在代码中写入模型代理地址或模型供应商 API Key。

验证配置

在 AI 应用中验证

1. 进入 AI 应用详情页，查看当前版本的 关联平台资源。
2. 确认模型代理和默认模型与预期一致。
3. 进入应用测试页面发起一次模型对话或 API 请求。
4. 确认应用能够获得模型响应。

管理模型代理

• 编辑：调整可访问模型、鉴权方式和高级策略。模型代理名称不可修改。
• 查看调用示例：获取当前代理的请求示例。
• 查看监控：查看模型代理的调用与运行指标。
• 删除：删除前确认没有 AI 应用继续依赖该代理，并先更新相关应用版本。

常见问题

为什么默认模型列表为空？

请先选择模型代理。默认模型列表来自所选模型代理的可访问模型配置；如果仍为空，请返回模型代理页面同步或补充可访问模型。

为什么模型请求被代理拒绝？

常见原因如下：

• 请求中的 model 不在模型代理的可访问模型列表中。
• 模型代理已开启 API Key 鉴权，但请求未携带有效凭证。
• 请求触发了 Token 限流或其他高级策略。
• 模型供应商地址或供应商凭证无效。

为什么无法同步模型列表？

请检查模型供应商的 Base URL 和 API Key 是否有效，并确认 API Key 具有查询或调用目标模型的权限。如果使用其他（OpenAI 兼容）服务，还需要确认服务实现了 AX 同步模型列表所需的兼容接口。无法同步时，可以在创建模型代理时手动填写模型名称。

配置多个供应商 API Key 后如何选择？

模型代理向上游模型供应商发起请求时，会从已配置的 API Key 中随机选择一个。请确保每个 API Key 都有效，并且具有一致的模型访问权限，避免相同请求因选中的 Key 不同而得到不同结果。

编辑模型供应商时，为什么原 API Key 没有显示？

出于凭证安全考虑，页面不会回显原 API Key。保存编辑内容后，本次填写的 API Key 会覆盖原有配置，因此需要填写所有需要继续保留的 Key。

为什么无法删除模型供应商？

当模型供应商已被一个或多个模型代理关联时，AX 会禁止删除。请根据列表中的关联模型代理数检查依赖关系，先删除或迁移相关模型代理，再删除模型供应商。

修改模型代理关联后，为什么运行中的应用没有变化？

关联平台资源属于 AI 应用版本配置。请完成新版本构建和发布，并确认实例已经切换到新版本。

是否可以不使用模型代理？

可以。可以通过 AI 应用的环境变量配置自有模型服务，但需要自行负责凭证安全、模型切换、限流、容灾和观测。生产应用建议优先使用模型代理。