GPUStack API 参考:内置 Swagger UI 的使用、认证与 OpenAI 兼容端点实战指南

原创2026-10-13 23:43:392,122 阅读
文章标签:人工智能模型推理服务后端本地部署运维

GPUStack API 参考:内置 Swagger UI 的使用、认证与 OpenAI 兼容端点实战指南

GPUStack 作为一个面向 vLLM、SGLang 等高性能 AI 模型服务的 GPU 集群管理器,对外暴露了完整的 HTTP API:既包括管理集群、模型、用户、工作节点的 v2 管理接口,也包括可直接对接 OpenAI SDK 的 v1 推理接口。本文以 GPUStack 内置的 Swagger UI 为核心,系统讲解如何通过 <gpustack-server-url>/docs 浏览、调试全部 API,如何配置认证并关闭文档入口,以及如何利用 API Key 在 Swagger UI 之外直接调用 OpenAI 兼容端点。读完本文,你将能够独立完成 API 文档浏览、在线调试、鉴权配置与命令行调用。

GPUStack 内置 Swagger UI 页面

Swagger UI:GPUStack 的 API 参考入口

GPUStack 的服务端基于 FastAPI 构建(见 gpustack/server/app.py),因此在启动服务后,框架会自动生成并挂载一套交互式 OpenAPI 文档页面。按照官方文档 docs/api-reference.md 的说明,你只需在浏览器中访问:

<gpustack-server-url>/docs

即可打开 GPUStack 内置的 Swagger UI,在这里可以查看全部 API 的定义,也可以直接交互调试——展开任意接口、填入参数、点击 Execute 发起真实请求。

这套自动生成的文档以 OpenAPI(原 Swagger)规范为基础,其核心价值在于:

  • 接口清单完整:所有注册到路由上的端点都会出现在页面中,按标签(Tags)分组,例如 Users、API Keys、Models、Model Instances、Workers、Clusters、OpenAI-Compatible APIs 等;
  • 参数与响应结构一目了然:每个接口的请求参数、请求体 JSON Schema、响应模型、可能的错误码(如 401/403/404/422/500)都会自动渲染;
  • 可交互执行:登录后点击 Authorize 填入凭证,即可直接在页面中向真实服务发起请求并查看响应,是排查接口问题的高效工具。

三个文档入口:/docs、/redoc 与 /openapi.json

除了 Swagger UI,GPUStack 还同时提供另外两个标准入口。从 gpustack/server/app.py 的 FastAPI 初始化代码可以看到,应用创建时显式指定了三个 URL:

app = FastAPI(
    title="GPUStack",
    ...
    docs_url=None if (cfg and cfg.disable_openapi_docs) else "/docs",
    redoc_url=None if (cfg and cfg.disable_openapi_docs) else "/redoc",
    openapi_url=None if (cfg and cfg.disable_openapi_docs) else "/openapi.json",
)

三个入口的用途对比如下:

入口 URL 说明
Swagger UI /docs 交互式调试页面,适合人工浏览与在线执行
ReDoc /redoc 另一种样式的 API 文档页面,布局更适合快速检索与阅读
原始规范 /openapi.json 机器可读的 OpenAPI JSON 规范,适合程序化生成客户端、接入 API 网关或做接口测试

三者共享同一份由 FastAPI 自动生成的 OpenAPI 规范。如果你需要把 GPUStack 的接口接入自动化工具(例如基于 OpenAPI 生成 SDK,或导入 Postman/Apifox),直接拉取 /openapi.json 即可。

关闭 OpenAPI 文档:--disable-openapi-docs

在生产环境或对暴露面有严格要求的场景,你可能不希望把完整 API 文档对外公开。GPUStack 提供了显式的关闭开关。在启动命令中加入如下参数即可同时关闭上述三个入口:

gpustack start --disable-openapi-docs

对应的环境变量为 GPUSTACK_DISABLE_OPENAPI_DOCS,设置为 1 或 true 等效。该参数的官方说明见 gpustack/cmd/start.py:

Disable autogenerated OpenAPI documentation endpoints (Swagger UI at /docs, ReDoc at /redoc, and the raw spec at /openapi.json).

从源码逻辑可以看出,一旦启用该开关,docs_url、redoc_url、openapi_url 三者会同时被置为 None,也就是文档页面与原始规范都会停止对外提供;但已注册的 API 本身不受影响,路由依旧正常工作,只是不再暴露文档描述。相关命令行参数的完整说明也可查阅 docs/cli-reference/start.md。

