InternVL3_5-30B-A3B-MPO 配置参数与API完整指南:config.json关键项与chat函数逐项讲解
InternVL3_5-30B-A3B-MPO 配置参数与API完整指南:config.json关键项与chat函数逐项讲解
InternVL3_5-30B-A3B-MPO 是 InternVL3.5 多模态大模型家族中完成 MPO(混合偏好优化)阶段的 30B MoE 版本,本文以 config.json 为线索,逐项讲解配置参数含义与 chat 函数 API 用法,帮助新手快速上手该模型的调用与部署。
一、先认识 InternVL3_5-30B-A3B-MPO
📦 模型采用经典的 ViT–MLP–LLM 三段式结构:
| 组成部分 | 说明 | 参数量 |
|---|---|---|
| 视觉编码器 InternViT | 24 层 ViT,image_size=448,patch_size=14 |
0.3B |
| 像素压缩模块 pixel shuffle + MLP | 以 downsample_ratio=0.5 将视觉 token 压缩 1/4 |
极小 |
| 语言模型 Qwen3-30B-A3B(MoE) | 48 层、128 个专家、每 token 激活 8 个专家 | 30.5B(激活 3B) |
其中 MPO 是 Cascade RL 训练流程里的离线 RL 阶段(CPT → SFT → MPO),因此该版本在完成监督微调后又经过偏好对齐,推理风格比 Instruct 版本更稳定。
仓库内除模型权重外,还包含自定义建模代码(通过 trust_remote_code=True 加载):
# 如需本地获取仓库
git clone https://gitcode.com/OpenGVLab/InternVL3_5-30B-A3B-MPO
二、仓库文件结构速览
| 文件 | 作用 |
|---|---|
| config.json | 主配置文件,声明视觉/语言双配置 |
| configuration_internvl_chat.py | InternVLChatConfig 配置类定义 |
| modeling_internvl_chat.py | 模型主体,含 chat、batch_chat、generate |
| configuration_intern_vit.py / modeling_intern_vit.py | InternViT 视觉编码器定义 |
| conversation.py | 对话模板(internvl2_5) |
| tokenizer_config.json / vocab.json / merges.txt | 分词器(基于 Qwen3 词表,151936) |
| added_tokens.json | 新增的 <IMG_CONTEXT>、<img> 等视觉特殊 token |
| vision.safetensors | 视觉编码器权重 |
| layer-0-ep-0-of-1.safetensors 等 | 语言模型按层分片的 MoE 权重(ep 即 expert parallel 分片) |
| others.safetensors | 嵌入层、归一化等其余参数 |
| model.safetensors.index.json | 权重分片索引 |
三、config.json 关键配置项逐项讲解
config.json 顶层是一个"组合式"配置:vision_config 与 llm_config 分别描述视觉塔与语言模型,外层参数则控制 InternVL 特有的动态分辨率行为。
3.1 顶层关键参数
| 参数 | 值 | 含义 |
|---|---|---|
architectures |
InternVLChatModel |
模型入口类,对应 modeling_internvl_chat.py |
auto_map |
— | 注册 AutoConfig/AutoModel 到自定义代码,因此加载时必须 trust_remote_code=True |
model_type |
internvl_chat |
组合模型标识 |
template |
internvl2_5 |
对话模板,决定 prompt 拼装格式,定义于 conversation.py |
force_image_size |
448 | 每块图像 patch 固定为 448×448 |
dynamic_image_size |
true |
启用动态高分辨率:按原图宽高比切分为多个 448 方格 |
use_thumbnail |
true |
切块数 >1 时追加一张全图缩略图,帮助全局理解 |
min_dynamic_patch / max_dynamic_patch |
1 / 12 | 动态切块数量范围(单图最多 12 块) |
downsample_ratio |
0.5 | pixel shuffle 下采样比例,视觉 token 数量压缩为 1/4 |
ps_version |
v2 |
pixel shuffle 版本(v2 会正确还原高宽顺序,见 modeling_internvl_chat.py) |
select_layer |
-1 | 取 ViT 最后一层输出;改为其他层号可取中间层特征 |
torch_dtype |
bfloat16 |
权重以 BF16 存储,加载时也建议用 torch.bfloat16 |
use_backbone_lora / use_llm_lora |
0 | LoRA 开关,推理默认关闭 |
💡 每个图像块(patch)对应 448/14 × 448/14 × 0.5² = 256 个视觉 token,该值由 modeling_internvl_chat.py 中的 num_image_token 自动计算。
3.2 llm_config:语言模型(Qwen3-30B-A3B MoE)
| 参数 | 值 | 说明 |
|---|---|---|
architectures |
Qwen3MoeForCausalLM |
语言模型架构 |
num_hidden_layers |
48 | 层数(与仓库中 layer-0 ~ layer-47 分片一一对应) |
hidden_size |
2048 | 隐层维度 |
intermediate_size |
6144 | 稠密 MLP 中间维度 |
moe_intermediate_size |
768 | 每个 MoE 专家的 FFN 维度 |
num_experts |
128 | 每层专家总数 |
num_experts_per_tok |
8 | 每 token 激活专家数(即"A3B":约 3B 激活参数) |
norm_topk_prob |
true |
专家路由权重归一化 |
router_aux_loss_coef |
0.001 | 路由负载均衡辅助损失系数(仅训练用) |
num_attention_heads / num_key_value_heads |
32 / 4 | GQA:4 组 KV 头,降低显存带宽压力 |
max_position_embeddings |
40960 | 最大上下文 40K token |
rope_theta |
1000000.0 | RoPE 基频 |
vocab_size |
151936 | 词表大小,与 vocab.json 一致 |
torch_dtype |
bfloat16 |
计算精度 |
其余如 do_sample、temperature、top_k 等是 HuggingFace 的生成默认值,实际生成以调用 chat 时传入的 generation_config 为准。
3.3 vision_config:视觉编码器(InternViT-300M)
| 参数 | 值 | 说明 |
|---|---|---|
model_type |
intern_vit_6b |
ViT 配置类型 |
num_hidden_layers |
24 | 视觉塔层数 |
hidden_size / intermediate_size |
1024 / 4096 | ViT 隐层与 FFN 维度 |
image_size |
448 | 输入分辨率 |
patch_size |
14 | 每个 patch 14×14 像素 |
num_attention_heads |
16 | 注意力头数 |
use_flash_attn |
true |
视觉侧启用 Flash Attention |
tie_word_embeddings |
true |
ViT 分类头与词嵌入共享(此处无实际词嵌入) |
权重文件对应关系:视觉部分见 vision.safetensors,语言部分见 layer-0-ep-0-of-1.safetensors 起的 48 个分片及 others.safetensors。
四、chat 函数 API 参数逐项讲解
核心对话入口是 modeling_internvl_chat.py 中的 model.chat(...),参数如下:
| 参数 | 类型 | 说明 |
|---|---|---|
tokenizer |
tokenizer | 由 AutoTokenizer.from_pretrained(path, trust_remote_code=True, use_fast=False) 加载 |
pixel_values |
Tensor / None |
图像张量(切块后的 stack),纯文本对话传 None |
question |
str | 用户输入;含图时需在文本中写 <image> 占位符 |
generation_config |
dict | 传给 generate 的生成参数,如 max_new_tokens、do_sample |
history |
list / None |
多轮历史 [(question, answer), ...],首轮传 None |
return_history |
bool | True 时返回 (response, history) 二元组,便于续接下一轮 |
num_patches_list |
list / None |
多图/视频场景下,每张图像各自的切块数量列表;单图可省略 |
IMG_START_TOKEN 等 3 个 |
str | <img> / </img> / <IMG_CONTEXT> 特殊 token,一般保持默认 |
verbose |
bool | True 时打印切块数与最终 prompt |
🔑 几个新手最容易踩坑的点:
- 多图独立场景必须传
num_patches_list。例如两张图分别切成 2、3 块,则传<a href="https://link.gitcode.com/i/1b9ebdbe0e3252324afa1fed1f8a11f1" target="_blank">2, 3],并保证len(pixel_values) == sum(num_patches_list)(见 [modeling_internvl_chat.py 的断言)。 - 纯文本对话直接把
pixel_values传None,<image>占位符也不用写。 <image>会被替换为 256×切块数 个<IMG_CONTEXT>token(见 modeling_internvl_chat.py),所以输入越长,上下文占用越大。- 流式输出可用
TextIteratorStreamer放进generation_config中实现逐字打印(README 中有完整示例)。
最简调用示例(单图单轮):
model = AutoModel.from_pretrained(
"OpenGVLab/InternVL3_5-30B-A3B-MPO",
torch_dtype=torch.bfloat16,
low_cpu_mem_usage=True,
use_flash_attn=True,
trust_remote_code=True,
device_map="auto",
).eval()
tokenizer = AutoTokenizer.from_pretrained(
"OpenGVLab/InternVL3_5-30B-A3B-MPO",
trust_remote_code=True, use_fast=False)
generation_config = dict(max_new_tokens=1024, do_sample=True)
question = "<image>\n请简要描述这张图片。"
response = model.chat(tokenizer, pixel_values, question, generation_config)
batch_chat 批量推理接口
multi-样本批量接口 model.batch_chat(...) 参数与 chat 类似,区别是:
questions为问题列表,pixel_values为所有图像切块拼接后的张量;- 不支持多轮(传
history会直接报错); - 必须传
num_patches_list指明每条样本的切块数。
五、generation_config 推荐配置
| 场景 | 推荐参数 | 说明 |
|---|---|---|
| 日常对话/描述 | dict(max_new_tokens=1024, do_sample=True) |
平衡速度与流畅度 |
| Thinking 深度思考模式 | dict(max_new_tokens=8192, do_sample=True, temperature=0.6) |
官方建议开启思考模式时使用采样并设 temperature=0.6,避免重复 |
| 流式输出 | 追加 streamer=streamer |
配合 TextIteratorStreamer 使用 |
模型默认以 BF16 运行(config.json 中 torch_dtype: "bfloat16"),30B-A3B 规模可部署在单张 A100 上;显存不足时可改用 8-bit 量化(load_in_8bit=True)或多卡 device_map="auto"。
六、常用文件与模块路径速查
- 主配置:config.json
- 配置类源码:configuration_internvl_chat.py
- 模型主体与对话 API:modeling_internvl_chat.py
- 前向传播(视觉特征注入文本 embedding):modeling_internvl_chat.py
- 视觉特征提取与像素压缩:modeling_internvl_chat.py
- 对话模板
internvl2_5:conversation.py - 视觉特殊 token 表:added_tokens.json
- 权重索引:model.safetensors.index.json
七、常见问题 FAQ
Q1:加载时报 trust_remote_code 相关错误?
该仓库使用自定义建模代码(auto_map 机制),必须显式传 trust_remote_code=True,且建议使用 transformers ≥ 4.52.1。
Q2:图片切块太多,上下文不够用?
可通过 dynamic_preprocess(..., max_num=6) 之类的参数把 max_dynamic_patch 调小,牺牲部分细节换取更短序列。
Q3:A3B 是什么意思?
即 30B 总参数、每 token 仅激活约 3B 参数的 MoE 设计(128 专家选 8),推理速度快、显存友好,适合单卡部署。
Q4:MPO 版本和最终版(无后缀)该选哪个? 不确定时选无后缀的完整版本(含 CascadeRL 全流程);需要研究离线 RL 中间态时再选 MPO 版本。
掌握以上 config.json 关键项与 chat 函数参数后,你就可以完成从模型加载、图像预处理到多轮对话的完整链路,快速把 InternVL3_5-30B-A3B-MPO 集成到自己的应用中 🚀。