企业官网建设流程全解析

• 大模型
• 多模态
• 推理模型

本文围绕开源模型仓库 Agnes-AI/Agnes-3.0-Flash（本仓库即该模型的开放权重发布目录）展开，系统梳理 Agnes-3.0-Flash Preview 的混合注意力架构、评测口径、Transformers/SGLang 两套加载与部署路径、推理强度与工具调用机制，以及硬件与推理参数建议。读完本文，你将掌握如何在本仓库权重基础上完成单卡与张量并行推理、多模态输入处理和 OpenAI 兼容接口对接的全套实战方案。

说明：本文所述规格、评测成绩与配置均针对本仓库发布的Agnes-3.0-Flash Preview 开放权重 checkpoint，与 production/API 版 Agnes 3.0 Flash（1M 上下文）不是同一份权重，评测成绩不能互相套用。

一、模型版本澄清：Preview 与 production/API 的区别

本仓库发布的是 Agnes 3.0 Flash 的早期开放权重 Preview checkpoint，它在三个关键维度上与 Artificial Analysis 页面所列的新版 production/API checkpoint 不同：

两点需要特别留意：

1. 本仓库最初以Agnes-3.0-Flash名称发布，遗漏了Preview后缀；现在模型卡已明确标识为Agnes-3.0-Flash Preview，本文所有规格与评测均指该 Preview checkpoint。
2. 本 Preview 是33B 参数的 dense（稠密）模型，并非 MoE 架构，不存在"3B active parameters"之类的口径。评测表中出现的 active parameter 数字仅用于标注部分对比模型（如 Qwen3.6-35B-A3B、DeepSeek V4 Flash 0731、MiniMax M3 等）。

二、架构：混合注意力解码器

Agnes-3.0-Flash Preview 采用混合注意力（hybrid-attention）解码器设计：每四层中，前三层为门控 delta rule（循环式注意力），第四层为标准全局注意力。由于 delta-rule 层的单层状态大小与序列长度无关，72 层中只有 18 层持有随上下文长度增长的 KV cache——这是其支撑 262,144 token 长上下文而显存代价可控的核心原因。

完整规格如下（与 config.json 中的text_config/vision_config逐项对应）：

2.1 源码层的架构印证

在 config.json 的text_config中，layer_types数组以"agnes_delta_attention"/"agnes_global_attention"交替出现共 72 项，与"3 : 1 交替"完全一致；global_attention_interval: 4、num_attention_heads: 24、num_key_value_heads: 4、head_dim: 256、linear_num_key_heads: 16、linear_num_value_heads: 48、linear_conv_kernel_dim: 4、partial_rotary_factor: 0.25、parallel_ffn_intermediate_size: 2048等字段均与上表一一对应。

在 configuration_agnes.py 中：

• AgnesTextConfig.__post_init__会在未显式指定layer_types时，按global_attention_interval（默认 4）自动生成"agnes_global_attention"/"agnes_delta_attention"交替的层计划；
• validate_layer_type校验层类型必须属于LAYER_TYPES，且层数必须等于num_hidden_layers（72）；
• base_model_tp_plan中为全局注意力（global_attn.q/k/v/o_proj）、主 MLP 与并行 FFN（mlp.parallel_ffn.gate/up/down_proj）都声明了 colwise / rowwise 的 tensor-parallel 切分方案。

在 modeling_agnes.py 中，实现细节同样与规格吻合：delta-rule 路径存在_causal_conv_step（因果卷积单步）、_delta_rule_chunked（chunk 尺寸 64 的分块循环）与_delta_rule_stepwise（逐 token 循环）等实现，全局注意力则由AgnesGlobalAttention类承担；视觉侧存在 patch 化（patch_size=16）与spatial_merge_size=2的空间合并逻辑。视觉塔投影到语言模型维度out_hidden_size: 5120，与文本隐藏维度一致。

三、评测结果与口径说明

评测范围：下图和下表中的 Agnes 成绩属于本仓库发布的Agnes-3.0-Flash Preview 开放权重 checkpoint，并非 Artificial Analysis 所列 production/API Agnes 3.0 Flash 模型的成绩。

图表中的 Agnes-3.0-Flash Preview 成绩对应本仓库发布的开放权重 checkpoint。下表汇总了多个同期模型的参考结果，数据来自不同评测环境、模型快照和 harness，不构成同一设置下的受控对比（所有指标均为越高越好；表头参数口径不完全一致，总参数 / 激活参数混排）。

