AI 大模型落地系列｜Eino 组件核心篇：ChatTemplate 为什么不是字符串拼接

声明本文数据源于官方文档与官方实现重点参考 ChatTemplate 使用说明。为什么很多人学 Eino 后写 Prompt 时还是把 ChatTemplate 用成了字符串拼接1. ChatTemplate 是什么不是什么2. 接口虽短但起的作用却不小3. 官方提供了哪些构建方式4. 一个最小例子看懂它怎么工作5. 三个最容易看浅的点5.1 schema.Message 是模板单元不是字符串壳5.2 MessagesPlaceholder 才是很多人真正该盯住的点5.3 三种模板语法怎么选别一上来就上复杂度6. 为什么它能进入 Chain / Graph / Callback为什么连 Callback 也会进来7. 总结参考资料为什么很多人已经会写 prompt(提示词) 了到了 Eino 里却还是经常把ChatTemplate用偏因为太多人一看到 template就条件反射地把它理解成“字符串替换器”。把{role}换进去把{task}换进去再把 history 手动拼成一大段文本看起来也能跑。可问题恰恰就在这儿你如果只是这么用等于把 Eino 这层最关键的上下文组织能力直接降级成了字符串拼接。这篇文章就想回答两个问题ChatTemplate到底解决了什么它为什么不是一个“高级一点的字符串模板”而已1.ChatTemplate是什么不是什么先把结论摆出来ChatTemplate不是字符串拼接工具。它是把变量、角色消息、历史对话组织成[]*schema.Message的组件。这句话看起来只差几个字实际差得很远。如果你把它当成字符串模板脑子里的链路通常是这样的变量 - 替换文本 - 拼 prompt - 丢给模型而 Eino 真正想让你建立的链路是这样的变量 / 前驱节点输出 - ChatTemplate - []*schema.Message - ChatModel也就是说ChatTemplate干的不是“把几段字拼起来”而是“把上下文整理成模型能消费的消息协议”。这层价值主要体现在三件事上。第一它让 prompt 变成结构化消息而不是一坨长字符串。第二它让多轮 history 的注入有统一入口不用你手搓字符串去拼上下文。第三它能直接进入Chain、Graph、Callback这些编排和可观测链路里说明它从一开始就不是一个工具函数而是一个组件。所以如果你问ChatTemplate在 Eino 里到底值不值得单独学我的回答很直接值得。因为它解决的不是“模板替换”而是“Prompt 怎样以消息协议的方式进入 Eino”。2. 接口虽短但起的作用却不小官方给出的核心接口其实非常短typeChatTemplateinterface{Format(ctx context.Context,vsmap[string]any,opts...Option)([]*schema.Message,error)}很多人第一次看到这行代码会觉得不就是个格式化函数吗真要这么理解还是看浅了。这里最重要的其实是Format的三个输入和一个输出。ctx不只是普通上下文。它即负责传递请求级信息同时它也承载Callback Manager。这意味着模板格式化这件事并不是一个完全封闭的小动作它是能被观测、能被接入回调链路的。vs虽是变量映射但却不是“只能塞字符串”的变量映射。你既可以传role: 专业助手这种普通文本也可以传history_key: []*schema.Message{...}这种消息列表。换句话说它接收的不是纯文本变量而是上下文数据。opts也很有意思。官方没有给ChatTemplate设计一个“大而全的公共参数表”而是把它作为具体实现的扩展点来留。这个意思其实很明确Prompt 组件需要统一协议但不想被统一成一个笨重的大接口。最后是输出。Format返回的不是一段 prompt 文本而是标准消息数组[]*schema.Message。这一步就是ChatTemplate和字符串拼接最本质的分水岭。你自己手拼字符串最终交给模型的是一段文本。你用ChatTemplate最终交给模型的是一组角色明确、结构清晰的消息。3. 官方提供了哪些构建方式prompt.FromMessages()用于把多个message变成一个chat template。schema.Message{}schema.Message是实现了Format接口的结构体因此可直接构建schema.Message{}作为 template。schema.SystemMessage()此方法是构建role为system的message快捷方法。schema.AssistantMessage()此方法是构建role为assistant的message快捷方法。schema.UserMessage()此方法是构建role为user的message快捷方法。schema.ToolMessage()此方法是构建role为tool的message快捷方法。schema.MessagesPlaceholder()可用于把一个[]*schema.Message插入到message列表中常用于插入历史对话。4. 一个最小例子看懂它怎么工作先看一遍留个整体印象后面再拆开说。import(github.com/cloudwego/eino/components/promptgithub.com/cloudwego/eino/schema)// 创建模板template:prompt.FromMessages(schema.FString,schema.SystemMessage(你是一个{role}。),schema.MessagesPlaceholder(history_key,false),schema.Message{Role:schema.User,Content:请帮我{task}。,},)// 准备变量variables:map[string]any{role:专业的助手,task:写一首诗,history_key:[]*schema.Message{{Role:schema.User,Content:告诉我油画是什么?},{Role:schema.Assistant,Content:油画是xxx},},}// 格式化模板messages,err:template.Format(context.Background(),variables)这段代码真正值得你记住的不是语法而是它把几个关键动作放到了一起。system提示可以参数化不需要写死。history 可以整体注入而且注入进去的仍然是[]*schema.Message不是你手工拼出来的一大段文本。当前这一轮的 user 问题也可以模板化跟 system 和 history 统一走一条格式化链路。最后template.Format(...)产出的不是字符串而是messages。这些messages才是后面交给ChatModel的标准输入。如果继续往下看真正值得盯住的主要是下面三个点。5. 三个最容易看浅的点这三点皆源于目录3与目录45.1schema.Message是模板单元不是字符串壳很多人学到prompt.FromMessages(...)时会下意识把它理解成“多个 prompt 片段拼起来”。这个理解只对了一半。它确实是在组合内容但组合的不是普通字符串而是消息模板。比如schema.SystemMessage(...)schema.UserMessage(...)甚至一个完整的schema.Message{}这些东西放进prompt.FromMessages(...)以后组成的是一组待格式化的消息模板不是一篇待替换的大作文。字符串拼接关心的是“句子怎么连起来”。而ChatTemplate关心的是“system 说什么user 说什么history 该插在哪最后怎样变成标准消息协议”。这两个层级本来就不是一回事。5.2MessagesPlaceholder才是很多人真正该盯住的点如果说ChatTemplate里有一个最容易被低估、但对真实业务最重要的能力那大概率就是schema.MessagesPlaceholder(...)。为什么因为多轮对话里最常见的问题从来不是“怎么替换{name}”而是“怎么把历史上下文塞进去而且别塞乱了”。很多人会这样干把历史对话先手动拼成一大段字符串再把它塞进某个 user prompt 里。这种写法当然能跑但它本质上还是字符串拼接。你原本可以传一个[]*schema.Message结果你自己把它打平成了纯文本。看起来省事实际上是主动绕开了消息协议。schema.MessagesPlaceholder(history_key, false)的价值就在这儿。它让你可以把history_key对应的[]*schema.Message直接插进消息列表里。也就是说这条链路应该这么理解history - MessagesPlaceholder - []*schema.Message它的重点不是“占位符”三个字而是“history 仍然以消息数组的形态进入模板”。这个思路一旦立住你后面做多轮、做记忆、做 Agent 上下文拼装脑子都会顺很多。5.3 三种模板语法怎么选别一上来就上复杂度官方内置了三种模板化方式schema.FStringschema.GoTemplateschema.Jinja2它们不是“谁更高级”而是适用场景不同。schema.FString最直观用{variable}做替换适合大多数基础场景。如果你的需求只是把角色、任务、问题这类变量填进去它通常就够了。schema.GoTemplate适合需要条件判断、循环拼接这类逻辑的场景。一旦你的模板里已经出现“有值就展示没有就省略”“遍历一组数据生成内容”这种诉求Go 模板会更顺手。schema.Jinja2更像是给有模板引擎经验的人准备的。python风格如果你平时就熟悉 Jinja 风格那它上手会更自然。我的建议很简单别把模板引擎选型搞成技术表演。简单替换就用schema.FString真有条件逻辑再上schema.GoTemplate已经习惯 Jinja 再选schema.Jinja2。你要解决的是消息组织问题不是比赛谁的模板更花。6. 为什么它能进入Chain / Graph / Callback只看单独调用你很容易以为ChatTemplate不过是个前置小工具。可一旦站到编排视角它的定位就完全变了。在Chain里ChatTemplate是一个很标准的上下文准备节点。它的任务不是回答问题而是把输入变量整理成后续模型能吃的消息列表。在Graph里这个味道更明显。它可以消费前驱节点经过compose.WithOutputKey(...)包装后的map[string]any输出然后继续把这些数据组织成消息。短示意可以看成这样// 创建一个 Chain输入是 map[string]any输出是 []*schema.Message// 也就是说这条链路接收一组变量最终产出标准消息列表供后续 ChatModel 使用。chain:compose.NewChain[map[string]any,[]*schema.Message]()// 把前面定义好的 ChatTemplate 挂到 Chain 上。// 作用把输入变量格式化成消息数组。chain.AppendChatTemplate(template)// 创建一个 Graph输入是 string输出是 []*schema.Message// 这里的意思是Graph 接收一段原始字符串经过节点处理后最终产出消息列表。graph:compose.NewGraph[string,[]*schema.Message]()// 添加一个 Lambda 节点节点名叫 rewrite_querygraph.AddLambdaNode(rewrite_query,// 这个 Lambda 的作用是把原始输入改写成一个更完整的用户问题// 例如输入123// 输出请帮我总结这段需求123compose.InvokableLambda(func(ctx context.Context,inputstring)(string,error){return请帮我总结这段需求input,nil}),// 把这个节点的输出包装成 map[string]any 里的一个字段key 叫 query// 这样后面的 ChatTemplate 就可以用 {query} 来取这个值compose.WithOutputKey(query),)// 添加一个 ChatTemplate 节点节点名叫 prompt_nodegraph.AddChatTemplateNode(prompt_node,prompt.FromMessages(schema.FString,// system 消息给模型设定角色// 这里的 {role} 需要在运行时从变量里传入schema.SystemMessage(你是一个{role}。),// user 消息使用上一个节点产出的 query// 因为 rewrite_query 节点通过 WithOutputKey(query) 输出了 query// 所以这里可以直接写 {query}schema.UserMessage({query}),))翻成人话就是前面的节点先产出数据。如果它通过compose.WithOutputKey(query)把结果包成map[string]any那后面的ChatTemplate节点就可以直接用这个 key 去取值再把它组织成标准消息。这时你会发现ChatTemplate真正扮演的角色其实是“消息协议装配器”。它站在模型前面把上游零散的数据整理成模型真正能消费的输入。也正因为如此它才能自然接进Chain和Graph而不是只能当一个局部 helper 用完即弃。说到底它不是零散的字符串 helper而是一个可以被编排系统识别的节点。为什么连Callback也会进来很多人看到 Prompt 组件的回调支持会有一个误判“模板格式化也要回调是不是有点小题大做了”如果你只是把ChatTemplate当字符串替换器你确实会这么想。但如果你已经接受了它是一个正式组件这件事就很合理了。官方给了prompt.CallbackInput和prompt.CallbackOutput这意味着你在模板格式化前后是可以被回调系统观察到的。你能看到输入的变量是什么当前模板集合是什么格式化产出的消息结果是什么而在生命周期上对应的就是OnStart、OnEnd、OnError这几个钩子。这层能力的意义不只是“记个日志”。而是在告诉你Prompt 组件也属于 Eino 的运行链路它不是一个藏在角落里的文本处理函数。7. 总结如果你问我本篇ChatTemplate真正想让人学会什么我会把答案压成三句话1、ChatTemplate解决的是消息组织不是字符串替换。2、MessagesPlaceholder是多轮上下文接入的关键因为它让 history 以[]*schema.Message的形态进入模板而不是被你手工压成文本。3、Chain、Graph、Callback这些能力同时出现说明ChatTemplate从一开始就是组件层能力不是 prompt 拼接小工具。所以别再把它当“模板语法说明书”看了。你一旦把这层看懂后面再去学ToolsNodeTool或者继续往Retriever / RAG的上下文拼装走很多设计都会顺理成章。参考资料CloudWeGo Eino ChatTemplate 使用说明