🦄 refactor: 重构 Dockerfile 和 app.py，优化多阶段构建，增强模型加载和 API 逻辑，更新 README 文档以反映新特性

Dockerfile

@@ -1,30 +1,55 @@
-# 使用一个更安全、更小的官方基础镜像
-FROM python:3.12-slim
-
-# 更新系统包并安装 llama-cpp-python 所需的编译工具 (包括 git)
-RUN apt-get update && apt-get install -y --no-install-recommends build-essential cmake git && rm -rf /var/lib/apt/lists/*
-
-# 设置 Hugging Face 的缓存目录，避免权限问题
-ENV HF_HOME /code/cache
-
+# --- 第一阶段：构建环境 ---
+# 使用一个包含编译工具的镜像作为"构建器"
+FROM python:3.12-slim as builder
+
+# 设置环境变量，避免 frontend 弹窗交互
+ENV DEBIAN_FRONTEND=noninteractive
+
+# 安装 llama-cpp-python 所需的编译工具和依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+# 将 Python 包安装到一个独立目录，方便后续拷贝
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=off
+ENV PIP_DISABLE_PIP_VERSION_CHECK=on
+ENV PIP_DEFAULT_TIMEOUT=100
+ENV POETRY_VIRTUALENVS_CREATE=false
+ENV PATH="/app/bin:$PATH"
+
+WORKDIR /app
+COPY ./requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+
+# --- 第二阶段：最终运行环境 ---
+# 使用一个干净、轻量的镜像作为最终的运行环境
+FROM python:3.12-slim as final
+
+# 设置 Hugging Face 的缓存目录
+ENV HF_HOME=/data
 # 设置工作目录
-WORKDIR /code
+WORKDIR /app
 
-# 创建并授权缓存目录，以解决运行时权限问题
-RUN mkdir /code/cache && chmod 777 /code/cache
+# 从构建器阶段拷贝已安装的Python依赖包
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
 
-# 复制依赖文件并安装
-COPY ./requirements.txt /code/requirements.txt
-RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+# 创建并授权数据目录，用于模型缓存
+RUN mkdir /data && chmod 777 /data
 
 # 复制应用代码
-COPY ./app.py /code/app.py
+COPY ./app.py /app/app.py
 
 # 暴露容器端口
-EXPOSE 7860
+EXPOSE 8080
 
 # 启动应用的命令
 # 使用 uvicorn 运行 app.py 文件中的 app 对象
 # --host 0.0.0.0 使其可以从外部访问
-# --port 7860 监听指定的端口
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+# --port 8080 监听指定的端口
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]

README.md

@@ -1,7 +1,105 @@
----
-title: Big Model API Service
-sdk: docker
-app_port: 7860
----
+# 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
+```
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+### 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) 数据流。
+
+---
+*Powered by Sparkle-Server*

app.py

@@ -1,69 +1,131 @@
+import json
+import asyncio
+from typing import List, Optional, Dict, Any, Generator, AsyncGenerator
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
 from llama_cpp import Llama
 from huggingface_hub import hf_hub_download
-from fastapi import FastAPI
-from pydantic import BaseModel
+from sse_starlette.sse import EventSourceResponse
 
-# --- 模型加载逻辑 ---
-
-# 1. 配置模型和分词器
-# 使用最强大的、经过GGUF优化的Qwen3系列8B模型
-MODEL_ID = "unsloth/Qwen3-8B-GGUF"
-# 我们选择一个在性能和质量之间取得良好平衡的8位量化版本
-FILENAME = "Qwen3-8B-Q8_0.gguf"
-
-print(f"正在从Hub下载模型: {MODEL_ID}/{FILENAME}...")
-
-# 2. 从Hub下载GGUF模型文件
-model_path = hf_hub_download(repo_id=MODEL_ID, filename=FILENAME)
-
-print("模型下载完成。正在加载模型到内存...")
-
-# 3. 使用 llama-cpp-python 加载GGUF模型
-# n_ctx是上下文窗口大小，n_gpu_layers=0表示完全使用CPU
-model = Llama(model_path=model_path, n_ctx=4096, n_gpu_layers=0, verbose=True)
-
-print("模型加载完成。")
-
-
-# --- API 服务逻辑 ---
-
-# 4. 创建 FastAPI 应用实例
-app = FastAPI()
-
-
-# 5. 定义请求体的数据模型
-class GenerationRequest(BaseModel):
-    prompt: str
-    max_tokens: int = 128
 
+# --- 1. 配置管理 ---
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", extra="ignore"
+    )
 
-# 6. 定义 API 端点 (endpoint)
-@app.post("/generate")
-def generate_text(request: GenerationRequest):
+    MODEL_ID: str = Field(
+        "unsloth/Qwen3-8B-GGUF", description="Hugging Face上的模型仓库ID"
+    )
+    FILENAME: str = Field("Qwen3-8B-Q8_0.gguf", description="要下载的GGUF模型文件名")
+    N_CTX: int = Field(4096, description="模型的上下文窗口大小")
+    N_GPU_LAYERS: int = Field(0, description="要卸载到GPU的层数 (0表示完全使用CPU)")
+    N_THREADS: Optional[int] = Field(
+        None, description="用于推理的CPU核心数 (None为自动)"
+    )
+    VERBOSE: bool = Field(True, description="是否启用Llama.cpp的详细日志")
+
+
+settings = Settings()
+
+
+# --- 2. 模型加载 ---
+def load_model():
+    """从Hugging Face Hub下载并加载GGUF模型"""
+    print(f"正在从Hub下载模型: {settings.MODEL_ID}/{settings.FILENAME}...")
+    try:
+        model_path = hf_hub_download(
+            repo_id=settings.MODEL_ID, filename=settings.FILENAME
+        )
+    except Exception as e:
+        print(f"模型下载失败: {e}")
+        raise RuntimeError(f"无法从Hugging Face Hub下载模型: {e}")
+
+    print("模型下载完成。正在加载模型到内存...")
+    try:
+        model = Llama(
+            model_path=model_path,
+            n_ctx=settings.N_CTX,
+            n_gpu_layers=settings.N_GPU_LAYERS,
+            n_threads=settings.N_THREADS,
+            verbose=settings.VERBOSE,
+        )
+        print("模型加载完成。")
+        return model
+    except Exception as e:
+        print(f"模型加载失败: {e}")
+        raise RuntimeError(f"无法加载Llama模型: {e}")
+
+
+model = load_model()
+
+# --- 3. API 服务逻辑 ---
+app = FastAPI(
+    title="Sparkle-Server - GGUF 大模型 API",
+    description="一个基于 llama-cpp-python 和 FastAPI 的、兼容 OpenAI 格式的高性能LLM推理服务。",
+    version="1.0.0",
+)
+
+
+# --- 4. API 数据模型 (兼容 OpenAI) ---
+class ChatMessage(BaseModel):
+    role: str
+    content: str
+
+
+class ChatCompletionRequest(BaseModel):
+    messages: List[ChatMessage]
+    model: str = settings.MODEL_ID
+    max_tokens: int = 1024
+    temperature: float = 0.7
+    stream: bool = False
+
+
+# --- 5. 流式响应生成器 ---
+async def stream_generator(
+    chat_iterator: Generator[Dict[str, Any], Any, None],
+) -> AsyncGenerator[str, None]:
+    """将 llama-cpp-python 的输出流转换为 Server-Sent Events (SSE) 格式"""
+    for chunk in chat_iterator:
+        if "content" in chunk["choices"][0]["delta"]:
+            yield f"data: {json.dumps(chunk)}\n\n"
+            await asyncio.sleep(0)  # 允许事件循环处理其他任务
+
+
+# --- 6. API 端点 (兼容 OpenAI) ---
+@app.post("/v1/chat/completions")
+async def create_chat_completion(request: ChatCompletionRequest):
     """
-    接收一个 prompt 并返回模型生成的结果。
+    处理聊天补全请求，支持流式和非流式响应。
     """
-    print(f"接收到输入: {request.prompt}")
-
-    # 使用 Pydantic 模型获取数据
-    prompt = request.prompt
-    max_tokens = request.max_tokens
-
-    # 将用户的输入包装成一个指令提示，以引导模型进行问答
-    formatted_prompt = f"Human: {prompt}\nAI:"
-
-    # 调用GGUF模型生成文本
-    output = model(
-        formatted_prompt, max_tokens=max_tokens, stop=["Human:", "\n"], echo=False
-    )
-
-    result_text = output["choices"][0]["text"].strip()
-
-    print(f"生成结果: {result_text}")
-
-    return {"result": result_text}
+    if not request.messages:
+        raise HTTPException(status_code=400, detail="messages 列表不能为空")
+
+    try:
+        if request.stream:
+            # 流式响应
+            chat_iterator = model.create_chat_completion(
+                messages=request.dict()["messages"],
+                max_tokens=request.max_tokens,
+                temperature=request.temperature,
+                stream=True,
+            )
+            return EventSourceResponse(stream_generator(chat_iterator))
+        else:
+            # 非流式响应
+            result = model.create_chat_completion(
+                messages=request.dict()["messages"],
+                max_tokens=request.max_tokens,
+                temperature=request.temperature,
+                stream=False,
+            )
+            return result
+    except Exception as e:
+        print(f"处理请求时发生错误: {e}")
+        raise HTTPException(status_code=500, detail=f"内部服务器错误: {str(e)}")
 
 
 @app.get("/")
 def read_root():
-    return {"message": "大模型 API (GGUF版) 正在运行。请访问 /docs 查看 API 文档。"}
+    return {"message": "Sparkle-Server (GGUF版) 正在运行。请访问 /docs 查看 API 文档。"}

requirements.txt

@@ -2,4 +2,7 @@ torch==2.7.1
 llama-cpp-python==0.3.9
 huggingface-hub==0.33.0
 fastapi==0.115.13
-uvicorn[standard]==0.34.3 
+uvicorn[standard]==0.34.3
+pydantic-settings==2.10.1
+python-dotenv==1.1.1
+sse-starlette==2.3.6