# llm-forge

**Repository Path**: ceagle/llm-forge

## Basic Information

- **Project Name**: llm-forge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: 001-admin-dashboard
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM-Forge

<p align="center">
  <strong>开箱即用的单机大模型推理平台</strong>
</p>

<p align="center">
  <a href="#特性">特性</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#安装">安装</a> •
  <a href="#配置">配置</a> •
  <a href="docs/">文档</a> •
  <a href="#贡献">贡献</a> •
  <a href="#许可证">许可证</a>
</p>

<p align="center">
  <a href="https://github.com/llm-forge/llm-forge/actions/workflows/ci.yml">
    <img src="https://github.com/llm-forge/llm-forge/actions/workflows/ci.yml/badge.svg" alt="CI Status">
  </a>
  <a href="https://pypi.org/project/llm-forge/">
    <img src="https://img.shields.io/pypi/v/llm-forge.svg" alt="PyPI Version">
  </a>
  <a href="https://github.com/llm-forge/llm-forge/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/llm-forge/llm-forge.svg" alt="License">
  </a>
  <a href="https://github.com/llm-forge/llm-forge/stargazers">
    <img src="https://img.shields.io/github/stars/llm-forge/llm-forge.svg?style=social" alt="Stars">
  </a>
</p>

---

## 概述

LLM-Forge 是一个开箱即用的单机大模型推理平台，让任何有 GPU/CPU 的机器都能在 5 分钟内运行一个生产级 LLM 推理服务。

### 特性

- 🚀 **开箱即用** - 一键部署，无需复杂配置
- 🎯 **单机部署** - 专注于单机场景，无需分布式知识
- 🔧 **多引擎支持** - vLLM (GPU) + llama.cpp (CPU/GPU)
- 🌐 **Web 管理后台** - 可视化管理模型、服务、配置
- 🔐 **安全可靠** - JWT 认证、审计日志、敏感数据脱敏
- 📊 **实时监控** - 服务状态、资源占用、日志流
- 🔄 **配置导入导出** - 一键备份和恢复系统配置
- 🇨🇳 **国内优化** - 预配置国内镜像源，加速下载

### 支持的推理引擎

