LlamaFactory 微调后的模型包装成 OpenAI API 格式教程（零基础版）

教程说明

本教程全程面向编程初学者，手把手教你将 LlamaFactory 微调完成的 Qwen2.5 模型，封装成标准 OpenAI 兼容的 API 接口。 ✅ 支持官方 openai 库调用 ✅ 支持流式 / 非流式输出 ✅ 兼容 EvalScope 等评估框架 ✅ 零改动适配 OpenAI 生态工具

一、前置准备

1. 基础条件

1. 已通过 LlamaFactory 完成模型微调（本教程以 Qwen2.5-0.8B-LoRA 为例）
2. 拿到微调后的模型文件夹路径（例如：E:\python_work...\out_qwen2.5_0.8b_lora）
3. 已安装 Python 3.9+ 环境

2. 创建虚拟环境（推荐，避免环境冲突）

打开终端，执行以下命令创建并激活虚拟环境：

# 创建虚拟环境（环境名：fastapi）
conda create -n fastapi python=3.10
# 激活环境
conda activate fastapi

3. 安装必备依赖

复制以下命令一键安装所有依赖（解决所有报错）：

先安装pytorch的gpu版本，

参考命令

pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124

然后安装以下库

pip install fastapi uvicorn transformers  pydantic accelerate python-dotenv evalscope openai

• fastapi/uvicorn：搭建 API 服务
• transformers/torch：加载微调模型
• accelerate：修复模型加载报错
• evalscope：后续模型评估使用
• openai：客户端测试使用

环境说明：

当前环境为 fastapi 虚拟环境（建议新手直接沿用此虚拟环境），所有包版本均经过验证，可完美适配 LlamaFactory 微调模型加载、FastAPI OpenAI 格式 API 部署及 EvalScope 评估，无版本冲突，可直接用于后续教程操作。核心包版本适配重点：

• torch 2.6.0+cu124：支持 CUDA 12.4（GPU 加速，若仅用 CPU 可忽略此版本限制）
• transformers 5.4.0：兼容 Qwen2.5 模型及 LlamaFactory 微调输出
• fastapi 0.135.3 + uvicorn 0.42.0：稳定搭建 API 服务
• accelerate 1.13.0：解决模型加载时 device_map 相关报错
• evalscope：已包含在命令中，适配本地 API 评估需求

# 安装pytorch后，再安装其余所有对应版本包（一键复制，无需修改）

pip install accelerate==1.13.0 annotated-doc==0.0.4 annotated-types==0.7.0 anyio==4.13.0 asttokens==3.0.0 certifi==2026.2.25 click==8.3.1 colorama==0.4.6 coloredlogs==15.0.1 comm==0.2.3 debugpy==1.8.16 decorator==5.2.1 exceptiongroup==1.3.1 executing==2.2.0 fastapi==0.135.3 filelock==3.25.2 flatbuffers==25.12.19 fsspec==2026.2.0 h11==0.16.0 hf-xet==1.4.3 httpcore==1.0.9 httpx==0.28.1 huggingface_hub==1.8.0 humanfriendly==10.0 idna==3.11 ipykernel==6.30.1 ipython==8.37.0 jedi==0.19.2 Jinja2==3.1.6 jupyter_client==8.6.3 jupyter_core==5.8.1 markdown-it-py==4.0.0 MarkupSafe==3.0.3 matplotlib-inline==0.1.7 mdurl==0.1.2 ml_dtypes==0.5.4 mpmath==1.3.0 nest-asyncio==1.6.0 networkx==3.4.2 numpy==2.2.6 onnx==1.20.1 onnxruntime-gpu==1.23.2 onnxslim==0.1.86 packaging==26.0 parso==0.8.5 pillow==12.1.1 pip==26.0.1 platformdirs==4.3.8 prompt_toolkit==3.0.51 protobuf==7.34.1 psutil==7.2.2 pure_eval==0.2.3 pydantic==2.12.5 pydantic_core==2.41.5 Pygments==2.19.2 pyreadline3==3.5.4 python-dateutil==2.9.0.post0 pywin32==311 PyYAML==6.0.3 pyzmq==27.0.2 regex==2026.3.32 rich==14.3.3 safetensors==0.7.0 sentencepiece==0.2.1 setuptools==82.0.1 shellingham==1.5.4 six==1.17.0 stack-data==0.6.3 starlette==1.0.0 sympy==1.13.1 tokenizers==0.22.2 tqdm==4.67.3 traitlets==5.14.3 transformers==5.4.0 typer==0.24.1 typing_extensions==4.15.0 typing-inspection==0.4.2 uvicorn==0.42.0 wcwidth==0.2.13 wheel==0.46.3 evalscope openai

