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，且末尾不包含斜杠
# 本地 On-Premises 快速入门使用 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",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

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

API Base 包含 /v1。AISIX 会为 Chat 请求追加 /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"

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：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "digitalocean-gpt-oss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from DigitalOcean Gradient AI."
      }
    ]
  }'

AISIX 会将 openai-gpt-oss-120b 转发到 https://inference.do-ai.run/v1/chat/completions，并携带 DigitalOcean 凭证。

访问 DigitalOcean 原生 API 格式

DigitalOcean 在同一 API Base 上提供原生 Responses 和 Messages 端点。本指南中的目录服务提供方密钥仍使用 openai 适配器，因此规范化 AISIX 路由不会自动选择这些原生上游格式：

AISIX 路由	上游行为
使用 DigitalOcean 别名的 /v1/responses	在 DigitalOcean Chat Completions 上使用 AISIX Responses 桥接，不会调用 DigitalOcean 原生 /v1/responses 路由，且没有 Chat 等价项的 Responses 专属字段会被忽略。
/passthrough/digitalocean/responses	调用 DigitalOcean 原生 Responses 路由。请在 model 中使用 DigitalOcean 模型 ID，而非 AISIX 别名。
使用 DigitalOcean 别名的 /v1/messages	将 Anthropic 格式调用方请求转换为 DigitalOcean Chat Completions，不会调用 DigitalOcean 原生 /v1/messages 路由。
/passthrough/digitalocean/messages	调用 DigitalOcean 原生 Messages 路由。请使用该端点支持的 DigitalOcean 模型 ID。

本页的 /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	通过基于 Chat 的 Responses 桥接支持，并非 DigitalOcean 原生 Responses API。
/v1/messages	通过转换为 Chat Completions 支持。/v1/messages/count_tokens 要求 Anthropic 后端模型，因此不可用。
/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 与其他服务提供方之间执行故障转移。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特有限制。