README.md

---
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](https://www.docker.com/products/docker-desktop/)。
- 克隆本项目。

### 2. 配置模型 (可选)

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

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

```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 容器

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

```bash
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 响应

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

```bash
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: 流式响应

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

```bash
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. 上下文窗口

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

1.  **模型大小 (Model Size)**
    *   **比喻**: 这是您的"厨师"的"大脑容量"和"技能水平"。它由模型的参数数量（如 7B, 14B）和量化等级（如 Q4_K_M, Q8_0）决定。
    *   **影响**: 决定了模型的"智力"和它在硬盘上以及加载到内存后所占用的**固定内存大小**。例如，`Qwen3-8B-Q8_0` 模型自身会稳定占用约 8.7 GB 内存。

2.  **上下文窗口大小 (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) 是最关键的限制因素。

---
*Powered by Sparkle-Server*