综合来看，Preview 在指令遵循（IFBench 74.20）、科学推理（GPQA Diamond 85.05）、代码（SciCode 38.08）、长上下文检索（AA-LCR 68.33）与全知基准（AA-Omniscience 23.00）上均有可用成绩，其中指令遵循与 GPQA 表现尤为突出。需要强调的是，跨列数值仅作参考，不应解读为受控横向对比结论。

四、快速开始

4.1 必须启用 REMOTE CODE

Agnes-3.0-Flash Preview 自带模型实现（modeling_agnes.py、configuration_agnes.py、processing_agnes.py 等均随仓库发布），因此通过 transformers 加载时必须传trust_remote_code=True，否则无法解析model_type: agnes。

4.2 环境要求

pip install "transformers>=5.12" torch torchvision accelerate

实测环境为 transformers 5.12.1。图像与视频输入由随附的 processor 处理，依赖torchvision；视频处理另依赖 video_processing_agnes.py 中的视频预处理逻辑。

4.3 Transformers 文本推理

from transformers import AutoModelForCausalLM, AutoTokenizer path = "Agnes-AI/Agnes-3.0-Flash" # 或本仓库本地路径 tok = AutoTokenizer.from_pretrained(path) model = AutoModelForCausalLM.from_pretrained( path, dtype="bfloat16", device_map="auto", trust_remote_code=True ) msgs = [{"role": "user", "content": "请用三句话解释什么是人工智能。"}] ids = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt").to(model.device) out = model.generate(ids, max_new_tokens=256) print(tok.decode(out[0][ids.shape[1]:], skip_special_tokens=True))

要点：

• dtype="bfloat16"与 config.json 中text_config.dtype: "bfloat16"一致；
• 对话协议由 chat_template.jinja 渲染（<|im_start|>体系），无需手动拼 prompt。

4.4 图像与视频

图像、视频输入走随模型附带的 processor（同样是 remote code）：

