对接 Crusoe Managed Inference：基于 vLLM OpenAI 兼容 API 的 SDK 调用、curl 验证与模型目录查询实战

Crusoe 提供的 Managed Inference 是一项托管推理服务，其底层由 vLLM 驱动，对外暴露的是 OpenAI 兼容的 API。这意味着凡是针对自建 vLLM 服务编写的应用代码，无需任何改动即可直接指向 Crusoe 端点运行。本文带你完整走通这一接入路径：从 API Key 的环境变量配置，到使用 OpenAI SDK 发起 Chat Completions 请求、用 curl 独立验证端点、以及通过 /v1/models 查询当前可用模型目录，并结合 vLLM 源码说明这些端点背后的实际实现。

为什么"零改动"可行：vLLM 的 OpenAI 兼容层

Crusoe Managed Inference 之所以能与任何 OpenAI SDK 代码无缝对接，核心在于 vLLM 的 API Server 原生实现了 OpenAI 的接口协议。从源码结构看，相关路由集中在 vllm/entrypoints/openai/ 目录下：

• Chat Completions：vllm/entrypoints/openai/chat_completion/api_router.py 中注册了 POST /v1/chat/completions 路由。该端点支持两种返回形态：非流式请求返回 JSONResponse，流式请求（stream: true）则返回 media_type="text/event-stream" 的 StreamingResponse，并通过 with_sse_keep_alive 保持 SSE 长连接不被中间代理掐断。同文件还注册了 POST /v1/chat/completions/batch 批量推理端点；
• 模型列表：vllm/entrypoints/openai/models/api_router.py 注册了 GET /v1/models 路由，由 OpenAIServingModels.show_available_models() 返回当前加载的模型与适配器信息；
• 请求协议：请求体由 vllm/entrypoints/openai/chat_completion/protocol.py 中的 ChatCompletionRequest（Pydantic 模型）定义，字段与 OpenAI 规范对齐（model、messages、max_tokens 等），并带有 vLLM 扩展字段（如 token_ids 回传等），因此标准 OpenAI 客户端发出的 JSON 都能被正确校验与解析。

托管服务（如 Crusoe）在其端点复用同一套协议，所以你在本地跑 vllm serve 时验证过的调用方式，指向 Crusoe 的 base URL 后依然成立。

前置条件

开始之前需要准备：

1. 一个 Crusoe 账户；
2. 一个 Inference API Key。在 Crusoe Console 的 Security > Inference API Key 页面中创建。

拿到 Key 后，将其设置为环境变量，后文的 SDK 调用与 curl 命令都会引用它：

export CRUSOE_API_KEY="your-api-key"

将 Key 放入环境变量而非硬编码在代码中，是避免密钥泄露到版本库或日志的最基本实践。

使用 OpenAI SDK 调用

接入方式是把 OpenAI 客户端的 base_url 指向 Crusoe 的推理端点：

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.inference.crusoecloud.com/v1",
    api_key=os.environ["CRUSOE_API_KEY"],
)

response = client.chat.completions.create(
    model="zai/GLM-5.2",
    messages=[{"role": "user", "content": "Hello, how are you?"}],
)

print(response.choices[0].message.content)

要点说明：

• base_url 以 /v1 结尾：OpenAI SDK 会在其后拼接具体路径（如 /chat/completions），最终请求打到 https://api.inference.crusoecloud.com/v1/chat/completions，与 vLLM 源码中 @router.post("/v1/chat/completions", ...) 注册的路径一致；
• model 参数：示例使用 zai/GLM-5.2。实际可用模型名以 /v1/models 接口返回为准（见下文），更换模型只需修改这一个字段；
• messages 结构：与 OpenAI Chat Completions 规范完全一致，role 支持 system / user / assistant 等角色；
• 由于协议同源，你同样可以传入 temperature、max_tokens、stream=True（对应 vLLM 端点中的 SSE 流式分支）等标准 OpenAI 参数；
• 响应对象是标准 OpenAI 的 ChatCompletion 结构，取 response.choices[0].message.content 即可获得模型回复文本。

用 curl 独立验证端点

不依赖 SDK 时，可以用 curl 直接验证端点可用性与认证是否配置正确：

curl https://api.inference.crusoecloud.com/v1/chat/completions \
    -H "Authorization: Bearer $CRUSOE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "zai/GLM-5.2",
        "messages": [
            {"role": "user", "content": "Hello, how are you?"}
        ],
        "max_tokens": 50
    }'

请求细节：

• Authorization: Bearer $CRUSOE_API_KEY：采用标准 Bearer Token 认证，shell 会自动展开环境变量；若返回 401，优先检查 CRUSOE_API_KEY 是否已正确导出、Key 是否仍在有效期内；
• Content-Type: application/json：vLLM 侧的路由挂载了 validate_json_request 依赖（见 chat_completion/api_router.py），请求体必须是合法 JSON，否则会收到 400 Bad Request 及 ErrorResponse 结构的错误信息；
• max_tokens: 50：限制本次补全最多生成 50 个 token，验证场景下可以有效控制耗时与费用。

查询可用模型目录

在写业务代码前，先确认端点上实际有哪些模型可以调用：

curl https://api.inference.crusoecloud.com/v1/models \
    -H "Authorization: Bearer $CRUSOE_API_KEY"

该命令对应 vLLM 的 GET /v1/models 路由（vllm/entrypoints/openai/models/api_router.py），返回标准 OpenAI 的模型列表结构。由于托管平台的模型目录可能随时间调整，以接口实时返回的 id 作为 model 参数的取值是最可靠的做法。完整的模型列表与托管推理服务的 API 细节，可进一步查阅 Crusoe 官方的 Managed Inference 文档。

实践建议

1. 先 curl 后 SDK：遇到认证、网络或参数问题时，用 curl 复现可以排除 SDK 版本差异带来的干扰；
2. 模型名以接口为准：不要把文档示例中的模型名当成固定值，上线前用 /v1/models 核对；
3. 流式请求注意超时：若使用 stream: true，vLLM 端点会通过 SSE keep-alive 维持连接，客户端与中间网关的读超时应留足余量；
4. 自建与托管平滑切换：由于协议一致，base_url 与 API Key 是唯一需要切换的配置，适合在自建 vLLM 集群与托管服务之间做灰度迁移。