跳到主要内容

REST API 参考

CSGLite 提供了符合 Ollama 及 OpenAI 规范的 REST API，供第三方应用、前端界面或自动化脚本接入。API 服务随 csghub-lite serve 启动，默认监听端口为 11435。

基本信息​

  • 默认基地址: http://localhost:11435
  • 默认请求格式: Content-Type: application/json
  • 流式响应: 默认使用 SSE（Server-Sent Events）规范返回，格式为 text/event-stream。

接口总览​

分类方法路径说明
推理 APIPOST/api/chat交互式对话补全（支持多轮对话与流式/非流式）
POST/api/generate文本生成补全（支持提示词输入与流式/非流式）
模型管理GET/api/tags列出本地所有已下载的模型
POST/api/show显示特定模型的详细元数据
POST/api/pull从平台下载模型（支持流式显示文件下载进度）
DELETE/api/delete从本地磁盘删除指定模型
服务管理GET/api/health检查 API 服务健康状态
GET/api/ps查看当前正在内存/显存中运行的模型
POST/api/stop卸载/停止当前正在运行的模型，释放内存
OpenAI 兼容GET/v1/modelsOpenAI 格式的模型列表
POST/v1/chat/completionsOpenAI 格式的对话补全接口

通用配置项 (Options Parameters)​

对于推理接口 (/api/chat & /api/generate & /v1/chat/completions)，您可以在请求体中传入 "options" 对象来自定义推理行为：

参数类型默认值说明
temperaturefloat0.7采样温度，越高生成内容越具创造性和随机性。
top_pfloat0.9核采样概率（Top-P）。
top_kint40Top-K 采样限制。
max_tokensint2048单次生成最大 token 数量。
seedint-1随机数种子（-1 表示完全随机）。
num_ctxint4096上下文窗口大小限制。
num_parallelint4并行推理槽数。
n_gpu_layersint-GPU offload 层数限制（与 llama-server --n-gpu-layers 一致）。
cache_type_kstringf16KV Cache 中 K 键的量化类型，如 q8_0（压缩显存使用）。
cache_type_vstringf16KV Cache 中 V 值的量化类型，如 q8_0（压缩显存使用）。
dtypestringf16SafeTensors -> GGUF 转换时的输出精度类型，可选：f32, f16, bf16, q8_0 等。

推理接口详解​

1. 对话补全：POST /api/chat​

请求体示例​

{
  "model": "Qwen/Qwen3-0.6B-GGUF",
  "messages": [
    {"role": "system", "content": "你是一个专业的编程助手。"},
    {"role": "user", "content": "写一段 Python 快速排序代码。"}
  ],
  "stream": true,
  "options": {
    "temperature": 0.5,
    "max_tokens": 1024
  }
}
  • messages 结构: 数组形式，每个消息包含 "role"（可选：system, user, assistant）和 "content"（消息正文）。
  • stream: 默认为 true。若设为 false，则在模型全部生成结束后返回单次 JSON 响应。

流式响应示例 (SSE)​

data: {"model":"Qwen/Qwen3-0.6B-GGUF","message":{"role":"assistant","content":"好的"},"done":false,"created_at":"2026-03-11T00:43:14.832Z"}

data: {"model":"Qwen/Qwen3-0.6B-GGUF","message":{"role":"assistant","content":"，为您提供排序代码"},"done":false,"created_at":"2026-03-11T00:43:14.839Z"}

data: {"model":"Qwen/Qwen3-0.6B-GGUF","done":true,"created_at":"2026-03-11T00:43:14.930Z"}

非流式响应示例​

{
  "model": "Qwen/Qwen3-0.6B-GGUF",
  "message": {
    "role": "assistant",
    "content": "这里是您的 Python 快速排序代码...\n"
  },
  "done": true,
  "created_at": "2026-03-11T00:43:14.930Z"
}

2. 文本生成：POST /api/generate​

请求体示例​

{
  "model": "Qwen/Qwen3-0.6B-GGUF",
  "prompt": "用一句话写一首关于编程的诗",
  "stream": false
}

非流式响应示例​

{
  "model": "Qwen/Qwen3-0.6B-GGUF",
  "response": "代码如画卷，逻辑舞动在黑夜之中。",
  "done": true,
  "created_at": "2026-03-11T00:43:32.343Z"
}

模型与服务管理接口详解​

3. 健康检查：GET /api/health​

响应​

{"status": "ok"}

4. 获取本地已下载模型：GET /api/tags​

响应​

{
  "models": [
    {
      "name": "Qwen/Qwen3-0.6B-GGUF",
      "model": "Qwen/Qwen3-0.6B-GGUF",
      "size": 639466546,
      "format": "gguf",
      "modified_at": "2026-03-11T00:42:14.856Z"
    }
  ]
}

5. 查看模型详细信息：POST /api/show​

请求​

{"model": "Qwen/Qwen3-0.6B-GGUF"}

响应​

{
  "modelfile": "",
  "details": {
    "name": "Qwen/Qwen3-0.6B-GGUF",
    "model": "Qwen/Qwen3-0.6B-GGUF",
    "size": 639466546,
    "format": "gguf",
    "modified_at": "2026-03-11T00:42:14.856Z"
  }
}

6. 下载模型（流式进度）：POST /api/pull​

请求​

{"model": "Qwen/Qwen3-0.6B-GGUF"}

响应 (SSE)​

data: {"status":"pulling Qwen/Qwen3-0.6B-GGUF"}

data: {"status":"downloading Qwen3-0.6B-Q8_0.gguf","digest":"Qwen3-0.6B-Q8_0.gguf","total":639446688,"completed":1048576}

data: {"status":"success"}

7. 删除本地模型：DELETE /api/delete​

请求​

{"model": "Qwen/Qwen3-0.6B-GGUF"}

响应​

{"status": "deleted"}

8. 获取当前加载运行中的模型：GET /api/ps​

响应​

{
  "models": [
    {
      "name": "Qwen/Qwen3-0.6B-GGUF",
      "model": "Qwen/Qwen3-0.6B-GGUF",
      "size": 639466546,
      "format": "gguf",
      "expires_at": "2026-03-11T00:48:14.930Z"
    }
  ]
}

提示: expires_at 指明该模型默认在内存中的到期时间（如果在 5 分钟内没有新请求，将会自动释放资源）。

9. 停止运行模型（手动卸载）：POST /api/stop​

请求​

{"model": "Qwen/Qwen3-0.6B-GGUF"}

响应​

{"status": "stopped"}

OpenAI 兼容接口示例​

1. Python 客户端集成示例​

from openai import OpenAI

# 基础 URL 配置，无需 API 密钥（可填写任意非空占位符）
client = OpenAI(base_url="http://localhost:11435/v1", api_key="unused")

response = client.chat.completions.create(
    model="Qwen/Qwen3-0.6B-GGUF",
    messages=[
        {"role": "system", "content": "You are a translator."},
        {"role": "user", "content": "Translate 'Hello, world!' to Chinese."}
    ],
    stream=False
)

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

2. cURL (OpenAI 兼容聊天接口)​

curl http://localhost:11435/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B-GGUF",
    "messages": [{"role": "user", "content": "你好！"}],
    "stream": false
  }'