Weights & Biases Inference

Weights & Biases Inference 通过 W&B 平台为开放模型提供托管推理服务。AISIX 将这些模型映射到稳定的别名，并在网关处控制调用方访问权限。

准备工作

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

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 一个已获 Inference 授权的 W&B API Key。
• 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"

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

创建服务提供方密钥

export WANDB_API_KEY="YOUR_WANDB_API_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": "wandb-prod",
      "provider": "wandb",
      "api_key": "'"${WANDB_API_KEY}"'",
      "api_base": "https://api.inference.wandb.ai/v1",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

AISIX 服务提供方 ID 是 wandb，而不是 weights-and-biases。不要添加 adapter；AISIX 会为目录服务提供方推导出 openai 适配器。

显式 API Base 中包含 /v1。AISIX 发送上游请求时会追加 /chat/completions。

如果未指定项目，W&B 会将请求归因到默认 Entity 和 inference 项目。若要使用其他 W&B 团队和项目，请在服务提供方密钥的 request.default_headers 中添加 OpenAI-Project 值。请参阅上游请求头。

创建模型

使用完整的 W&B 模型 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": "wandb-llama-prod",
      "model_name": "meta-llama/Llama-3.1-8B-Instruct",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

替换为 W&B Inference 目录中的其他模型时，请保留发布方命名空间和大小写。

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

echo "$AISIX_API_KEY"

使用开源 AISIX 网关配置

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

export WANDB_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "wandb-prod"
    provider: "wandb"
    adapter: "openai"
    api_key: ${WANDB_API_KEY}
    api_base: "https://api.inference.wandb.ai/v1"

models:
  - display_name: "wandb-llama-prod"
    provider: "wandb"
    model_name: "meta-llama/Llama-3.1-8B-Instruct"
    provider_key: "wandb-prod"

api_keys:
  - display_name: "wandb-inference-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "wandb-llama-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 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wandb-llama-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from W&B Inference."
      }
    ]
  }'

AISIX 将上游模型 ID 转发到 POST /v1/chat/completions，并在 Bearer 请求头中携带 W&B API Key。

端点覆盖范围

W&B Serverless Inference 当前提供 OpenAI 兼容的 Chat Completions 和模型列表。AISIX 会增加基于 Chat 的协议桥接，但无法增加 W&B 未提供的上游能力：

路由	使用 wandb 模型别名时的行为
/v1/chat/completions	支持缓冲和流式传输。
/v1/responses	通过 Responses 桥接提供支持。没有对应 Chat Completions 语义的字段会被忽略。
/v1/messages	通过 AISIX 转换到 Chat Completions 提供支持。/v1/messages/count_tokens 不受支持，因为该模型并非由 Anthropic 提供支持。
/v1/embeddings	不支持。W&B Serverless Inference 未在此 API Root 上提供 Embedding 端点。
/v1/models	返回调用方可访问的 AISIX 别名，而不是 W&B 目录。调用 GET /passthrough/wandb/models 可使用已配置的服务提供方凭证访问 W&B 原生模型列表端点。
/v1/images/generations、/v1/videos、/v1/rerank	不支持。W&B 未提供这些 API，且 wandb 服务提供方值不在标准化路由允许列表中。
/passthrough/wandb/*rest	通过已配置的透传路由可用：路由认领此前缀，target_url 设为 W&B API 根地址；在调用方 Key 的 allowed_routes 上授予该路由。透传不会重写 AISIX 别名，并会增量中继 SSE 响应。可识别的 Chat、Completions 和 Responses 信封会记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。

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

故障排查

现象	检查项
上游返回 401 或 403	确认 W&B API Key 具有 Inference 访问权限。
上游返回 404	在 API Base 中保留 /v1，并验证模型 ID。
找不到模型	保留发布方命名空间和大小写。
创建服务提供方密钥时返回 400	使用 provider: "wandb"，且不要添加 adapter。

后续步骤

现在，你已将 AISIX 连接到 W&B Inference，并验证了模型别名。请继续阅读以下指南：

• 服务提供方密钥：管理服务提供方密钥轮换和环境访问权限。
• 模型别名：为别名配置路由、重试行为或成本元数据。
• 路由和故障转移：在 W&B Inference 和其他服务提供方之间进行故障转移。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。