| 引擎 | 平台 | 特点 |
|------|------|------|
| [vLLM](https://github.com/vllm-project/vllm) | NVIDIA GPU | 高吞吐量，PagedAttention |
| [llama.cpp](https://github.com/ggerganov/llama.cpp) | CPU/GPU | 轻量级，跨平台 |
| [TGI](https://github.com/huggingface/text-generation-inference) | NVIDIA GPU | HuggingFace 官方 |

---

## 快速开始

### 前置要求

- Python 3.11+
- Docker（用于运行推理服务）
- NVIDIA GPU（可选，用于 GPU 推理）

### 使用 Docker Compose（推荐）

> **注意**: 本项目使用 Docker Compose v2，命令为 `docker compose`（不带连字符）。

```bash
# 克隆仓库
git clone https://github.com/llm-forge/llm-forge.git
cd llm-forge

# 配置环境变量
cp .env.example .env
# 编辑 .env 设置 JWT_SECRET_KEY 和管理员密码

# 启动服务
docker compose up -d

# 访问
# 前端: http://localhost:3000
# API 文档: http://localhost:8080/docs
```

### 开发模式

```bash
# 安装 uv (Python 包管理器)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装后端依赖
uv sync --group dev

# 安装前端依赖
cd frontend && npm install && cd ..

# 启动后端
make run

# 启动前端 (新终端)
cd frontend && npm run dev
```

---

## 项目结构

```
llm-forge/
├── backend/                # FastAPI 后端
│   ├── src/
│   │   ├── api/           # API 路由
│   │   ├── models/        # ORM 模型
│   │   ├── schemas/       # Pydantic Schemas
│   │   ├── services/      # 业务逻辑
│   │   ├── db/            # 数据库配置
│   │   └── utils/         # 工具函数
│   └── tests/             # 测试文件
├── frontend/              # Vue 3 前端
│   ├── src/
│   │   ├── views/        # 页面组件
│   │   ├── components/   # 通用组件
│   │   ├── stores/       # Pinia 状态
│   │   └── api/          # API 调用
│   └── tests/            # 测试文件
├── docs/                  # 文档
├── data/                  # 数据目录（运行时）
├── pyproject.toml         # Python 项目配置
├── docker-compose.yml     # Docker 编排
└── Makefile               # 开发命令
```

---

## 配置

### 环境变量

创建 `.env` 文件：

```env
# JWT 认证
JWT_SECRET_KEY=your-secret-key-here
JWT_EXPIRE_MINUTES=30

# 管理员账户
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-password-here

# 数据目录
DATA_DIR=./data

# 模型下载令牌（可选）
HF_TOKEN=your-huggingface-token
MODELSCOPE_TOKEN=your-modelscope-token
```

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `JWT_SECRET_KEY` | JWT 签名密钥 | `change-me-in-production` |
| `JWT_EXPIRE_MINUTES` | Token 过期时间（分钟） | `30` |
| `ADMIN_USERNAME` | 管理员用户名 | `admin` |
| `ADMIN_PASSWORD` | 管理员密码 | `admin123` |
| `DATA_DIR` | 数据存储目录 | `./data` |
| `HF_TOKEN` | HuggingFace Token | （可选） |
| `MODELSCOPE_TOKEN` | ModelScope Token | （可选） |

---

## 功能模块

### 服务管理
- 查看推理服务状态（运行/停止/错误）
- 实时日志流（SSE）
- 服务重启/停止操作
- 资源使用监控（CPU/内存）

### 模型管理
- 模型注册与元数据管理
- 多源下载（HuggingFace/HTTP/ModelScope/Ollama）
- 下载进度追踪
- 模型状态校验

#### 模型下载示例

通过 Web 页面下载模型时，不同来源的填写方式如下：

**1. HuggingFace**

| 字段 | 填写内容 | 示例 |
|------|----------|------|
| 来源 | HuggingFace | - |
| 来源URL | 模型仓库 ID（作者/模型名） | `Qwen/Qwen2.5-7B-Instruct` |
| 模型名称 | 本地显示名称 | `qwen2.5-7b` |
| 存储路径 | 本地保存路径 | `/data/models/qwen2.5-7b` |
| 类型 | 模型类型 | Qwen/通义千问 |

**2. ModelScope（国内推荐）**

| 字段 | 填写内容 | 示例 |
|------|----------|------|
| 来源 | ModelScope | - |
| 来源URL | 模型 ID | `Qwen/Qwen2.5-7B-Instruct` |
| 模型名称 | 本地显示名称 | `qwen2.5-7b` |
| 存储路径 | 本地保存路径 | `/data/models/qwen2.5-7b` |
| 类型 | 模型类型 | Qwen/通义千问 |

**3. HTTP 直链**

| 字段 | 填写内容 | 示例 |
|------|----------|------|
| 来源 | HTTP 直链 | - |
| 来源URL | 下载链接 | `https://example.com/models/llama-2-7b.gguf` |
| 模型名称 | 本地显示名称 | `llama-2-7b` |
| 存储路径 | 本地保存路径 | `/data/models/llama-2-7b.gguf` |
| 类型 | 模型类型 | LLaMA |

**4. Ollama（最简单）**

| 字段 | 填写内容 | 示例 |
|------|----------|------|
| 来源 | Ollama | - |
| 来源URL | Ollama 模型名称 | `qwen2.5:7b` 或 `llama3.2` |
| 模型名称 | 本地显示名称 | `qwen2.5-7b` |
| 存储路径 | （自动管理，无需填写） | - |
| 类型 | 模型类型 | Ollama |

> **Ollama 说明**：
> - 需要先在服务器上安装 Ollama CLI
> - 模型存储由 Ollama 自动管理，无需指定路径
> - 支持的模型可访问 [Ollama 模型库](https://ollama.com/library) 查看

#### 常见模型下载示例

```
# Qwen2.5-7B (HuggingFace)
来源: HuggingFace
来源URL: Qwen/Qwen2.5-7B-Instruct
模型名称: qwen2.5-7b
存储路径: /data/models/qwen2.5-7b

# Llama 3.2 (Ollama)
来源: Ollama
来源URL: llama3.2
模型名称: llama3.2

# DeepSeek-V3 (ModelScope，国内推荐)
来源: ModelScope
来源URL: deepseek-ai/DeepSeek-V3
模型名称: deepseek-v3
存储路径: /data/models/deepseek-v3

# Qwen2.5-14B GGUF (HTTP)
来源: HTTP 直链
来源URL: https://huggingface.co/Qwen/Qwen2.5-14B-Instruct-GGUF/resolve/main/qwen2.5-14b-instruct-q4_k_m.gguf
模型名称: qwen2.5-14b-gguf
存储路径: /data/models/qwen2.5-14b-q4_k_m.gguf
```

### 引擎配置
- Docker 镜像版本管理
- 启动参数配置模板
- 参数校验与建议
- 使用次数统计

### 系统配置
- 环境变量管理
- 敏感信息脱敏
- 配置导入/导出
- 审计日志查询

---

## 开发命令

```bash
make help          # 显示所有命令
make install       # 安装依赖
make run           # 启动开发服务器
make test          # 运行测试
make lint          # 代码检查
make format        # 代码格式化
make docker-up     # 启动 Docker 服务
make docker-down   # 停止 Docker 服务
```

---

## API 文档

启动服务后访问：

- Swagger UI: http://localhost:8080/docs
- ReDoc: http://localhost:8080/redoc

---

## 文档

- [安装指南](docs/installation.md)
- [配置说明](docs/configuration.md)
- [API 文档](docs/api.md)
- [开发指南](docs/development.md)
- [部署指南](docs/deployment.md)
- [常见问题](docs/faq.md)
- [贡献指南](docs/contributing.md)
- [更新日志](docs/CHANGELOG.md)

---

## 技术栈

### 后端

| 技术 | 用途 |
|------|------|
| [FastAPI](https://fastapi.tiangolo.com/) | Web 框架 |
| [SQLAlchemy](https://www.sqlalchemy.org/) | ORM |
| [Pydantic](https://docs.pydantic.dev/) | 数据验证 |
| [Docker SDK](https://docker-py.readthedocs.io/) | 容器管理 |
| [JWT](https://jwt.io/) | 认证 |

### 前端

| 技术 | 用途 |
|------|------|
| [Vue 3](https://vuejs.org/) | 框架 |
| [TypeScript](https://www.typescriptlang.org/) | 类型安全 |
| [Element Plus](https://element-plus.org/) | UI 组件 |
| [Pinia](https://pinia.vuejs.org/) | 状态管理 |
| [Vite](https://vitejs.dev/) | 构建工具 |

---

## 贡献

我们欢迎所有形式的贡献！

### 贡献方式

- 🐛 提交 Bug 报告
- 💡 提出新功能建议
- 📝 改进文档
- 🔧 提交代码修复

### 开发流程

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/amazing-feature`）
3. 提交更改（`git commit -m 'feat: add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing-feature`）
5. 创建 Pull Request

详见 [贡献指南](docs/contributing.md)。

---

## 常见问题

### 1. 服务启动失败：GPU 内存不足

**错误信息**：
```
ValueError: Free memory on device cuda:0 (19.18/29.98 GiB) on startup is less than desired GPU memory utilization (0.9, 26.99 GiB)
```

**原因**：
- GPU 显存已被其他服务占用
- 配置的 GPU 显存使用率过高（默认 90%）
- vLLM 要求连续的 GPU 内存块，碎片化也会导致此问题

**解决方案**：

**方案一：降低 GPU 显存使用率（推荐）**

通过 Web 界面或 API 修改配置模板：
1. 访问"引擎配置"页面
2. 编辑相关配置模板
3. 将 GPU 显存使用率从 0.9 降低到 0.6-0.7

或通过 API 修改：
```bash
# 登录获取 token
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.access_token')

# 更新配置模板（假设模板 ID 为 4）
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8080/api/configs/templates/4 \
  -d '{"params": {"gpu_memory_utilization": 0.6, "max_model_len": 4096}}'
```

**方案二：停止其他占用 GPU 的服务**

```bash
# 查看运行中的服务
docker ps

# 停止不需要的服务
docker stop llm-forge-xxx-api

# 查看 GPU 使用情况
rocm-smi   # AMD GPU
nvidia-smi # NVIDIA GPU
```

**方案三：使用 GGUF 格式模型**

GGUF 模型内存占用更小，适合显存有限的场景：
- 使用 llama.cpp 引擎
- 选择量化版本（如 Q4_K_M、Q5_K_M）

### 2. 模型下载失败

**ModelScope 下载失败**：
- 确保 ModelScope SDK 已安装：`pip install modelscope`
- 使用正确的模型 ID 格式：`Qwen/Qwen2.5-7B-Instruct`

**ModelScope SDK 网络错误**：
- 错误信息：`AttributeError: 'NoneType' object has no attribute 'update'`
- 原因：未配置 MODELSCOPE_TOKEN 或网络不稳定
- 解决方案：
  ```bash
  # 方法一：手动使用 Python 下载
  pip install modelscope
  python3 -c "
  from modelscope import snapshot_download
  snapshot_download('Qwen/Qwen2.5-7B-Instruct', cache_dir='/data/models/qwen2.5-7b')
  "

  # 方法二：配置 MODELSCOPE_TOKEN
  # 编辑 .env 文件，设置 MODELSCOPE_TOKEN=your-token
  ```

**模型文件不完整**：
- 错误信息：`ValueError: Following weights were not initialized from checkpoint`
- 原因：下载中断导致 safetensors 文件缺失
- 检查方法：
  ```bash
  # 检查模型文件数量（Qwen2.5-7B 应有 4 个 safetensors 文件）
  ls /data/models/qwen2.5-7b/*.safetensors | wc -l
  # 应输出 4
  ```
- 解决方案：删除不完整模型重新下载
  ```bash
  rm -rf /data/models/qwen2.5-7b/
  # 然后通过 Web 界面或 API 重新下载
  ```

**HuggingFace 下载慢**：
- 配置镜像源或代理
- 考虑使用 ModelScope 下载国内镜像

**Ollama 下载失败**：
- 确保已安装 Ollama CLI：`curl -fsSL https://ollama.com/install.sh | sh`
- 检查 Ollama 服务是否运行：`ollama list`

### 3. 容器状态显示 Unhealthy

**原因**：
- 容器健康检查端口不匹配
- 服务启动时间过长

**解决方案**：
- 检查服务日志：`docker logs <container_name>`
- 确认模型路径正确
- 检查 GPU 是否可用

### 4. AMD GPU 服务无法启动

**检查 ROCm 环境**：
```bash
# 检查 ROCm 是否安装
rocm-smi

# 检查 Docker 是否支持 ROCm
docker run --rm -it --device /dev/kfd --device /dev/dri rocm/rocm-terminal rocm-smi
```

**使用正确的镜像**：
- AMD GPU 使用 `vllm/vllm-openai-rocm` 镜像
- NVIDIA GPU 使用 `vllm/vllm-openai` 镜像

---

## 安全

- JWT 认证，30 分钟会话超时
- 敏感字段自动脱敏
- 审计日志记录所有写操作
- 审计日志 append-only，保留 90 天

如果您发现安全漏洞，请参阅 [安全政策](SECURITY.md)。

---

## 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

---

## 致谢

- [vLLM](https://github.com/vllm-project/vllm) - 高性能推理引擎
- [llama.cpp](https://github.com/ggerganov/llama.cpp) - 轻量级推理引擎
- [FastAPI](https://fastapi.tiangolo.com/) - 优秀的 Web 框架
- [Element Plus](https://element-plus.org/) - 精美的 UI 组件

---

<p align="center">
  Made with ❤️ by LLM-Forge Team
</p>