from transformers import AutoProcessor proc = AutoProcessor.from_pretrained(path, trust_remote_code=True) msgs = [{"role": "user", "content": [{"type": "image", "image": "photo.jpg"}, {"type": "text", "text": "描述这张图。"}]}] inputs = proc.apply_chat_template(msgs, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(model.device) out = model.generate(**inputs, max_new_tokens=256) print(proc.batch_decode(out[:, inputs["input_ids"].shape[1]:], skip_special_tokens=True)[0])

底层流程：processor 在模板中将图像/视频替换为<|vision_start|><|image_pad|><|vision_end|>占位符（见 chat_template.jinja 的render_content宏，支持add_vision_id生成 "Picture N:" / "Video N:" 前缀）；processing_agnes.py 再据此将实际视觉特征灌入占位位置。视觉塔支持 2D 图像与 2×2 时间/空间 patch 化的视频输入，image_token_id: 248056、video_token_id: 248057、vision_start/end_token_id均定义在 config.json 顶层。

4.5 推理强度（reasoning effort）

chat template 提供三档推理强度，也可整体关闭思考：

ids = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt", reasoning_effort="medium") # 或 enable_thinking=False

结合 chat_template.jinja 源码，机制如下：

• 当enable_thinking未显式关闭时，默认推理强度为xhigh，合法取值为xhigh（默认）/medium/low，传入其他值会直接抛出Unexpected reasoning effort异常；
• xhigh会注入"仔细思考、校验假设、权衡备选方案、优先保证正确性与一致性"的 system 指令；low注入"思考简短聚焦、直接得出结论"的指令；medium不注入额外指令；
• 传入enable_thinking=False时，生成 prompt 会以空<think></think>开头，关闭思考过程。

实操提示：README 以high指代默认档，模板实现中的字符串为xhigh。以源码实际取值为准：调用时传xhigh/medium/low最稳妥。

4.6 工具调用

chat template 会自动渲染工具定义，模型按<tool_call><function=…><parameter=…>格式发起调用，工具返回值作为tool角色消息接回即可：

tools = [{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的实时天气", "parameters": { "type": "object", "properties": {"city": {"type": "string", "description": "城市名称"}}, "required": ["city"], }, }, }] msgs = [{"role": "user", "content": "北京现在天气怎么样？"}] ids = tok.apply_chat_template(msgs, tools=tools, add_generation_prompt=True, return_tensors="pt").to(model.device) out = model.generate(ids, max_new_tokens=256) reply = tok.decode(out[0][ids.shape[1]:], skip_special_tokens=True) # <tool_call> # <function=get_weather> # <parameter=city> # 北京 # </parameter> # </function> # </tool_call> # 执行工具后把结果接回对话，继续生成最终回复 msgs += [{"role": "assistant", "content": reply}, {"role": "tool", "content": "晴，26°C，东北风 2 级"}]

模板实现细节（见 chat_template.jinja）：

• 工具定义以<tools>…</tools>注入 system 消息，并附上<tool_call>格式说明与"必须严格遵循格式、必填参数必须给出"的提醒；
• assistant 消息携带结构化tool_calls时，模板会渲染为<tool_call><function=…><parameter=…>…</parameter></function></tool_call>嵌套 XML 形式，参数值支持跨行；
• tool角色消息被包装为<tool_response>…</tool_response>块，并自动与前后的 user 消息拼合为合法对话流。

走 OpenAI 接口时同样传tools=。服务端默认原样返回上面的文本；要拿到结构化的tool_calls，需给 sglang 配置与该格式匹配的 tool-call parser（思考段同理，需配置 reasoning parser 才会落入reasoning_content）。

五、SGLang 部署与 OpenAI 兼容服务

5.1 补丁方案原理

sglang_patch/README.md说明了部署思路：serve.sh用官方公开镜像起服务，只覆盖 sglang 包里的三个文件，镜像内其他内容一概不动：

补丁变体支持情况：

补充说明：--trust-remote-code是必须的，因为 sglang 会先经 transformers 解析模型配置，而配置解析要读取随 checkpoint 发布的 configuration_agnes.py；serve.sh还会导出AGNES_MODEL_PATH作为加载器的后备路径。

数值一致性：把并行分支折入主 MLP 会改变 down 投影的归约长度，因此服务端 logits 与 transformers 实现并非逐位一致。在 nightly 镜像上实测（TP1、H200、2144 个 teacher-forced 位置、全词表 248,320 路 softmax）：全词表 KL 为 5.9e-4（对比未打补丁引擎用同权重不带分支服务的 6.5e-4 内部差异），perplexity 17.07 vs 17.05，处于可接受范围。

5.2 启动服务

仓库根目录的 serve.sh 会自动完成"识别 sglang 版本 → 覆盖预编译补丁或就地打补丁 → 启动服务"的全流程（容器内监听8080端口）：

docker run --gpus all --shm-size 64g -p 30001:8080 \ -v /path/to/agnes-3.0-flash:/model \ lmsysorg/sglang:nightly-dev-20260908-20ca564b \ bash /agnes-3.0-flash/serve.sh --served-model-name Agnes-3.0-Flash

serve.sh会把命令行上的额外参数透传给 sglang（--served-model-name即由此生效，同理可追加--tp 2）。serve.sh脚本逻辑：set -euo pipefail下先解析sglang.__version__匹配变体，命中则cp -r覆盖补丁目录，否则调用 apply_patch.py 就地打补丁；最后以python3 -m sglang.launch_server --model-path <repo> --trust-remote-code --host 0.0.0.0 --port 8080 "$@"启动。

5.3 OpenAI 兼容客户端

from openai import OpenAI client = OpenAI(api_key="EMPTY", base_url="http://localhost:30001/v1") response = client.chat.completions.create( model="Agnes-3.0-Flash", messages=[{"role": "user", "content": "设计一个容错的事件处理架构。"}], temperature=1.0, max_tokens=2000, ) print(response.choices[0].message.content)

流式输出传stream=True即可；tools=、reasoning_effort=等参数同样按 OpenAI 协议传递。

六、硬件需求

实际可用上下文长度和并发能力取决于 KV cache 分配、运行时开销和张量并行配置；由于仅 18 层全局注意力持有随长度增长的 KV cache，长上下文下的显存增速显著低于同规模的纯注意力模型。请在目标硬件上按实际负载验证。

七、推荐推理参数

以上即检查点自带 generation_config.json 的默认值（do_sample: true、temperature: 1.0、top_k: 20、top_p: 0.95；eos_token_id为 [248046, 248044]，与bos_token_id248044 一并定义）。

八、能力一览

九、许可证与引用

本项目采用 Apache License 2.0。如需引用，可使用：

@misc{agnes30flash2026, title = {Agnes-3.0-Flash Preview}, author = {{Agnes AI}}, year = {2026}, month = sep, howpublished = {Open-weights preview checkpoint}, url = {https://agnes-ai.com/} }

十、参考资料

• 模型卡（本文主体依据）：README.md / README_zh.md
• 模型配置：config.json（含text_config/vision_config全部超参数）
• 生成参数默认值：generation_config.json
• 配置类源码：configuration_agnes.py
• 模型实现源码：modeling_agnes.py
• 对话模板：chat_template.jinja
• SGLang 补丁说明：sglang_patch/README.md、补丁脚本 sglang_patch/apply_patch.py
• 部署入口：serve.sh

• 大模型
• 多模态
• 推理模型