InternVL3_5-14B-Pretrained 生产部署指南:LMDeploy 与 vLLM 搭建 OpenAI 兼容 API 服务
InternVL3_5-14B-Pretrained 生产部署指南:LMDeploy 与 vLLM 搭建 OpenAI 兼容 API 服务
本文以 InternVL3_5-14B-Pretrained 多模态大模型为例,介绍如何用 LMDeploy 和 vLLM 完成生产部署,用一条命令搭建 OpenAI 兼容 API 服务,覆盖硬件选型、环境准备、服务启动、API 调用与常见问题排查,帮助新手快速把 14B 视觉语言模型上线。
一、先认识模型:15.1B 参数的多模态基础模型
InternVL3_5-14B-Pretrained 是 InternVL3.5 系列中 14B 规格的多模态持续预训练(CPT)检查点,采用经典的 "ViT–MLP–LLM" 架构:视觉编码器为 InternViT-300M(448px 输入),语言模型为 Qwen3-14B,两者经 MLP 投影层桥接。
| 关键信息 | 数值 |
|---|---|
| 总参数量 | 约 15.1B(0.3B 视觉 + 14.8B 语言) |
| 权重体积(bf16) | 约 30.2GB,分 7 个 safetensors 分片 |
| 上下文长度 | 最大 40960,建议服务配置 32768(32K) |
| 精度 | bfloat16 |
| 硬件建议 | 30B 及以下规格单卡 A100(80G)即可部署,14B 推荐 tp=1 |
💡 选型提示:
Pretrained版本仅完成持续预训练,适合微调、二次训练与下游适配;如果目标是直接对外提供高质量对话服务,可优先评估同系列的 Instruct / CascadeRL 完整版权重,本指南的部署流程对全系列通用。
仓库内除 7 个权重分片外,还包含模型运行所需的关键文件:
- config.json:模型主配置,可见
InternVLChatModel架构、max_position_embeddings: 40960、动态分辨率(dynamic_image_size: true)等参数 - modeling_internvl_chat.py、modeling_intern_vit.py:自定义模型实现,推理时需启用
trust_remote_code - conversation.py:对话模板(
template: internvl2_5) - model.safetensors.index.json:权重分片索引(total_size 约 30.2GB)
- generation_config.json、tokenizer_config.json:生成与分词配置
二、环境准备与模型下载
1. 硬件与基础环境
- 1 张 A100/H100(80G)或 2 张 40G 级显卡(
tp=2) - CUDA 11.8+ / 12.x,Python 3.10+,
transformers>=4.52.1(官方明确要求,低于此版本模型无法正常工作)
2. 安装部署框架(二选一或都装)
# LMDeploy 路线
pip install "lmdeploy>=0.9.1" openai
# vLLM 路线
pip install vllm
3. 下载模型权重(约 30GB,建议用浅克隆节省时间)
git clone --depth 1 https://gitcode.com/OpenGVLab/InternVL3_5-14B-Pretrained
三、LMDeploy 一键部署 OpenAI 兼容服务(推荐)
LMDeploy 把多模态推理抽象成与纯 LLM 相同的推理管线,其 api_server 一条命令即可打包出 OpenAI 接口兼容的 RESTful 服务,详见 README.md 部署章节:
lmdeploy serve api_server /path/to/InternVL3_5-14B-Pretrained \
--server-port 23333 --tp 1 --backend pytorch
常用启动参数速查:
| 参数 | 说明 | 推荐值 |
|---|---|---|
--server-port |
服务端口 | 23333(可自定义) |
--tp |
张量并行卡数(8B/14B 为 1,38B 为 2,241B 为 8) | 1 |
--session-len |
单会话上下文长度 | 32768 |
--backend |
推理后端 | pytorch |
验证服务是否就绪:
curl http://localhost:23333/v1/models
用 OpenAI SDK 发起调用(官方示例见 README.md#service):
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="http://localhost:23333/v1")
model_name = client.models.list().data[0].id
response = client.chat.completions.create(
model=model_name,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "describe this image"},
{"type": "image_url",
"image_url": {"url": "<图片URL或Base64 Data URI>"}},
],
}],
temperature=0.8,
top_p=0.8,
)
print(response.choices[0].message.content)
多图场景下,按 Image-1: <image> 编号传入即可;多图会显著增加输入 token,记得调大 --session-len。
四、备选方案:用 vLLM 部署
vLLM 在纯文本吞吐上表现优异,且同样暴露 /v1/chat/completions 等 OpenAI 兼容端点。官方 README 指出:多数情况下 LMDeploy 与 vLLM 均可用于 InternVL3.5 系列部署。vLLM 路线更推荐搭配 HF 标准格式权重(InternVL3_5-14B-HF)使用:
vllm serve /path/to/InternVL3_5-14B-HF \
--max-model-len 32768 --port 8000
启动后通过 http://localhost:8000/v1/chat/completions 调用,参数体系与上文完全一致,客户端代码无需改动。
五、生产环境最佳实践 ⚙️
- 推理参数:开启 Thinking 模式(设置官方 R1 system prompt)时,官方建议
do_sample=True、temperature=0.6,以缓解复读问题 - 显存不足:优先调小图片动态切块数
max_num(默认 12)与session-len,其次增大tp - 安全:生产环境务必配置 API Key 鉴权,服务不要裸露在公网,网关层做限流
- 监控:用
nvidia-smi或 Prometheus 监控 GPU 利用率与显存,定期巡检/v1/models健康检查 - 版本兼容:升级
transformers前先在测试环境验证,避免破坏自定义模型加载
常见问题排查:
| 现象 | 原因与解决 |
|---|---|
| 加载模型报架构/属性错误 | transformers 版本低于 4.52.1,升级后重试 |
| 找不到自定义模型类 | 确认加载时启用 trust_remote_code=True |
| 启动即 OOM | 单卡显存不足,改 tp=2 或降低上下文长度 |
| 请求 404 | 核对路径是否为 /v1/chat/completions,端口是否与启动参数一致 |
| 输出重复 | 按上文调整采样参数(do_sample=True、temperature=0.6) |
六、关键文件索引 📂
| 文件 | 作用 |
|---|---|
| config.json | 模型总配置(架构、LLM/视觉子配置) |
| configuration_internvl_chat.py | 自定义 Config 类 |
| modeling_internvl_chat.py | 对话模型主实现 |
| modeling_intern_vit.py | InternViT 视觉编码器实现 |
| conversation.py | 对话模板定义 |
| model.safetensors.index.json | 权重分片索引 |
| README.md | 官方快速开始与部署文档 |
总结
用一条 lmdeploy serve api_server 命令,InternVL3_5-14B-Pretrained 即可在单卡 A100 上变成标准 OpenAI 兼容 API 服务;追求更高文本吞吐可切换 vLLM + HF 格式权重。记住三件事:transformers 不低于 4.52.1、14B 规格 tp=1、上下文按 32K 规划,多模态模型服务上线就完成了一大半。