metadata

title: Sparkle-Server - GGUF 大模型 API
emoji: ✨
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 8080
pinned: false

Sparkle-Server: 高性能 GGUF 大模型 API 服务

这是一个基于 FastAPI 和 llama-cpp-python 的高性能大语言模型（LLM）推理服务。它经过精心优化，旨在以最简单的方式部署基于 GGUF 格式的本地大模型，并提供兼容 OpenAI 的 API 接口。

✨ 特性

高性能推理: 底层使用 llama.cpp，在 CPU 上也能实现非常快速的文本生成。
兼容 OpenAI: 提供 /v1/chat/completions 接口，可以无缝对接到各种现有的 OpenAI 生态工具中。
流式响应: 支持流式（Server-Sent Events）输出，显著提升客户端的交互体验。
灵活配置: 所有关键参数（如模型ID、文件名、上下文长度等）均可通过环境变量或 .env 文件进行配置。
轻量级部署: 采用 Docker 多阶段构建，最终镜像体积小，安全且易于部署。
动态模型加载: 在服务启动时从 Hugging Face Hub 自动下载指定的 GGUF 模型。

🚀 快速开始

1. 准备工作

安装 Docker。
克隆本项目。

2. 配置模型 (可选)

您可以创建一个 .env 文件来配置您想要运行的模型。如果文件不存在，将使用默认的 Qwen3-8B 模型。

创建一个名为 .env 的文件，内容如下：

# Hugging Face 上的模型仓库 ID
MODEL_ID="Qwen/Qwen3-14B-GGUF"

# 要下载的 GGUF 模型文件名 (确保它在上面的仓库中存在)
FILENAME="Qwen3-14B-Q5_K_M.gguf"

# 模型的上下文窗口大小
N_CTX=4096

# 要卸载到 GPU 的层数 (0 表示完全使用CPU, -1 表示尽可能多地使用GPU)
N_GPU_LAYERS=0

3. 构建并运行 Docker 容器

在项目根目录下，执行以下命令：

docker build -t sparkle-server .
docker run -it -p 8080:8080 --rm --name sparkle-server sparkle-server

服务启动后，模型文件会自动从 Hugging Face Hub 下载并加载。您将在终端看到模型加载的日志。

🤖 API 使用示例

服务启动后，您可以访问 http://localhost:8080/docs 查看交互式 API 文档。

以下是使用 curl 的调用示例：

示例 1: 标准 JSON 响应

发送一个请求，并等待模型生成完整的回复。

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "你是一个乐于助人的AI助手。"
      },
      {
        "role": "user",
        "content": "你好！请给我讲一个关于宇宙的笑话。"
      }
    ],
    "max_tokens": 128,
    "temperature": 0.7,
    "stream": false
  }'

示例 2: 流式响应

发送一个请求，服务器会以数据流的方式实时返回生成的词语。

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "请写一首关于秋天的五言绝句。"
      }
    ],
    "max_tokens": 100,
    "stream": true
  }'

您将看到以 data: 开头的 Server-Sent Events (SSE) 数据流。

🧠 核心概念与配置建议

模型大小 vs. 上下文窗口

理解这两个核心概念对于成功运行大模型至关重要：

模型大小 (Model Size)
- 比喻: 这是您的"厨师"的"大脑容量"和"技能水平"。它由模型的参数数量（如 7B, 14B）和量化等级（如 Q4_K_M, Q8_0）决定。
- 影响: 决定了模型的"智力"和它在硬盘上以及加载到内存后所占用的固定内存大小。例如，Qwen3-8B-Q8_0 模型自身会稳定占用约 8.7 GB 内存。
上下文窗口大小 (Context Window / N_CTX)
- 比喻: 这是厨师的"操作台"大小。操作台越大，厨师能同时处理的食材（文本）就越多。
- 影响: 决定了模型在一次对话中能"记住"的文本长度。它会占用动态内存，窗口越大，消耗的内存越多。

总内存占用 ≈ 模型大小 (固定) + 上下文窗口内存 (动态) + 其他开销

如何根据您的内存进行配置？

您可以通过在 .env 文件中设置 N_CTX 变量来调整上下文窗口大小。以下是针对不同内存大小的推荐配置：

可用内存	推荐模型	`N_CTX` 推荐值	说明
8 GB	7B-Q4_K_M (~4.5 GB)	`2048`	足够进行日常问答和短文处理。
16 GB	8B-Q8_0 (~8.7 GB)	`8192`	推荐配置。能处理较长的文档分析和多轮对话。
32 GB	14B-Q6_K (~10.5 GB)	`16384`	适合需要更强模型能力和更长上下文的专业场景。
64 GB+	70B-Q4_K_M (~38 GB)	`32768+`	面向需要处理海量文本或进行复杂推理的企业级应用。

重要提示:

请确保为操作系统和其他程序留出至少 1-2 GB 的内存。
GGUF 模型主要在 CPU 上运行，因此内存大小 (RAM) 是最关键的限制因素。