跳到主要内容

REST API 概述

NIM 提供完全兼容 OpenAI API 规范的 REST API，让您无需修改代码即可将现有 OpenAI 应用迁移至 NIM。

API 设计原则​

  • OpenAI 兼容：完全兼容 OpenAI Chat Completions、Completions 和 Embeddings API
  • 无状态：每个请求独立处理，服务端不维护会话状态
  • JSON 格式：请求体和响应体均使用 JSON 格式
  • 流式支持：通过 Server-Sent Events (SSE) 支持流式输出

基础 URL​

http://<host>:<port>/v1

默认端口为 8000。在生产环境中，建议在 NIM 前部署反向代理（Nginx/Envoy）并启用 HTTPS。

支持的端点​

端点方法说明
/v1/chat/completionsPOST对话式文本生成（主要推理端点）
/v1/completionsPOST文本补全（传统风格）
/v1/embeddingsPOST文本嵌入向量生成
/v1/messagesPOSTAnthropic Messages API 兼容端点
/v1/modelsGET列出可用模型
/v1/models/{model}GET获取指定模型信息
/v1/health/liveGET存活检查
/v1/health/readyGET就绪检查
/metricsGETPrometheus 指标（如启用）

请求格式​

所有 POST 请求需要设置 Content-Type: application/json 请求头。

示例请求​

OpenAI 兼容接口（/v1/chat/completions）：

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NGC_API_KEY" \
  -d '{
    "model": "meta/llama-3.1-8b-instruct",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "max_tokens": 100,
    "temperature": 0.7,
    "top_p": 0.9,
    "stream": false
  }'

Anthropic 兼容接口（/v1/messages）：

curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $NGC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "meta/llama-3.1-8b-instruct",
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

响应格式遵循 Anthropic Messages API 规范：

{
  "id": "msg-abc123",
  "type": "message",
  "role": "assistant",
  "model": "meta/llama-3.1-8b-instruct",
  "content": [
    {
      "type": "text",
      "text": "模型生成的内容..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 10,
    "output_tokens": 42
  }
}

通用请求参数​

下表列出所有推理端点共用的参数：

参数类型默认值说明
modelstring必填模型 ID（如 meta/llama-3.1-8b-instruct）
max_tokensinteger模型最大值生成 Token 的最大数量
temperaturefloat1.0采样温度，范围 [0, 2]。值越低输出越确定性
top_pfloat1.0核采样概率，范围 (0, 1]
top_kinteger-Top-K 采样，仅部分模型支持
ninteger1为每个输入生成的回复数量
streambooleanfalse是否启用流式输出
stopstring/array-停止序列，遇到时停止生成
presence_penaltyfloat0.0存在惩罚，范围 [-2, 2]
frequency_penaltyfloat0.0频率惩罚，范围 [-2, 2]
seedinteger-随机数种子，用于可复现生成
userstring-用户标识，用于审计日志

通用响应格式​

{
  "id": "chat-abc123def456",
  "object": "chat.completion",
  "created": 1735000000,
  "model": "meta/llama-3.1-8b-instruct",
  "system_fingerprint": "fp_abc123",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "模型生成的内容..."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 42,
    "total_tokens": 67
  }
}

finish_reason 取值说明​

值说明
stop模型自然结束生成，或遇到停止序列
length达到 max_tokens 限制
content_filter内容被安全过滤器拦截
null流式输出进行中

速率限制与配额​

NIM 本地部署无内置速率限制，但受限于以下资源：

  • GPU 显存：决定最大 KV Cache 容量，影响并发请求数
  • 计算能力：GPU TFLOPS 决定理论吞吐量上限

如需实现速率限制，建议在 NIM 前部署 API 网关（如 Kong、Nginx）。

SDK 支持​

由于 NIM 完全兼容 OpenAI API，可直接使用以下 SDK：

pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-required"  # 本地部署
)

版本兼容性​

NIM 版本OpenAI API 版本说明
1.0.xv1Chat Completions、Completions、Embeddings
1.1.xv1 + 扩展增加 Function Calling、JSON Mode
1.2.xv1 + 扩展增加 Vision、Structured Outputs
更多信息

查看推理端点了解各端点的详细参数说明，或查看错误代码了解如何处理 API 错误。

最后于 更新