【LLaMA-Factory 实战系列】四、API 篇 - 部署推理服务与批量调用实战
1. 引言
在前几篇教程中，我们已经掌握了如何使用 LLaMA-Factory 的 WebUI 和命令行，成功对 Qwen2.5-VL 多模态模型进行了 LoRA 微调与评估。现在，是时候将我们精心训练的模型投入实际应用了！将模型部署为标准化的 API 服务，是实现程序化调用、集成到现有业务流或构建交互式应用（如聊天机器人、自动化分析工具）的必经之路。
本教程将详细指导您如何使用 llamafactory-cli 将微调后的模型一键部署为兼容 OpenAI 格式的 API 服务。我们将深入探讨不同推理后端（huggingface, vllm, sglang）的优劣与选择，并提供一个完整的 Python 脚本，演示如何批量处理一个文件夹中的所有图片，实现自动化图文识别与描述。
2. 推理后端的选择与对比
在启动 API 服务之前，最关键的决策之一是选择合适的推理后端。LLaMA-Factory 在配置文件中通过 infer_backend 参数支持多种选项，它们在性能、易用性和资源消耗上各有侧重。
infer_backend 可选值：huggingface, vllm, sglang
下面是这三个主流后端的详细对比：
| 后端 | 核心特点 | 优点 | 缺点 | 安装命令 |
|---|---|---|---|---|
| huggingface | 默认选项，简单易用 | - 无需额外安装，开箱即用。 - 兼容性最好，支持几乎所有模型。 - 适合调试或低并发场景。 |
- 性能较低，尤其在处理批量请求时，吞吐量不高。 - 显存利用效率一般。 |
pip install -e .[torch]（已包含） |
| vllm | 高吞吐量推理引擎 | - 极高的吞吐量，通过 PagedAttention 等技术，能将 GPU 性能压榨到极致。 - 动态批处理，显著提升并发处理效率。 - 生产环境首选，是目前业界部署 LLM 的主流方案。 |
- 需要额外安装，可能存在兼容性问题。 - 对部分新模型的支持可能稍有延迟。 |
pip install vllm |
| sglang | 超高速度与复杂提示 | - 极快的推理速度，通过 RadixAttention 进一步优化。 - 原生支持复杂提示（如循环、条件判断），非常适合 Agent 等高级应用。 - 吞吐量与 vLLM 相当或更高。 |
- 相对较新，社区和生态仍在发展中。 - 同样需要额外安装，且可能对环境有特定要求。 |
pip install "sglang[srt_model]" |
选择建议：
- 初学者/快速验证：直接使用默认的 huggingface。
- 生产部署/高并发场景：强烈推荐 vllm，它能最大化您的硬件投资回报。
- 追求极致速度/Agent应用：可以尝试 sglang，它代表了推理引擎的前沿方向。
本教程将首先使用 huggingface 进行演示，因为其最为便捷。
3. 部署 API 推理服务
3.1 创建 API 配置文件
与训练类似，我们先在 my_configs/ 目录下创建一个 API 服务的配置文件。
my_configs/api_pokemon.yaml:
# model & adapter
model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct
adapter_name_or_path: saves/qwen2.5vl-3b-lora-pokemon/sft-cli
# template
template: qwen2_vl
# backend
infer_backend: huggingface # 更改为 vllm 或 sglang 以使用不同后端
# serving
trust_remote_code: true
说明：
model_name_or_path: 基础模型。adapter_name_or_path: 关键！指向我们第三篇教程中训练好的 LoRA 适配器路径。template: 必须与模型匹配。infer_backend: 我们在此选择 huggingface 作为开始。
3.2 启动 API 服务
在 LLaMA-Factory 根目录下，执行以下命令：
# 激活环境
conda activate llama_factory
# 启动 API 服务，指定端口为 8000
API_PORT=8000 llamafactory-cli api my_configs/api_pokemon.yaml
如果一切顺利，您将看到类似以下的输出，表明 API 服务已在 8000 端口成功启动：
INFO: Started server process [xxxxx]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
3.3 探索交互式 API 文档
服务启动后，在浏览器中打开 http://0.0.0.0:8000/docs。
您会看到一个由 FastAPI 自动生成的交互式 API 文档（Swagger UI）。这里列出了所有可用的 API 端点。我们最关心的是 /v1/chat/completions，它完全兼容 OpenAI 的 API 格式，极大地便利了客户端的开发。
4. 编写 Python 脚本进行批量调用
4.1 准备工作
- 在 LLaMA-Factory 根目录下创建一个名为
batch_test_images的文件夹。 - 向该文件夹中放入几张宝可梦的图片（例如
pikachu.png,bulbasaur.jpg等）。
4.2 批量调用脚本
创建一个名为 batch_inference.py 的 Python 文件，并填入以下内容：
import os
import requests
import base64
import json
from tqdm import tqdm
# --- 配置 ---
API_URL = "http://0.0.0.0:8000/v1/chat/completions"
IMAGE_FOLDER = "batch_test_images"
PROMPT = "Please describe this Pokémon's appearance, attributes, and characteristics in detail."
OUTPUT_FILE = "batch_results.json"
def encode_image_to_base64(image_path):
try:
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode('utf-8')
except IOError as e:
print(f"Error opening or reading image file {image_path}: {e}")
return None
def call_inference_api(prompt, base64_image):
headers = {"Content-Type": "application/json"}
payload = {
"model": "qwen",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": prompt
},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{base64_image}"
}
}
]
}
],
"max_tokens": 1024,
"temperature": 0.7,
"stream": False
}
try:
response = requests.post(API_URL, headers=headers, json=payload, timeout=60)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"API call failed: {e}")
return None
def main():
if not os.path.isdir(IMAGE_FOLDER):
print(f"Error: Image folder '{IMAGE_FOLDER}' not found.")
return
all_results = []
image_files = [f for f in os.listdir(IMAGE_FOLDER) if f.lower().endswith(('.png', '.jpg', '.jpeg'))]
if not image_files:
print(f"No images found in '{IMAGE_FOLDER}'.")
return
print(f"Found {len(image_files)} images. Starting batch inference...")
for image_name in tqdm(image_files, desc="Processing Images"):
image_path = os.path.join(IMAGE_FOLDER, image_name)
base64_image = encode_image_to_base64(image_path)
if not base64_image:
continue
result = call_inference_api(PROMPT, base64_image)
if result and "choices" in result and len(result["choices"]) > 0:
content = result["choices"][0]["message"]["content"]
print(f"\n--- Result for {image_name} ---")
print(content)
all_results.append({
"image": image_name,
"prompt": PROMPT,
"response": content
})
else:
print(f"\nFailed to get a valid response for {image_name}.")
all_results.append({
"image": image_name,
"prompt": PROMPT,
"response": "Error or empty response from API."
})
with open(OUTPUT_FILE, 'w', encoding='utf-8') as f:
json.dump(all_results, f, ensure_ascii=False, indent=4)
print(f"\nBatch processing complete. All results saved to {OUTPUT_FILE}.")
if __name__ == "__main__":
main()
4.3 运行脚本并查看结果
- 确保 API 服务仍在运行。
- 在终端中执行脚本：
python batch_inference.py
- 脚本会显示一个进度条，并逐一打印出每张图片的处理结果。
- 执行完毕后，项目根目录下会生成一个
batch_results.json文件，其中包含了所有图片的识别结果。
5. 总结
通过本教程，您已学会：
- 将微调模型部署为 API 服务
- 使用 OpenAI 风格 API 调用模型
- 实现图像批量推理与结果存储
核心要点：
- API 是桥梁：连接模型与实际应用。
- 后端定性能：合理选择 huggingface/vllm/sglang。
- 格式很重要：OpenAI 兼容格式，开发无缝衔接。
- 批量处理显神威：脚本驱动，效率爆表。