【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 准备工作

1. 在 LLaMA-Factory 根目录下创建一个名为 batch_test_images 的文件夹。
2. 向该文件夹中放入几张宝可梦的图片（例如 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 Nonedef 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 Nonedef main():if not os.path.isdir(IMAGE_FOLDER):print(f"Error: Image folder '{IMAGE_FOLDER}' not found.")returnall_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}'.")returnprint(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:continueresult = 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 运行脚本并查看结果

1. 确保 API 服务仍在运行。
2. 在终端中执行脚本：

python batch_inference.py

3. 脚本会显示一个进度条，并逐一打印出每张图片的处理结果。
4. 执行完毕后，项目根目录下会生成一个 batch_results.json 文件，其中包含了所有图片的识别结果。

5. 总结

通过本教程，您已学会：

• 将微调模型部署为 API 服务
• 使用 OpenAI 风格 API 调用模型
• 实现图像批量推理与结果存储

核心要点：

• API 是桥梁：连接模型与实际应用。
• 后端定性能：合理选择 huggingface/vllm/sglang。
• 格式很重要：OpenAI 兼容格式，开发无缝衔接。
• 批量处理显神威：脚本驱动，效率爆表。