GPUStack API 参考:内置 Swagger UI 的使用、认证与 OpenAI 兼容端点实战指南
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 文档浏览、在线调试、鉴权配置与命令行调用。
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_sessionCookie 自动携带,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 兼容推理面的完整接口体系。日常使用中,你可以:
- 在浏览器打开
<gpustack-server-url>/docs浏览全部接口,点击Authorize录入 API Key 后在线调试; - 通过
--disable-openapi-docs(或环境变量GPUSTACK_DISABLE_OPENAPI_DOCS)在需要时关闭文档暴露面; - 使用
gpustack_<access_key>_<secret>格式的 API Key 搭配Authorization: Bearer请求头,直接以 curl 或 OpenAI SDK 调用/v1/chat/completions等推理端点,实现与既有应用的无缝集成。
