Spaces:
Running
Running
| 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* | |