二、核心步骤：编写 OpenAI 兼容 API 代码

这是最终版无报错代码，直接复制使用，仅需修改模型路径！

新建文件：main_lora.py（文件名固定，直接用）

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
import time
from typing import List, Optional
from fastapi.responses import StreamingResponse
import json
import asyncio

# 初始化 FastAPI 服务
app = FastAPI(title="Qwen2.5 OpenAI Compatible API", version="1.0")

# ===================== 【新手必改】配置你的微调模型路径 =====================
model_path = r"E:\python_work\large_language_model\llamfactory\LlamaFactory-main\out_qwen2.5_0.8b_lora"
# 自动识别设备（GPU/CPU）
device = "cuda" if torch.cuda.is_available() else "cpu"

# ===================== 加载微调模型和分词器 =====================
print("正在加载模型...")
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
# 修复 Qwen 模型必备配置
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "left"

# 加载模型（无报错版）
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    trust_remote_code=True,
    dtype=torch.bfloat16 if device == "cuda" else torch.float32,
    device_map="auto",
).eval()
print(f"模型加载完成！运行设备：{device}")

# ===================== 定义 OpenAI 标准请求格式 =====================
class Message(BaseModel):
    role: str
    content: str

class ChatCompletionRequest(BaseModel):
    model: str
    messages: List[Message]
    temperature: Optional[float] = 0.7
    max_tokens: Optional[int] = 1024
    top_p: Optional[float] = 0.95
    top_k: Optional[int] = 20
    stream: Optional[bool] = False

# ===================== OpenAI 标准接口（核心） =====================
@app.post("/v1/chat/completions")
async def chat_completions(request: ChatCompletionRequest):
    if not request.messages:
        raise HTTPException(status_code=400, detail="messages 不能为空")
    
    # 适配 Qwen 模型对话模板
    messages = [{"role": msg.role, "content": msg.content} for msg in request.messages]
    prompt = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True
    )

    # 模型推理
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    gen_kwargs = {
        "max_new_tokens": request.max_tokens,
        "temperature": request.temperature,
        "top_p": request.top_p,
        "top_k": request.top_k,
        "do_sample": True if request.temperature > 0 else False,
        "pad_token_id": tokenizer.pad_token_id,
        "eos_token_id": tokenizer.eos_token_id,
    }

    with torch.no_grad():
        outputs = model.generate(**inputs, **gen_kwargs)

    # 解码生成结果
    response_text = tokenizer.decode(outputs[0][len(inputs["input_ids"][0]):], skip_special_tokens=True)

    # 流式输出（兼容评估框架）
    if request.stream:
        async def stream_generator():
            yield f"data: {json.dumps({'choices': [{'delta': {'content': response_text}, 'index': 0}]})}\n\n"
            yield "data: [DONE]\n\n"
        return StreamingResponse(stream_generator(), media_type="text/event-stream")

    # 非流式输出（标准 OpenAI 格式）
    return {
        "id": f"chatcmpl-{int(time.time())}",
        "object": "chat.completion",
        "created": int(time.time()),
        "model": request.model,
        "choices": [
            {
                "message": {"role": "assistant", "content": response_text},
                "finish_reason": "stop",
                "index": 0
            }
        ],
        "usage": {
            "prompt_tokens": len(inputs["input_ids"][0]),
            "completion_tokens": len(outputs[0]) - len(inputs["input_ids"][0]),
            "total_tokens": len(outputs[0])
        }
    }

# 健康检查接口
@app.get("/")
async def root():
    return {"message": "Qwen2.5 微调模型 API 运行正常"}

新手唯一修改点

把代码中 model_path 替换为你自己微调后的模型文件夹路径！

三、启动 API 服务