在 Swagger UI 中完成认证(Authorize)

GPUStack 的绝大多数管理接口都要求认证。Swagger UI 右上角的 Authorize 按钮支持直接录入凭证,录入后点击 Execute 发起调试请求时会自动附带认证信息。

GPUStack 支持的认证方式(见 gpustack/api/auth.py)包括:

  • HTTP Bearer Token:最常用的方式,携带 Authorization: Bearer <token> 请求头,token 即你的 API Key 值;
  • HTTP Basic:使用用户名/密码(如 admin 与登录密码),也用于系统级 Worker/集群的旧式认证;
  • X-API-Key 请求头:将 API Key 直接放入名为 X-API-Key 的请求头;
  • Cookie 会话:浏览器登录后由 gpustack_session Cookie 自动携带,Swagger UI 同源调试时无需额外配置。

在 Swagger UI 的 Authorize 弹窗中,HTTPBearer 对应的 value 字段填入你的 API Key 完整值即可。API Key 的完整值形如 gpustack_<access_key>_<secret>(自动生成时由前缀 gpustack_、访问密钥与密钥段拼接而成,见 gpustack/security.py)。

获取 API Key

若你还没有 API Key,可在 GPUStack 界面的 Access Control > API Keys 页面创建,或直接调用管理 API 创建。创建后服务端只返回一次完整明文,之后仅显示掩码值,因此创建时务必妥善保存。API Key 的详细管理流程(创建、编辑权限、删除、吊销)见 docs/user-guide/api-key-management.md。

API Key 支持细粒度权限控制:选择 Platform Management 权限可获得平台管理类接口(用户、模型、工作节点等)的访问权;选择 Model Access 权限可获得推理接口访问权,并可进一步限定为 All models 或仅允许访问指定的模型列表。从源码实现看(gpustack/api/auth.py),API Key 的 scope 最终通过 management_scope 与 inference_scope 两个依赖注入到对应路由上:管理类路由挂载 Depends(management_scope),推理类路由挂载 Depends(inference_scope) 与 Depends(get_current_user),从而实现了管理面与推理面的权限隔离。

API 路由总览:从 /v2 管理面到 /v1 推理面

GPUStack 的 API 面分为几个清晰的层次,这一点在路由注册代码 gpustack/routes/routes.py 中有完整体现:

层次 前缀 用途 典型端点
管理 API /v2 集群资源与平台管理 /v2/models、/v2/workers、/v2/users、/v2/clusters、/v2/api-keys、/v2/gpu-instances 等
推理 API /v1 OpenAI 兼容推理 /v1/chat/completions、/v1/embeddings、/v1/models 等
推理 API(旧别名) /v1-openai 兼容旧版本客户端的固定子集 /v1-openai/chat/completions 等
认证相关 /auth、/token-auth 登录、SSO 回调、令牌校验 /auth/login、/token-auth
公开探针 /probes 健康检查等 探针端点

其中管理面内部又按权限分为三层(源码注释明确说明):

  • tenant_routers(租户感知):任何已登录用户可访问,处理器内部按租户上下文过滤数据(如模型、模型路由、GPU 设备等);
  • admin_routers(平台管理员):仅 is_admin 可访问,例如 /v2/users、/v2/organizations 等;
  • worker_client_router / cluster_client_router:供 Worker 与 Cluster 系统主体回调使用,通过 get_worker_principal / get_cluster_principal 依赖鉴权。

需要注意,/v2 管理接口的完整集合中,一部分属于“扩展 API”:默认不出现在 OpenAPI 文档中,仅当环境变量 GPUSTACK_EXTENDED_API_DOCS 设置为 1/true/yes 时才在 /docs 与 /openapi.json 中展示(见 gpustack/routes/routes.py)。端点本身始终挂载可用,只是文档表面默认隐藏——如果你在 Swagger UI 里找不到某些接口,可以先确认是否属于这一类。

OpenAI 兼容推理端点:/v1

GPUStack 的核心推理面是一套 OpenAI 兼容 API。从 gpustack/routes/openai.py 的路由注册逻辑可以看出,/v1 前缀下自动注册了如下端点集合(前缀列表定义在 gpustack/gateway/utils.py):

