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。

---

接口总览

分类	方法	路径	说明
推理 API	POST	/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/models	OpenAI 格式的模型列表
	POST	/v1/chat/completions	OpenAI 格式的对话补全接口

---

通用配置项 (Options Parameters)

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

参数	类型	默认值	说明
temperature	float	0.7	采样温度，越高生成内容越具创造性和随机性。
top_p	float	0.9	核采样概率（Top-P）。
top_k	int	40	Top-K 采样限制。
max_tokens	int	2048	单次生成最大 token 数量。
seed	int	-1	随机数种子（-1 表示完全随机）。
num_ctx	int	4096	上下文窗口大小限制。
num_parallel	int	4	并行推理槽数。
n_gpu_layers	int	-	GPU offload 层数限制（与 llama-server --n-gpu-layers 一致）。
cache_type_k	string	f16	KV Cache 中 K 键的量化类型，如 q8_0（压缩显存使用）。
cache_type_v	string	f16	KV Cache 中 V 值的量化类型，如 q8_0（压缩显存使用）。
dtype	string	f16	SafeTensors -> 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
  }'