InternVL3_5-30B-A3B-MPO 配置参数与API完整指南:config.json关键项与chat函数逐项讲解

原创2026-10-16 09:30:561,909 阅读

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

🔑 几个新手最容易踩坑的点:

  1. 多图独立场景必须传 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 的断言)。
  2. 纯文本对话直接把 pixel_values 传 None,<image> 占位符也不用写。
  3. <image> 会被替换为 256×切块数 个 <IMG_CONTEXT> token(见 modeling_internvl_chat.py),所以输入越长,上下文占用越大。
  4. 流式输出可用 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"。

六、常用文件与模块路径速查

七、常见问题 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 集成到自己的应用中 🚀。

登录后查看全文
InternVL3_5-30B-A3B-MPO