【LLM实战】如何把 LlamaFactory 接入统一网关？llm_AIO 项目实战保姆级教程

丨白色风车丨

217人浏览 · 2026-08-08 16:18:07

丨白色风车丨 · 2026-08-08 16:18:07 发布

摘要： 还在命令行里手动敲 llamafactory-cli 微调大模型吗？还在为多任务管理混乱、模型路径泄露、显存经常 OOM 而头疼吗？本文深入解析开源项目 llm_AIO，手把手教你如何将 LlamaFactory 封装成标准的 HTTP 服务，实现异步训练、模型合并、OpenAI 兼容推理的全流程闭环。

关键词： LlamaFactory, LLM微调, FastAPI, LoRA, AI网关, 大模型部署

一、为什么需要把 LlamaFactory 接入网关？

七、总结：它比原生 LlamaFactory 强在哪？

一、为什么需要把 LlamaFactory 接入网关？

原生 LlamaFactory 功能强大，但通常是通过命令行交互。在生产环境或多人协作场景下，直接暴露 CLI 存在几个痛点：

路径暴露风险：人人都需要知道服务器的绝对路径。
资源竞争：多人同时训练，显存直接爆炸，缺乏统一门禁。
管理混乱：训练任务（Job）状态难追踪，模型文件散落各处。

llm_AIO 项目解决了这个问题。它在 LlamaFactory 外面包了一层 FastAPI 网关，将其变成了一个标准的 Web 服务。

先统一一个概念（别叫错了）：
在本文的架构中：

训练 = CLI 子命令 train
合并 = CLI 子命令 export
对话 = 启动 api 子进程，通过 HTTP 交互（不是终端里的 chat 命令）

二、架构核心：网关怎么调用底层？

整个项目的调用链非常清晰：

text

[浏览器/前端]
    ↓ HTTP 请求 (POST /api/playground/llmfactory/train/lora)
[llm_AIO FastAPI 主服务 (端口 8000)]
    ↓ 调用 app/services/llmfactory_service.py
[底层 llmfactory 源码]
    ↓ 实际执行 llamafactory-cli train ...
[GPU 服务器开始炼丹]

关键点： 它并不依赖 pip install llamafactory，而是默认要求磁盘上有一个与 llm_AIO 同级的 llmfactory 源码目录。

预期目录结构：

text

你的工作区/
├── llm_AIO/          # 网关代码
└── llmfactory/       # LlamaFactory 源码 + 虚拟环境

三、环境配置速查（.env 设置）

在启动项目前，务必配好 .env 文件，核心变量如下：

变量名	作用	示例
`LLMFACTORY_COMMAND_PREFIX`	指向 LlamaFactory 的虚拟环境 bin 目录	`llmfactory/.venv/bin`
`LLMFACTORY_MODELS_DIR`	存放所有基座模型的父目录	`/data/models/`
`LLMFACTORY_MIN_FREE_VRAM_MIB`	显存门禁，低于此值拒绝新任务	`4096` (4GB)

四、数据从哪里来？（两种方式）

开始训练前，你得告诉系统数据在哪。项目支持两种方式，dataset_id 优先：

方式1：通过上传接口（推荐）

先用 POST /api/playground/datasets/upload 上传你的 JSON/CSV（Alpaca 或 ShareGPT 格式），系统会返回一个 dataset_id。训练时传这个 ID 即可，服务端会自动处理格式转换。

方式2：直接指定服务器路径

如果你已经把数据放在了服务器上，直接传 dataset 和 dataset_dir 参数。

五、 API 接口全攻略（实战流程）

统一访问前缀：http://你的IP:8000/api/playground/llmfactory

1. 第一步：选模型和模板

bash

# 查看可用基座模型
curl http://localhost:8000/api/playground/llmfactory/models

# 查看支持的对话模板（如 qwen, llama3）
curl http://localhost:8000/api/playground/llmfactory/templates

2. 第二步：发起训练（异步任务）

这里有三种模式：LoRA（低秩适配）、QLoRA（量化版）、Full（全量微调）。每种都分异步和同步接口。推荐用异步，防止 HTTP 超时。

bash

# 异步 LoRA 训练示例
curl -X POST http://localhost:8000/api/playground/llmfactory/train/lora \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "Qwen2-7B",
    "dataset_id": "你的数据集ID",
    "template": "qwen",
    "learning_rate": 5e-5,
    "num_train_epochs": 3
  }'

返回： {"job_id": "xxxx-xxxx", "status": "running"}

3. 第三步：查进度

拿到 job_id 后，你可以轮询进度，服务端会解析训练日志返回当前 Loss。

bash

curl http://localhost:8000/api/playground/llmfactory/train/jobs/{job_id}/progress

4. 第四步：模型合并（导出）

LoRA 训练完是“补丁”，需要合并进基座模型才能直接用。

bash

curl -X POST http://localhost:8000/api/playground/llmfactory/merge \
  -H "Content-Type: application/json" \
  -d '{"task_id": "刚才的job_id"}'

5. 第五步：启动推理服务（核心亮点）

这是接口最强大的地方。系统会内部启动一个 llamafactory-cli api 子进程，然后通过网关反向代理给你，接口完全兼容 OpenAI 格式。

启动：

bash

curl -X POST http://localhost:8000/api/playground/llmfactory/api/start \
  -H "Content-Type: application/json" \
  -d '{"model_path": "merged/你的模型_merged", "template": "qwen"}'

返回：

json

{
  "api_url": "http://你的网关IP:8000/api/playground/llmfactory/v1",
  "status": "running"
}

使用（完全兼容 OpenAI SDK）：
拿到 api_url 后，你可以直接在代码里像调用 ChatGPT 一样调用你的私有模型：

python

import openai
client = openai.Client(
    base_url="http://你的网关IP:8000/api/playground/llmfactory/v1", 
    api_key="not-needed"
)
response = client.chat.completions.create(
    model="default", 
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

停止： 用完记得释放显存！

bash

curl -X POST http://localhost:8000/api/playground/llmfactory/api/stop

六、附加功能：任务管理

系统会自动记录所有训练和合并任务，不怕丢。

bash

# 查看所有训练任务列表
curl http://localhost:8000/api/playground/llmfactory/train/jobs

# 下载训练好的模型文件（打包成 zip）
curl http://localhost:8000/api/playground/llmfactory/train/jobs/{job_id}/download -o my_model.zip

七、总结：它比原生 LlamaFactory 强在哪？

维度	原生 LlamaFactory (CLI)	llm_AIO 项目 (HTTP 网关)
使用方式	SSH 进服务器敲命令	前端页面 / curl / Python 脚本
模型管理	手动记录文件夹路径	模型 ID 化，不暴露服务器绝对路径
任务流	手动依次执行	链式调用：训练→合并→启动 API
资源控制	容易多人冲突导致 OOM	显存门禁，不足自动拦截
产物分发	scp 拷来拷去	直接提供 HTTP 下载链接
接口标准	无	完全兼容 OpenAI SDK