端点 方法 说明
/v1/models GET 列出当前用户可见且就绪的模型
/v1/chat/completions POST 对话补全(流式与非流式)
/v1/completions POST 文本补全
/v1/responses POST OpenAI Responses API 风格补全
/v1/embeddings POST 向量化
/v1/audio/transcriptions POST 语音转写
/v1/audio/speech POST 语音合成
/v1/audio/translations POST 语音翻译
/v1/images/generations POST 图像生成
/v1/images/edits POST 图像编辑
/v1/images/variations POST 图像变体
/v1/moderations POST 内容审核
/v1/rerank POST 重排序(额外挂载于 /v2/rerank)
/v1/videos/sync POST 同步视频生成

其中第一组端点(chat/completions、embeddings、audio、images 等)同时支持 /v1-openai 旧前缀(support_legacy=True),而 translations、variations、moderations 等仅挂载在 /v1。

/v1/models 的返回遵循 OpenAI 的 SyncPage 格式(object: "list"),且会按照调用者的可见范围过滤:管理员看到全部就绪的 ModelRoute,普通用户只看到自己可见的模型;若 API Key 被限制了 allowed_model_names,列表还会进一步收缩到允许的模型 ID(含组织前缀,例如 team-a/qwen3),这一行为在 docs/user-guide/api-key-management.md 中有明确说明,也与 gpustack/routes/openai.py 的实现一致。

用 curl 直接调用 OpenAI 兼容接口

Swagger UI 适合在线调试,但生产集成通常直接用命令行或 OpenAI SDK。下面以对话补全为例,展示如何用 API Key 调用 GPUStack 的 /v1/chat/completions(示例取自 docs/quickstart.md 与 docs/user-guide/api-key-management.md):

export GPUSTACK_API_KEY=your_api_key
curl http://your_gpustack_server_url/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{
    "model": "qwen3.5-0.8b",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Tell me a joke."
      }
    ],
    "stream": true
  }'

请求体中的 model 字段填写已部署模型的名称,stream: true 表示以 SSE 流式返回。GPUStack 的 /v1 端点本质上是反向代理:收到请求后,服务端会根据 model 解析模型路由,选择一个运行中的模型实例(经负载均衡,见 gpustack/routes/openai.py 与 gpustack/http_proxy/load_balancer.py),再把请求转发到对应 Worker 上承载该模型的 vLLM / SGLang 实例,最后把响应(或 SSE 流)透传回客户端。因此,对客户端而言 GPUStack 完全是一个 OpenAI 兼容的服务入口,可以直接替换 OpenAI SDK 的 base_url 使用。

错误响应格式

在 Swagger UI 中调试时,理解错误响应结构同样重要。GPUStack 的 API 有两套错误格式,分别对应管理面与推理面:

管理面错误(ErrorResponse),字段为 code / reason / message(见 gpustack/api/exceptions.py):

{
  "code": 404,
  "reason": "NotFound",
  "message": "Not found"
}

推理面错误(OpenAI 兼容格式 OpenAIAPIErrorResponse),字段为 error.message / error.type / error.code(见 gpustack/api/exceptions.py):

{
  "error": {
    "message": "Model not found",
    "code": 404,
    "type": "NotFound"
  }
}

推理面的异常处理通过 gpustack/api/exceptions.py 的 OpenAIAPIException handler 统一完成,保证与 OpenAI 官方错误格式兼容,方便现有 OpenAI 客户端直接消费。

常见的推理面错误场景包括:

场景 HTTP 状态码 说明
模型不存在或无权访问 404 Model not found(OpenAI 格式)
模型已部署但无可用实例 503 No running instances available
代理请求超时 504 Gateway timeout
认证失败 401 Unauthorized(管理面格式)
权限不足 403 Forbidden

小结

GPUStack 的 API 参考以内置 Swagger UI 为入口,提供 /docs、/redoc、/openapi.json 三个标准文档入口,覆盖从 /v2 管理面到 /v1 OpenAI 兼容推理面的完整接口体系。日常使用中,你可以:

  1. 在浏览器打开 <gpustack-server-url>/docs 浏览全部接口,点击 Authorize 录入 API Key 后在线调试;
  2. 通过 --disable-openapi-docs(或环境变量 GPUSTACK_DISABLE_OPENAPI_DOCS)在需要时关闭文档暴露面;
  3. 使用 gpustack_<access_key>_<secret> 格式的 API Key 搭配 Authorization: Bearer 请求头,直接以 curl 或 OpenAI SDK 调用 /v1/chat/completions 等推理端点,实现与既有应用的无缝集成。
登录后查看全文
gpustack