版本：1.2.0

DigitalOcean Gradient AI

DigitalOcean Gradient AI Serverless Inference 提供对基础模型的托管访问，无需自行运维模型服务基础设施。AISIX 会将上游模型 ID 映射为稳定别名，并控制其使用权限。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
可调用 Serverless Inference 的 Gradient AI 模型访问密钥或 DigitalOcean Personal Access Token。
所选 DigitalOcean Inference 模型的访问权限。
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"

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

创建服务提供方密钥

export DIGITALOCEAN_INFERENCE_KEY="YOUR_MODEL_ACCESS_KEY"

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "digitalocean-prod",
      "provider": "digitalocean",
      "api_key": "'"${DIGITALOCEAN_INFERENCE_KEY}"'",
      "api_base": "https://inference.do-ai.run/v1",
      "apis": {
        "responses": {}
      },
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

使用 digitalocean 作为目录服务提供方 ID。AISIX 会派生 openai 适配器；在目录密钥上显式发送适配器会返回校验错误。

API Base 包含 /v1。AISIX 会向该 Base 追加所选端点的路径。

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

创建模型

为 Gradient AI 当前提供的模型创建别名：

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": "digitalocean-gpt-oss-prod",
      "model_name": "openai-gpt-oss-120b",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

请使用 DigitalOcean 模型 ID，而不是原始发布方的仓库名称。创建其他别名前，请在模型参考中确认当前可用性。

创建调用方 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": "digitalocean-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

使用开源 AISIX 网关配置

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

export DIGITALOCEAN_INFERENCE_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "digitalocean-prod"
    provider: "digitalocean"
    adapter: "openai"
    api_key: ${DIGITALOCEAN_INFERENCE_KEY}
    api_base: "https://inference.do-ai.run/v1"
    apis:
      responses: {}

models:
  - display_name: "digitalocean-gpt-oss-prod"
    provider: "digitalocean"
    model_name: "openai-gpt-oss-120b"
    provider_key: "digitalocean-prod"

api_keys:
  - display_name: "digitalocean-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "digitalocean-gpt-oss-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": "digitalocean-gpt-oss-prod",
    "input": "Say hello from DigitalOcean Gradient AI."
  }'

AISIX 会将 openai-gpt-oss-120b 连同配置的凭证转发至 DigitalOcean 原生 Responses 端点，然后在响应中恢复 AISIX 别名。

通过透传使用原生 Messages

上述服务提供方密钥已经会把 Responses 请求发送到 DigitalOcean 原生端点。DigitalOcean 还在同一 API Base 上提供原生 Messages 端点。除非使用下方服务提供方原生方案，否则 Messages 仍会经过转换：

AISIX 路由	上游行为
使用 DigitalOcean 别名的 `/v1/messages`	将 Anthropic 格式调用方请求转换为 DigitalOcean Chat Completions，不会调用 DigitalOcean 原生 `/v1/messages` 路由。
`/passthrough/digitalocean/messages`	调用 DigitalOcean 原生 Messages 路由，但不声明成对的协议面。请使用该端点支持的 DigitalOcean 模型 ID。Count Tokens 仍不可用。

DigitalOcean 接受 AISIX 在原生 Messages 请求中使用的 x-api-key 请求头，但未提供 Count Tokens。请继续通过透传访问此集成，不要声明 apis.messages，因为该声明把两条路由表示为一个完整协议面。

本页的 /passthrough/digitalocean 路径假定一条透传路由认领该前缀，target_url 设为 https://inference.do-ai.run/v1；在调用方 Key 的 allowed_routes 上授予路由名称。路径中省略 /v1 是因为路由目标已包含它；即使重复，开头的 v1 段也会去重。透传路由不会重写 AISIX 别名。AISIX 会从每个请求中检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。

端点覆盖范围

路由	使用 DigitalOcean 目录别名时的行为
`/v1/chat/completions`	支持，包括 `stream: true`。
`/v1/responses`	由于本指南声明了 `apis.responses`，请求会发送至 DigitalOcean 原生 Responses API。如果没有此声明，AISIX 会使用基于 Chat 的 Responses 桥接。
`/v1/messages`	通过转换为 Chat Completions 支持。由于配置的服务提供方密钥没有声明原生 Messages 协议面，`/v1/messages/count_tokens` 不可用。
`/v1/embeddings`	别名指向 `qwen3-embedding-0.6b` 等 DigitalOcean 嵌入模型时支持。
`/v1/audio/speech`	别名指向 `qwen3-tts-voicedesign` 等文本转语音模型时，请求可以到达 DigitalOcean，但响应并非端到端兼容 OpenAI。DigitalOcean 会把 Base64 音频封装在 JSON 数据 Envelope 中，AISIX 会原样中继，而不会解码为二进制音频。应用支持 DigitalOcean 原生响应协议时，请使用 `/passthrough/digitalocean/audio/speech` 并解码 `data[0].b64_json`。
`/v1/audio/transcriptions` 和 `/v1/audio/translations`	不可用。DigitalOcean 未提供这些路由。
`/v1/images/generations`	规范化 AISIX 路由只接受 `openai` 服务提供方值，因此会被拒绝。请使用兼容的 DigitalOcean 模型 ID 通过 `/passthrough/digitalocean/images/generations` 调用原生路由。
`/v1/videos`	未为 `digitalocean` 服务提供方实现。请通过 `/passthrough/digitalocean/videos` 提交 DigitalOcean 原生视频作业，通过 `/passthrough/digitalocean/video/generations/{job_id}` 轮询，并可通过 `/passthrough/digitalocean/videos/{video_id}/content` 下载已完成的 MP4。
`/v1/rerank`	规范化 AISIX 路由只接受 `openai`、`cohere` 和 `jina` 服务提供方值，因此会被拒绝。
`/passthrough/digitalocean/async-invoke`	为支持的图片、音频和文本转语音模型调用 DigitalOcean 异步端点。请使用服务提供方原生请求格式。
`/passthrough/digitalocean/models`	列出配置的 DigitalOcean 凭证可访问的模型 ID。

网关完整端点矩阵请参阅服务提供方兼容性。

故障排查

现象	检查项
上游返回 `401` 或 `403`	确认凭证具备推理访问权限。对于模型访问密钥，请验证其模型范围和所有 VPC 限制；受 VPC 限制的调用方必须使用 VPC 本地 DNS 解析器。
上游返回 `404`	在 `api_base` 中保留 `/v1`，并验证 DigitalOcean 模型 ID。
找不到模型	使用相同上游凭证查询 DigitalOcean `GET /v1/models`，并确认模型访问密钥包含所选模型。
创建服务提供方密钥时返回 `400`	使用 `provider: "digitalocean"`，且不要设置 `adapter`。

后续步骤

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

模型别名：为别名配置路由、重试行为或成本元数据。
API Key 与模型限流：配置网关侧的请求数和 Token 限制。
路由与故障转移：在 DigitalOcean 与其他服务提供方之间执行故障转移。
服务提供方兼容性：查看支持的代理端点和服务提供方特有限制。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

通过透传使用原生 Messages​

端点覆盖范围​

故障排查​

后续步骤​