Transformers 中的 Inkling 多模态 MoE 模型架构、推理配置与部署实战指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本文是基于 Hugging Face Transformers 当前仓库中 Inkling 模型文档 编写的一篇技术指南。它面向想要快速上手 Thinking Machines Lab 开源的通用多模态模型 Inkling 的开发者你将了解其“文本 图像 音频”统一建模的架构原理、如何在本地通过Pipeline与AutoModel完成图文对话、语音转录与推理链式生成reasoning以及如何用transformers serve一行命令把它以 OpenAI 兼容接口部署为在线服务。读完本文你既可以照抄配置代码直接运行也能从源码层面理解每一层混合注意力、稀疏 MoE、短卷积与多 token 预测MTP等关键结构在实际调用链中如何工作。配套源码位于 src/transformers/models/inkling/官方文档页为 docs/source/en/model_doc/inkling.md该模型由 Thinking Machines Lab 于 2026-07-15 贡献并合入本仓库。模型总览975B 参数的多模态 MoE 解码器Inkling 是一个通用多模态multimodal模型输入侧同时接受文本、图像、音频三种模态输出侧统一生成文本。根据官方模型文档 docs/source/en/model_doc/inkling.md 的介绍其核心结构是66 层 decoder-only transformer且采用**稀疏混合专家sparse MoE**的 FFN 骨干每个 token 会被路由到256 个专家中的 6 个同时还有2 个始终激活的共享专家shared experts总计975B 参数量而每个 token 实际激活的参数约为41B图像与音频输入先被投影到语言模型的嵌入空间中再与文本 token 交错interleave因此单个 checkpoint 即可对三种模态进行联合推理。这些官方 checkpoint 托管在 Thinking Machines Lab 组织名下示例中使用的模型标识如thinkingmachines/Inkling与量化版本thinkingmachines/Inkling-NVFP4。模型页面上的徽标也表明本仓库实现支持SDPAPyTorch scaled dot-product attention与张量并行Tensor parallelism。在仓库的 Auto API 注册中可以找到该模型完整的接入点src/transformers/models/auto/modeling_auto.py、src/transformers/models/auto/auto_mappings.py模型类型model_type配置类Auto 模型类inkling_mm_modelInklingConfigInklingModel/InklingForConditionalGenerationinkling_textInklingTextConfigInklingForCausalLM纯文本骨干inkling_audioInklingAudioConfig—inkling_visionInklingVisionConfig—对应的处理器也在 Auto API 中完成映射InklingProcessor关联 processing_auto.py 与 feature_extraction_auto.py、image_processing_auto.py。因此下面所有示例都能用AutoProcessorAutoModelForMultimodalLM直接加载。快速开始两种官方推荐的推理入口原文档 docs/source/en/model_doc/inkling.md 提供了两套完全对等的调用方式Pipeline与AutoModel。下面完整保留这两种写法并补充参数说明。方式一Pipeline最简路径image-text-to-textpipeline 会自动把多模态消息规整为模型输入适合快速验证。注意示例中传入了reasoning_effortmediumInkling 具备推理链reasoning开关可用low / medium / high之类的档位控制模型在给出答案前的思考深度该值由 checkpoint 的 chat template 定义并消费。from transformers import pipeline model_id thinkingmachines/Inkling-NVFP4 pipe pipeline(image-text-to-text, modelmodel_id) image_url ( https://huggingface.co/datasets/merve/vl-test-suite/ resolve/main/pills.jpg ) messages [ { role: user, content: [ { type: image, image: image_url, }, { type: text, text: Do components in this supplement interact with each other?, }, ], }, ] output pipe( messages, max_new_tokens2000, return_full_textFalse, reasoning_effortmedium, ) output[0][generated_text]关键参数解读max_new_tokens2000生成的最大新 token 数Inkling 的文本上下文很长见下文max_position_embeddings131072文档示例普遍给出较大的生成预算便于容纳推理链return_full_textFalse只返回新生成的部分不含输入消息reasoning_effortmedium通过 chat template 路由到生成参数控制推理链长度。方式二AutoModel更底层的控制需要精细控制预处理与采样时用AutoModelForMultimodalLMAutoProcessor。核心是processor.apply_chat_template(..., tokenizeTrue, return_tensorspt)它一次性完成chat template 展开、图像/音频解码与特征提取、soft-token 占位替换、文本分词输出可直接送进model.generate的张量字典。from transformers import AutoModelForMultimodalLM, AutoProcessor model_id thinkingmachines/Inkling-NVFP4 processor AutoProcessor.from_pretrained(model_id) model AutoModelForMultimodalLM.from_pretrained( model_id, device_mapauto, ) messages [ {role: system, content: You should only answer with a number.}, {role: user, content: What is 17 * 23?}, ] inputs processor.apply_chat_template( messages, add_generation_promptTrue, tokenizeTrue, return_dictTrue, return_tensorspt, reasoning_efforthigh, ).to(model.device) output model.generate(**inputs, max_new_tokens2000) generated_tokens output[0][inputs[input_ids].shape[1] :] print(processor.decode(generated_tokens, skip_special_tokensFalse))两个细节值得注意apply_chat_template返回return_dictTrue把各模态输入合并为字典合并逻辑见下文处理器一节随后.to(model.device)需要设备与device_mapauto一致解码生成结果时代码先按inputs[input_ids].shape[1]切掉提示词前缀只对增量 token 调用processor.decode。由于模型输出中可能保留思维过程标记或推理链内容直接打印原始输出再配合parse_response见下文解析是官方推荐的两段式流程。Notes文本 图像 / 文本 音频的具体调用图文推理 响应解析下面的完整示例来自文档“Notes”一节展示了parse_response的典型用法——模型可能把“思考过程”与“最终回答”都放进生成的文本中processor.parse_response(response)负责把二者剥离from transformers import AutoModelForMultimodalLM, AutoProcessor model_id thinkingmachines/Inkling processor AutoProcessor.from_pretrained(model_id) model AutoModelForMultimodalLM.from_pretrained( model_id, device_mapauto, ) image_url ( https://huggingface.co/datasets/merve/vl-test-suite/ resolve/main/pills.jpg ) messages [ { role: user, content: [ { type: image, image: image_url, }, { type: text, text: Do any of the components in this supplement interact?, }, ], }, ] inputs processor.apply_chat_template( messages, tokenizeTrue, add_generation_promptTrue, reasoning_effortmedium, return_dictTrue, return_tensorspt, ).to(model.device) input_len inputs[input_ids].shape[-1] outputs model.generate(**inputs, max_new_tokens2000) response processor.decode(outputs[0][input_len:], skip_special_tokensFalse) processor.parse_response(response)这里的image_url既可以是网络 URL也可以替换为本地路径或 PIL 图像对象——处理链路见 image_processing_inkling.py。文本 音频推理语音转录音频输入在消息中以{type: audio, audio: url/路径/数组}声明。下面来自原文档的示例演示了“将语音转录为文本”该任务同样经由apply_chat_template触发音频解码、log-mel 特征提取与量化from transformers import AutoModelForMultimodalLM, AutoProcessor model_id thinkingmachines/Inkling processor AutoProcessor.from_pretrained(model_id) model AutoModelForMultimodalLM.from_pretrained( model_id, device_mapauto, ) audio_url ( https://huggingface.co/datasets/merve/vl-test-suite/ resolve/main/example_audio.mp3 ) messages [ { role: user, content: [ {type: text, text: Transcribe the following speech to text.}, { type: audio, audio: audio_url, }, ], }, ] inputs processor.apply_chat_template( messages, tokenizeTrue, return_dictTrue, return_tensorspt, add_generation_promptTrue, ).to(model.device) input_len inputs[input_ids].shape[-1] outputs model.generate(**inputs, max_new_tokens512) response processor.decode(outputs[0][input_len:], skip_special_tokensFalse) processor.parse_response(response)两个任务在输入组织上完全一致区别仅在消息 content 的模态类型以及生成预算语音转录max_new_tokens512通常够用长推理链任务建议给到 2000。Serving用transformers serve一键部署 OpenAI 兼容服务原文档还给出了生产部署的最小路径——借助 Transformers 自带的transformers serveCLI一行命令即可把 Inkling checkpoint 启动为OpenAI 兼容的/v1HTTP 服务transformers serve thinkingmachines/Inkling-NVFP4服务启动后默认监听http://localhost:8000/v1可直接使用 OpenAI Python SDK 调用注意 base_url 与一个任意非空的 api_keyfrom openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyrandom_string) completion client.chat.completions.create( modelthinkingmachines/Inkling-NVFP4, messages[ { role: user, content: [ {type: text, text: What is in this image?}, { type: image_url, image_url: { url: https://huggingface.co/datasets/merve/vl-test-suite/resolve/main/pills.jpg }, }, ], } ], ) print(completion.choices[0].message.content)注意这里走的是 OpenAI 对话协议的image_url消息结构与本地Pipeline/AutoModel里的image键不同服务端会自动将其映射到 Inkling 的图像处理管线。多模态场景建议选择 NVFP4 等量化 checkpoint如示例中的Inkling-NVFP4以降低显存占用。配置类纵览四层配置结构Inkling 使用“顶层组合配置 三个子配置”的经典多模态布局全部定义在 configuration_inkling.py。文档中通过[[autodoc]]导出的类包括InklingConfig、InklingTextConfig、InklingAudioConfig、InklingVisionConfig。顶层InklingConfig对应model_type inkling_mm_model把三个子配置聚合起来text_config: InklingTextConfig | dict | Noneaudio_config: InklingAudioConfig | dict | Nonevision_config: InklingVisionConfig | dict | None以及模态边界 tokenimage_token_id200054、audio_token_id200053、image_bos_token_id200005、audio_bos_token_id200020。在其__post_init__中configuration_inkling.py会把 dict 形式的子配置实例化、把 checkpoint 顶层mtp_config块中携带的 MTP 字段如num_nextn_predict_layers、chain_hidden_post_norm、local_layer_ids合并进 text 子配置最后让两个子编码器的text_hidden_size对齐到文本骨干的hidden_size。从源码结构看InklingConfig对应 SGLang 参考实现中的InklingMMConfig见其auto_docstring的自定义简介。InklingTextConfig文本骨干参数下表汇总了 configuration_inkling.py 中定义的全部关键默认值多数与原文档自动生成的 docstring 一致参数默认值含义vocab_size201024词表大小unpadded_vocab_sizeNone当 checkpoint 的解嵌入矩阵行数未补齐到vocab_size时给出实际行数超出部分 logits 被丢弃大模型为200058hidden_size6144隐藏层维度num_hidden_layers66解码器层数num_attention_heads64全注意力层头数num_key_value_heads8全注意力层 KV 头数GQA 分组head_dim128全注意力层 Q/K 头维度swa_num_attention_heads64滑窗注意力SWA层头数swa_num_key_value_heads16滑窗层 KV 头数swa_head_dim128滑窗层 Q/K 头维度sliding_window_size512layer_types中为hybrid_sliding的层使用的滑窗大小d_rel16参与构造相对位置偏置的相对状态relative states的每头维度rel_extent1024相对位置偏置生效的回溯距离token 数超过则为 0log_scaling_n_floorNone全注意力层中 logits 开始对数放大的位置起点None表示禁用log_scaling_alpha0.1上述对数放大强度local_layer_idsNone使用滑窗注意力的层下标None时“索引不是 6 的倍数”的层默认使用滑窗layer_typesNone每层类型hybrid/hybrid_sliding推导自local_layer_idsmax_position_embeddings131072最大上下文长度checkpoint 以model_max_length上报经attribute_map映射rms_norm_eps1e-6RMSNorm 的 epsilonconv_kernel_size4短卷积short convolution核大小checkpoint 中名为sconv_kernel_sizeintermediate_size24576dense MLP 中间维度hidden_actsilu激活函数moe_intermediate_size3072MoE 单个专家 FFN 的中间维度n_routed_experts256路由专家数checkpoint 中名为num_local_expertsnum_experts_per_tok6每个 token 激活的路由专家数n_shared_experts2始终激活的共享专家数shared_expert_sinkTrue路由器是否把共享专家与路由专家一起参与打分作为 softmax 中的 sinkroute_scale8.0MoE 路由缩放logits_mup_width_multiplier24.0muP 宽度乘子语言建模头前除以它checkpoint 中名为embedding_multipliernum_mtp_layersNone多 token 预测层数None表示禁用 MTPchain_hidden_post_normFalseMTP 层间链式传递的 hidden states 是否在每层后归一化mtp_hidden_states_firstTrueMTP 层拼接输入时 hidden states 是否位于 token embeddings 之前bos/eos/pad_token_id1 / 2 / None特殊 token idInklingTextConfig.__post_init__里还做了两件事一是当layer_types未提供时把(i 1) % 6非零的所有层标成hybrid_sliding其余为hybrid这样 66 层中平均每 6 层出现一层全注意力层其余层以 512 滑窗做局部注意力二是当未提供mlp_layer_types时按dense_mlp_idx默认 0把前若干层标为 dense、其余为 sparse。此外每个解码器层内实际包含4 个卷积模块因此配置里固定number_of_conv_states 4每个卷积子模块需要独立的卷积状态缓存KV cache 需要据此分配空间。InklingAudioConfig 与 InklingVisionConfig音频子配置model_type inkling_audioconfiguration_inkling.pyn_mel_bins 80每帧 mel 频带数mel_vocab_size 256每个 mel 值被量化dMel 离散化后嵌入的桶数text_hidden_size 6144音频嵌入投影到的维度须与文本骨干一致。该配置通过attribute_map兼容参考实现命名num_codebooks - n_mel_bins、codebook_size - mel_vocab_size、hidden_size - text_hidden_size。视觉子配置model_type inkling_visionconfiguration_inkling.pytext_hidden_size 6144视觉特征经最后编码层投影到的文本骨干维度patch_size 40、temporal_patch_size 2、num_channels 3立方体 patch 划分参数hidden_size 1024、num_hidden_layers 24、num_attention_heads 16视觉塔自身的容量。处理器与模态接入原理InklingProcessorprocessing_inkling.py同时聚合了三种组件feature_extractor音频InklingFeatureExtractor、image_processorInklingImageProcessor与tokenizer是apply_chat_template背后的总调度器。Soft-token 占位与替换多模态输入统一建模的核心是把连续特征转成“软 token”处理器为每个图像 patch / 音频帧维护一个文本占位符实际输入时替换成等长的特征序列image_token |unused_200054|每个图像软 token 槽位的占位符会被图像特征替换audio_token |unused_200053|音频软 token 占位符image_bos_token |content_image|图像片段起始标记作为普通嵌入 token 保留audio_bos_token |content_audio_input|音频片段起始标记。替换逻辑见 processing_inkling.py图像侧根据image_inputs[num_patches]重复占位符音频侧根据audio_input_ids_mask计算有效帧数无 mask 时按帧维长度重复占位符。模型侧则用InklingModel.get_placeholder_mask找到占位 token再用视觉/音频编码器输出的连续特征张量替换其嵌入modeling_inkling.py 中InklingModel的前向逻辑。音频log-mel dMel 离散化InklingFeatureExtractorfeature_extraction_inkling.py把原始波形转成log10 空间的 mel 频谱默认sampling_rate16000、feature_size80、audio_token_duration_s0.05即每个音频 token 对应 50ms、STFT hop length 800 采样点、window_size_multiplier2.0窗长 100ms。窗函数为 periodic Hann 窗mel 滤波器组使用 Slaney 归一化随后对幅度谱做log10。特征提取器还额外产出input_features_mask用来标记批内 padding 帧并特意避开attention_mask命名以免与文本掩码冲突。真正“token 化”的离散化由InklingProcessor的dMel 量化完成把log10空间内clamp 到[dmel_min_value-7.0, dmel_max_value2.0]的 log-mel 值量化到num_dmel_bins16个离散桶得到整数audio_input_idsprocessing_inkling.py。这些整数 id 随后经过InklingAudioModel的嵌入层与InklingAudioModelEmbeddings含 fold-timespace-to-depth 折叠变成连续特征喂给文本骨干。这也解释了为何音频配置中mel_vocab_size256它为音频 token id 预留给足嵌入空间。图像方形 patch 划分与时空 patch 化InklingImageProcessorimage_processing_inkling.py以 torchvision 后端实现关键默认值resampleLANCZOS、mean/std 为 OpenAI CLIP 统计量、default_to_squareFalse不做强制方形 resize/center crop。preprocess要求把图像 resize 到正方形_validate_preprocess_kwargs中do_resize禁止为 False且宽高必须相等随后用自定义的divide_to_patches把图像按40x40patch 划分允许右/下边缘不足时补-1.0填充再做 rescale normalize并把张量在最后一个维度复制 2 份对应temporal_patch_size2与视觉配置中patch_size40、temporal_patch_size2呼应。处理结果包含pixel_values形状(batch, ..., 2, 40, 40, 3)重排与num_patches两个键其中num_patches被处理器标记为unused_input_names——它只在预处理阶段决定占位符长度不直接进入模型前向见 processing_inkling.py 的model_input_names。解码器层内部混合注意力 MoE 短卷积从源码结构modeling_inkling.py可以梳理出单层InklingDecoderLayer的实现要点这对理解上文配置参数意义很有帮助1. 混合注意力hybrid attention。每一层的注意力类型由config.layer_types决定InklingAttention初始化时读取modeling_inkling.py滑窗层使用swa_*头数与sliding_window_size全注意力层使用主配置并支持log_scaling_*对数缩放。层内 Q/K 各自接RMSNorm 归一化per-head 归一化故缩放因子取1/head_dim而非1/sqrt(head_dim)K、V 投影之后还各经过一个**短卷积short convolution**模块InklingShortConvolution核大小默认 4这本质上是一种轻量局部建模 / 状态压缩结构。相对位置偏置则由InklingRelativeLogits依据每层独立的d_rel相对状态与 Q/K 位置动态生成而非固定表项。2. 稀疏 MoE。InklingTopkRouter负责给每个 token 从 256 个专家中选出 top-6InklingExperts把专家权重存成 3D 张量并支持多种 kernel 后端源码中对专家前向使用了use_experts_implementation一类机制InklingSharedExperts提供始终激活的 2 个共享专家shared_expert_sink决定共享专家是否进入路由 softmax 充当 sink。MoE 层与 dense MLP 层按mlp_layer_types交替出现。3. 多 token 预测MTP。num_mtp_layers非 None 时解码器会在主序列之上级联若干 MTP 层同时预测后续多个 token可加速推理/改善长程生成相关结构参数chain_hidden_post_norm、mtp_hidden_states_first、mtp_local_layer_ids都在 text 配置中给出。4. 并行化支持。InklingTextConfig定义了完整的base_model_tp_plan/base_model_pp_plan/base_model_ep_planconfiguration_inkling.py张量并行下嵌入做embedding_rowwise、dense 线性层按 colwise/rowwise 切分、MoE 专家按moe_tp_experts分配EP 场景则走grouped_gemmep_router流水线并行把 66 层切分到多 stage。这是模型页面 Tensor parallelism 徽标的实现基础也意味着从仓库侧可以推断 Inkling 面向多卡大规模推理设计。模型对外暴露的推理接口包括InklingPreTrainedModel基类含_init_weights、纯文本InklingTextModel与InklingForCausalLM、音频塔InklingAudioModel、视觉塔InklingVisionModel以及组合后的InklingModel与InklingForConditionalGeneration——前者提供get_image_features/get_audio_features子模块入口后者把三种模态的特征在嵌入空间融合后逐 token 自回归生成。这些都对应原文档末尾通过[[autodoc]]导出的完整 API 清单。进一步验证与参考模型实现与导出类InklingForConditionalGeneration定义在 modeling_inkling.py文本因果模型InklingForCausalLM在其#L726附近组合模型InklingModel在#L1009附近源码由 modular_inkling.py 模块化生成模型文件头部注明了这一点——若需理解实现来源可对照阅读仓库 CI 也会校验二者一致utils/check_modular_conversion.py测试覆盖集中在 tests/models/inkling/包括test_modeling_inkling.py66 层结构、注意力实现与生成、test_image_processing_inkling.pypatch 划分、尺寸与num_patches行为与test_processing_inkling.pychat template 与 dMel 量化是验证上文所述配置与预处理逻辑行为的最佳入口。小结一句话总结使用流程加载AutoProcessorAutoModelForMultimodalLM→ 组消息role/content中混排文本、image、audio→apply_chat_template预处理 →model.generate→decodeparse_response需要线上服务时直接transformers serve。理解其架构时抓住三条主线即可66 层中“全注意力与 512 滑窗混合 K/V 短卷积”的注意力骨干、每 token 6/256 路由专家外加 2 共享专家的稀疏 MoE、以及“图像按 40×40 时空 patch、音频经 dMel 量化”后被投影进文本嵌入空间的统一多模态接入。上述所有实现、配置与测试均可在本仓库 src/transformers/models/inkling 与 tests/models/inkling 目录下进一步查看。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考