1. 确保终端激活了 fastapi 虚拟环境
2. 执行启动命令：

uvicorn main_lora:app --host 0.0.0.0 --port 8000

启动成功标志

终端显示：

INFO:     Uvicorn running on http://0.0.0.0:8000
模型加载完成！运行设备：cuda/cpu

✅ 你的微调模型已经变成 OpenAI 标准 API 了！ 接口地址：http://localhost:8000/v1/chat/completions

四、测试 API 服务（验证是否可用）

新建测试文件：client_test.py，复制以下代码：

from openai import OpenAI

# 连接本地微调模型 API
client = OpenAI(
    base_url="http://localhost:8000/v1",  # 固定地址
    api_key="none"  # 本地模型无需真实密钥
)

# 发送请求（和调用 ChatGPT 代码完全一样）
response = client.chat.completions.create(
    model="local-qwen-lora",  # 任意填写
    messages=[
        {"role": "user", "content": "你好，介绍一下自己"}
    ]
)

# 打印结果
print("模型回复：", response.choices[0].message.content)

运行测试：

python client_test.py

✅ 输出模型回复 → 说明 API 部署成功！

五、进阶：对接 EvalScope 评估框架（可选）

如果你需要用 EvalScope 评估微调模型，只需修改评估代码的 3 个参数，对接本地 API：

评估代码核心修改

task_cfg = TaskConfig(
    # 1. 模型名：任意填写
    model='local-qwen-lora',
    # 2. API地址：你的本地模型接口
    api_url='http://localhost:8000/v1/chat/completions',
    # 3. API密钥：本地模型填 none
    api_key='none',
    eval_type='openai_api',  # 固定不变
    # ... 其他配置保持不变
)

完整评估服务代码

新建 eval_server.py，启动后即可通过 API 触发评估：

from fastapi import FastAPI, BackgroundTasks, HTTPException
from evalscope import TaskConfig, run_task
import uuid

app = FastAPI(title="本地模型评估服务")
task_status = {}

def run_eval_task(task_id: str):
    try:
        task_status[task_id] = "running"
        task_cfg = TaskConfig(
            model='local-qwen-lora',
            api_url='http://localhost:8000/v1/chat/completions',
            api_key='none',
            eval_type='openai_api',
            datasets=['general_mcq'],
            dataset_args={'general_mcq': {'local_path': 'dataset', 'subset_list': ['example_data']}},
            work_dir=f'outputs/local_model_eval_{task_id}',
            limit=10,  # 评估前10题
            eval_batch_size=1,
            generation_config={'max_tokens': 4096, 'temperature': 0.0},
            timeout=60000,
            stream=True,
        )
        run_task(task_cfg=task_cfg)
        task_status[task_id] = "success"
    except Exception as e:
        task_status[task_id] = f"failed: {str(e)}"

@app.post("/api/eval/maritime-bench")
async def start_eval(background_tasks: BackgroundTasks):
    task_id = str(uuid.uuid4())[:8]
    task_status[task_id] = "pending"
    background_tasks.add_task(run_eval_task, task_id)
    return {"task_id": task_id, "msg": "评估任务已启动"}

@app.get("/api/eval/status/{task_id}")
async def get_eval_status(task_id: str):
    return {"task_id": task_id, "status": task_status.get(task_id, "not found")}

启动评估服务：

uvicorn eval_server:app --host 0.0.0.0 --port 8001

六、新手常见报错解决（必看）

报错 1：ValueError: requires accelerate

✅ 解决：执行 pip install accelerate

报错 2：torch_dtype is deprecated

✅ 解决：使用教程中的代码（已修复为 dtype）

报错 3：模型加载失败

✅ 解决：检查 model_path 是否正确，路径不要有中文 / 空格

报错 4：端口被占用

✅ 解决：修改启动命令端口，例如 --port 8001

七、教程总结

1. 核心成果：LlamaFactory 微调模型 → 标准 OpenAI API 接口
2. 使用方式：和调用 ChatGPT 完全一致，零学习成本
3. 兼容生态：支持 OpenAI 客户端、EvalScope 评估、各类 ChatUI 工具
4. 新手友好：仅需修改模型路径，复制粘贴即可运行

本教程所有代码均为最终稳定版，无任何报错，直接使用即可！