跳到主要内容
版本：1.2.0

OVHcloud AI Endpoints

OVHcloud AI Endpoints 为托管模型提供推理端点。AISIX 为应用提供调用方密钥和稳定模型别名，以便访问这些端点。

准备工作​

开始前，请准备以下内容：

  • 一套 AISIX 环境：
    • 对于 AISIX Cloud，需要一个已关联网关的环境和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
    • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
  • 一个 OVHcloud AI Endpoints 访问 Token。
  • 所选模型的访问权限。
  • curl 和 jq。

使用 AISIX Cloud 配置​

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

OVHcloud 是提供 OpenAI 兼容端点的社区目录服务提供方。AISIX 通过 openai 适配器连接，并使用 Bearer Token 对上游请求进行身份认证。

创建服务提供方密钥​

export OVHCLOUD_API_KEY="YOUR_OVHCLOUD_ACCESS_TOKEN"

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "ovhcloud-prod",
      "provider": "ovhcloud",
      "api_key": "'"${OVHCLOUD_API_KEY}"'",
      "api_base": "https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
      "apis": {
        "responses": {}
      },
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

使用目录 ID ovhcloud 并省略 adapter。AISIX 会派生 OpenAI 传输格式和 Bearer 身份认证。

API Base 是 OVHcloud 文档中所述的共享 OpenAI 兼容 Root，其中包含 /v1；AISIX 会向该 Base 追加所选端点的路径。

apis.responses 声明会把 Responses 请求发送至同一 API Base 上的 OVHcloud 原生端点，而不是通过 Chat Completions 转换。

创建模型​

使用准确的 OVHcloud 模型 ID 创建别名：

MODEL_ID=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "ovhcloud-gptoss-prod",
      "model_name": "gpt-oss-20b",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

OVHcloud 模型 ID 不一定与发布方的原始仓库 ID 一致。请复制 OVHcloud 显示的值，包括下划线、连字符和大小写。

创建调用方 API Key​

AISIX_API_KEY=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "ovhcloud-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

使用开源 AISIX 网关配置​

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export OVHCLOUD_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "ovhcloud-prod"
    provider: "ovhcloud"
    adapter: "openai"
    api_key: ${OVHCLOUD_API_KEY}
    api_base: "https://oai.endpoints.kepler.ai.cloud.ovh.net/v1"
    apis:
      responses: {}

models:
  - display_name: "ovhcloud-gptoss-prod"
    provider: "ovhcloud"
    model_name: "gpt-oss-20b"
    provider_key: "ovhcloud-prod"

api_keys:
  - display_name: "ovhcloud-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "ovhcloud-gptoss-prod"

如果 AISIX 安装在本地，请在加载前校验文件：

aisix validate --resources resources.yaml

校验后，请在网关进程环境中提供所引用的环境变量并启动网关。仅当这些变量已可用于现有网关进程时才重新加载；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的校验和启动命令。挂载此 resources.yaml 文件，并在两个命令中使用 -e 传入该文件引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接​

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ovhcloud-gptoss-prod",
    "input": "Say hello from OVHcloud AI Endpoints.",
    "store": false
  }'

AISIX 会使用 Bearer 身份认证，将 OVHcloud 模型 ID 发送至原生 Responses 端点，然后在响应中恢复 AISIX 别名。OVHcloud 当前不管理 Responses 状态，因此要求设置 store: false。

端点覆盖范围​

OVHcloud 模型别名无法访问每个代理路由。AISIX 在标准化推理路由上使用 openai 适配器，但部分路由还会限制配置的服务提供方值。

路由OVHcloud 支持情况
/v1/chat/completions，包括 stream: true支持。工具调用、结构化输出、视觉和其他能力取决于所选模型。
/v1/responses由于本指南声明了 apis.responses，请求会发送至 OVHcloud 原生 Responses API。请发送 store: false；该 API 不支持状态、previous_response_id 和内置工具，但支持自定义函数工具。
/v1/messages通过转换到 Chat Completions 支持 Anthropic 形态的调用方。/v1/messages/count_tokens 不可用，因为它要求使用 Anthropic 协议的服务提供方密钥。
/v1/embeddings当别名指向 bge-m3 等 OVHcloud Embedding 模型时受支持。
/v1/audio/transcriptions当别名指向 whisper-large-v3 等 OVHcloud 语音转文本模型时受支持。AISIX 会重写模型别名，并把 OpenAI 兼容的 multipart 表单转发到 OVHcloud 转录端点。
/v1/audio/translations、/v1/audio/speech在共享 OVHcloud OpenAI 兼容 Base 上不可用。OVHcloud 通过转录提示词处理翻译，并在单独的原生端点上提供文本转语音模型。
/v1/images/generations、/v1/videos、/v1/rerank服务提供方值为 ovhcloud 的别名不可用；这些 AISIX 路由的服务提供方允许列表不包含该值。
/v1/models返回调用方可访问的 AISIX 别名，而不是 OVHcloud 模型目录。请通过 /passthrough/ovhcloud/models 获取 OVHcloud 当前列表。
/passthrough/ovhcloud/*rest通过已配置的透传路由可用于 OVHcloud 原生路由，网关标准化有限。

本页的 /passthrough/ovhcloud 路径假定一条透传路由认领该前缀，target_url 设为 OVHcloud API 基础地址；在调用方 Key 的 allowed_routes 上授予路由名称。原生 Responses 应优先使用规范化 /v1/responses 路由，因为 AISIX 会重写模型别名、增量流式传输并解析用量。对于 AISIX 未规范化的 OVHcloud 操作，请使用透传；它会原样转发正文，因此应发送上游模型 ID，而不是 AISIX 别名。

网关级端点规则请参阅服务提供方兼容性。

故障排查​

现象检查项
上游返回 401 或 403确认访问 Token 和项目权限。
上游返回 404在 api_base 中保留 /v1，并准确复制 OVHcloud 模型 ID。
找不到模型检查 model_name 中的下划线、连字符和版本片段。
创建服务提供方密钥时返回 400使用 provider: "ovhcloud" 并省略 adapter。

后续步骤​

你已将 AISIX 连接到 OVHcloud AI Endpoints，并验证了模型别名。接下来可阅读以下指南：