概述

DeepShield 提供完全兼容 OpenAI 的 API 接口，支持流式和非流式响应、自动故障切换和 Token 用量统计。只需将 base_url 指向 DeepShield 服务器即可使用。

  • Base URL：http://<host>:9090/v1
  • 主要端点：POST /v1/chat/completions
  • 健康检查：GET /health

认证

所有 API 请求需要通过 Bearer Token 认证。在 HTTP 请求头中添加：

HTTP
Authorization: Bearer YOUR_API_KEY

API Key 可以在对话页面点击左下角用户名查看。注册用户将自动分配一个唯一的 API Key。

Chat Completions

创建一个聊天补全请求。

请求

HTTP
POST /v1/chat/completions
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求体参数

参数类型必填说明
modelstring是模型名称，如 deepshield-chat
messagesarray是消息列表，每条包含 role 和 content
streamboolean否是否使用流式响应，默认 false
temperaturenumber否采样温度 0-2，默认 1
max_tokensinteger否最大生成 token 数

请求示例

JSON
{
  "model": "deepshield-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false
}

响应示例

JSON
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "deepshield-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

流式响应

将 stream 设置为 true 启用 Server-Sent Events (SSE) 流式响应。每个事件以 data: 前缀发送，最后以 data: [DONE] 结束。

JSON (SSE chunk)
data: {
  "id": "chatcmpl-xxx",
  "object": "chat.completion.chunk",
  "choices": [
    {
      "index": 0,
      "delta": {"content": "Hello"},
      "finish_reason": null
    }
  ]
}

data: [DONE]

错误处理

API 使用标准 HTTP 状态码。错误响应格式：

JSON
{
  "error": {
    "message": "invalid API key",
    "type": "authentication_error"
  }
}
状态码说明
400请求参数无效
401认证失败（API Key 无效或缺失）
429请求过于频繁（匿名用户限制）
502上游服务不可用

Python SDK

使用官方 openai Python SDK：

BASH
pip install openai

非流式调用

PYTHON
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:9090/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="deepshield-chat",
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
)
print(response.choices[0].message.content)

流式调用

PYTHON
stream = client.chat.completions.create(
    model="deepshield-chat",
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript SDK

BASH
npm install openai
JAVASCRIPT
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: "http://localhost:9090/v1",
    apiKey: "YOUR_API_KEY",
});

const response = await client.chat.completions.create({
    model: "deepshield-chat",
    messages: [
        { role: "user", content: "Hello!" }
    ],
});
console.log(response.choices[0].message.content);

cURL

BASH
curl http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepshield-chat",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'