AIxiv專欄是機(jī)器之心發(fā)布學(xué)術(shù)、技術(shù)內(nèi)容的欄目。過去數(shù)年，機(jī)器之心AIxiv專欄接收?qǐng)?bào)道了2000多篇內(nèi)容，覆蓋全球各大高校與企業(yè)的頂級(jí)實(shí)驗(yàn)室，有效促進(jìn)了學(xué)術(shù)交流與傳播。如果您有優(yōu)秀的工作想要分享，歡迎投稿或者聯(lián)系報(bào)道。投稿郵箱：liyazhou@jiqizhixin.com；zhaoyunfeng@jiqizhixin.com
開發(fā)基于大模型的軟件應(yīng)用，就像指揮一支足球隊(duì)：組件是能力各異的隊(duì)員，編排是靈活多變的戰(zhàn)術(shù)，數(shù)據(jù)是流轉(zhuǎn)的足球。
Eino 是字節(jié)跳動(dòng)開源的大模型應(yīng)用開發(fā)框架，擁有穩(wěn)定的內(nèi)核，靈活的擴(kuò)展性，完善的工具生態(tài)，可靠且易維護(hù)，背靠豆包、抖音等應(yīng)用的豐富實(shí)踐經(jīng)驗(yàn)。初次使用 Eino，就像接手一支實(shí)力雄厚的足球隊(duì)，即使教練是初出茅廬的潛力新人，也可以踢出高質(zhì)量、有內(nèi)容的比賽。
下面就讓我們一起踏上新手上路之旅！
認(rèn)識(shí)隊(duì)員
Eino 應(yīng)用的基本構(gòu)成元素是功能各異的組件，就像足球隊(duì)由不同位置角色的隊(duì)員組成：
這些組件抽象代表了固定的輸入輸出類型、Option 類型和方法簽名：
type ChatModel interface { Generate(ctx context.Context, input []*schema.Message, opts ...Option) (*schema.Message, error) Stream(ctx context.Context, input []*schema.Message, opts ...Option) ( *schema.StreamReader[*schema.Message], error) BindTools(tools []*schema.ToolInfo) error}
真正的運(yùn)行，需要的是具體的組件實(shí)現(xiàn)：
Eino 的開發(fā)過程中，首先要做的是決定 “我需要使用哪個(gè)組件抽象”，再?zèng)Q定 “我需要使用哪個(gè)具體組件實(shí)現(xiàn)”。就像足球隊(duì)先決定 “我要上 1 個(gè)前鋒”，再挑選 “誰來擔(dān)任這個(gè)前鋒”。
組件可以像使用任何的 Go interface 一樣單獨(dú)使用。但要想發(fā)揮 Eino 這支球隊(duì)真正的威力，需要多個(gè)組件協(xié)同編排，成為一個(gè)相互聯(lián)結(jié)的整體。
制定戰(zhàn)術(shù)
在 Eino 編排場(chǎng)景中，每個(gè)組件成為了 “節(jié)點(diǎn)”（Node），節(jié)點(diǎn)之間 1 對(duì) 1 的流轉(zhuǎn)關(guān)系成為了 “邊”（Edge），N 選 1 的流轉(zhuǎn)關(guān)系成為了 “分支”（Branch）。基于 Eino 開發(fā)的應(yīng)用，經(jīng)過對(duì)各種組件的靈活編排，就像一支足球隊(duì)可以采用各種陣型，能夠支持無限豐富的業(yè)務(wù)場(chǎng)景。
足球隊(duì)的戰(zhàn)術(shù)千變?nèi)f化，但卻有跡可循，有的注重控球，有的簡(jiǎn)單直接。對(duì) Eino 而言，針對(duì)不同的業(yè)務(wù)形態(tài)，也有更合適的編排方式：
Chain，如簡(jiǎn)單的 ChatTemplate + ChatModel 的 Chain：
chain, _ := NewChain[map[string]any, *Message](). AppendChatTemplate(prompt). AppendChatModel(model). Compile(ctx)chain.Invoke(ctx,map[string]any{"query":"what'syourname?"})
Graph，如 ReAct Agent：
graph := NewGraph[map[string]any, *schema.Message]()_ = graph.AddChatTemplateNode("node_template", chatTpl)_ = graph.AddChatModelNode("node_model", chatModel)_ = graph.AddToolsNode("node_tools", toolsNode)_ = graph.AddLambdaNode("node_converter", takeOne)_ = graph.AddEdge(START, "node_template")_ = graph.AddEdge("node_template", "node_model")_ = graph.AddBranch("node_model", branch)_ = graph.AddEdge("node_tools", "node_converter")_ = graph.AddEdge("node_converter", END)compiledGraph, err := graph.Compile(ctx)if err != nil { return err}out,err:=r.Invoke(ctx,map[string]any{"query":"Beijing'sweatherthisweekend"})了解工具現(xiàn)在想象下你接手的足球隊(duì)用了一些黑科技，比如：在每個(gè)隊(duì)員接球和出球的瞬間，身上的球衣可以自動(dòng)的記錄接球和出球的速度、角度并傳遞給場(chǎng)邊的服務(wù)器，這樣比賽結(jié)束后，就可以統(tǒng)計(jì)出每個(gè)隊(duì)員觸球的情況和處理球的時(shí)間。在 Eino 中，每個(gè)組件運(yùn)行的開始和結(jié)束，也可以通過 Callbacks 機(jī)制拿到輸入輸出及一些額外信息，處理橫切面需求。比如一個(gè)簡(jiǎn)單的打日志能力：
handler := NewHandlerBuilder(). OnStartFn( func (ctx context.Context, info *RunInfo, input CallbackInput) context.Context { log.Printf("onStart, runInfo: % v, input: % v", info, input) return ctx }). OnEndFn( func (ctx context.Context, info *RunInfo, output CallbackOutput) context.Context { log.Printf("onEnd, runInfo: % v, out: % v", info, output) return ctx }). Build()// 注入到 graph 運(yùn)行中compiledGraph.Invoke(ctx, input, WithCallbacks(handler))再想象一下，這個(gè)足球隊(duì)的黑科技不止一種，還可以讓教練在比賽前制作 “錦囊” 并藏在球衣里，當(dāng)隊(duì)員接球時(shí)，這個(gè)錦囊就會(huì)播放教練事先錄制好的妙計(jì)，比如 “別猶豫，直接射門！”。聽上去很有趣，但有一個(gè)難點(diǎn)：有的錦囊是給全隊(duì)所有隊(duì)員的，有的錦囊是只給一類隊(duì)員（比如所有前鋒）的，而有的錦囊甚至是只給單個(gè)隊(duì)員的。如何有效的做到錦囊妙計(jì)的分發(fā)？在 Eino 中，類似的問題是 graph 運(yùn)行過程中 call option 的分發(fā)：
// 所有節(jié)點(diǎn)都生效的 call optioncompiledGraph.Invoke(ctx, input, WithCallbacks(handler))// 只對(duì)特定類型節(jié)點(diǎn)生效的 call optioncompiledGraph.Invoke(ctx, input, WithChatModelOption(model.WithTemperature(0.5)))// 只對(duì)特定節(jié)點(diǎn)生效的 call optioncompiledGraph.Invoke(ctx,input,WithCallbacks(handler).DesignateNode("node_1"))發(fā)現(xiàn)獨(dú)門秘笈現(xiàn)在，想象一下你的球隊(duì)里有一些明星球員（中場(chǎng)大腦 ChatModel 和鋒線尖刀 StreamableTool）身懷絕技，他們踢出的球速度如此之快，甚至出現(xiàn)了殘影，看上去就像是把一個(gè)完整的足球切成了很多片！面對(duì)這樣的 “流式” 足球，對(duì)手球員手足無措，不知道該如何接球，但是你的球隊(duì)的所有隊(duì)員，都能夠完美的接球，要么直接一個(gè)片一個(gè)片的接收 “流式” 足球并第一時(shí)間處理，要么自動(dòng)的把所有片拼接成完整的足球后再處理。身懷這樣的獨(dú)門秘笈，你的球隊(duì)具備了面對(duì)其他球隊(duì)的降維打擊能力！在 Eino 中，開發(fā)者只需要關(guān)注一個(gè)組件在 “真實(shí)業(yè)務(wù)場(chǎng)景” 中，是否可以處理流式的輸入，以及是否可以生成流式的輸出。根據(jù)這個(gè)真實(shí)的場(chǎng)景，具體的組件實(shí)現(xiàn)（包括 Lambda Function）就去實(shí)現(xiàn)符合這個(gè)流式范式的方法：
// ChatModel 實(shí)現(xiàn)了 Invoke（輸入輸出均非流）和 Stream（輸入非流，輸出流）兩個(gè)范式type ChatModel interface { Generate(ctx context.Context, input []*Message, opts ...Option) (*Message, error) Stream(ctx context.Context, input []*Message, opts ...Option) ( *schema.StreamReader[*Message], error)}// Lambda 可以實(shí)現(xiàn)任意四種流式范式//Invokeisthetypeoftheinvokablelambdafunction.type Invoke[I, O, TOption any] func(ctx context.Context, input I, opts ...TOption) ( output O, err error)// Stream is the type of the streamable lambda function.type Stream[I, O, TOption any] func(ctx context.Context, input I, opts ...TOption) (output *schema.StreamReader[O], err error)// Collect is the type of the collectable lambda function.type Collect[I, O, TOption any] func(ctx context.Context, input *schema.StreamReader[I], opts ...TOption) (output O, err error)// Transform is the type of the transformable lambda function.type Transform[I, O, TOption any] func(ctx context.Context,input*schema.StreamReader[I],opts...TOption)(output*schema.StreamReader[O],errerror)Eino 編排能力會(huì)自動(dòng)做兩個(gè)重要的事情：1. 上游是流，但是下游只能接收非流時(shí)，自動(dòng)拼接（Concat）。2. 上游是非流，但是下游只能接收流時(shí)，自動(dòng)流化（T -> StreamReader [T]）。除此之外，Eino 編排能力還會(huì)自動(dòng)處理流的合并、復(fù)制等各種細(xì)節(jié)，把大模型應(yīng)用的核心 流處理做到了極致。一場(chǎng)訓(xùn)練賽 -- Eino 智能助手好了，現(xiàn)在你已經(jīng)初步了解了 Eino 這支明星球隊(duì)的主要能力，是時(shí)候通過隊(duì)員 (組件)、戰(zhàn)術(shù) (編排)、工具 (切面、可視化) 來一場(chǎng)訓(xùn)練賽，去親自體驗(yàn)一下它的強(qiáng)大。場(chǎng)景設(shè)定Eino 智能助手：根據(jù)用戶請(qǐng)求，從知識(shí)庫檢索必要的信息并按需調(diào)用多種工具，以完成對(duì)用戶的請(qǐng)求的處理。工具列表如下：
DuckDuckGo：從 DuckDuckGo 搜索互聯(lián)網(wǎng)信息
EinoTool：獲取 Eino 的工程信息，比如倉庫鏈接、文檔鏈接等
GitClone：克隆指定倉庫到本地
任務(wù)管理 (TaskManager)：添加、查看、刪除 任務(wù)
OpenURL：使用系統(tǒng)的默認(rèn)應(yīng)用打開文件、Web 等類型的鏈接
這里呈現(xiàn)一個(gè) Demo 樣例，大家可根據(jù)自己的場(chǎng)景，更換自己的知識(shí)庫和工具，以搭建自己所需的智能助手。先來一起看看基于 Eino 搭建起來的 Agent 助手能實(shí)現(xiàn)什么效果：
構(gòu)建這個(gè) Eino 智能助手分兩步：
Knowledge Indexing（索引知識(shí)庫）：將我們?cè)谔囟I(lǐng)域沉淀的知識(shí)，以分詞、向量化等多種手段，構(gòu)建成索引，以便在接收用戶請(qǐng)求時(shí)，索引出合適的上下文。本文采用向量化索引來構(gòu)建知識(shí)庫。
Eino Agent（Eino 智能助手）：根據(jù)用戶的請(qǐng)求信息以及我們預(yù)先構(gòu)建好的可調(diào)用的工具，讓 ChatModel 幫我們決策下一步應(yīng)該執(zhí)行什么動(dòng)作或輸出最終結(jié)果。Tool 的執(zhí)行結(jié)果會(huì)再次輸入給 ChatModel，讓 ChatModel 再一次判斷下一步的動(dòng)作，直至完成用戶的請(qǐng)求。
任務(wù)工作流索引知識(shí)庫 (Knowledge Indexing)將 Markdown 格式的 Eino 用戶手冊(cè)，以合適的策略進(jìn)行拆分和向量化，存入到 RedisSearch 的 VectorStore 中，作為 Eino 知識(shí)庫。
Eino 智能體 (Eino Agent)根據(jù)用戶請(qǐng)求，從 Eino 知識(shí)庫召回信息，采用 ChatTemplate 構(gòu)建消息，請(qǐng)求 React Agent，視需求循環(huán)調(diào)用對(duì)應(yīng)工具，直至完成處理用戶的請(qǐng)求。
所需工具在從零開始構(gòu)建「Eino 智能助手」這個(gè)實(shí)踐場(chǎng)景中，需要下列工具：
索引知識(shí)庫示例的倉庫路徑：https://github.com/cloudwego/eino-examples/tree/main/quickstart/eino_assistant下文中，采用相對(duì)于此目錄的相對(duì)路徑來標(biāo)識(shí)資源位置
構(gòu)建一個(gè)命令行工具，遞歸遍歷指定目錄下的所有 Markdown 文件。按照標(biāo)題將 Markdown 文件內(nèi)容分成不同的片段，并采用火山云的豆包向量化模型逐個(gè)將文本片段進(jìn)行向量化，存儲(chǔ)到 Redis VectorStore 中。指令行工具目錄：cmd/knowledge_indexingMarkdown 文件目錄：cmd/knowledge_indexing/eino-dcos
開發(fā)「索引知識(shí)庫」應(yīng)用時(shí)，首先采用 Eino 框架提供的 Goland EinoDev 插件，以可視化拖拽和編排的形式構(gòu)建 KnowledgeIndexing 的核心應(yīng)用邏輯，生成代碼到 eino_graph/knowledge_indexing 目錄。代碼生成后，首先手動(dòng)將該目錄下的各組件的構(gòu)造方法補(bǔ)充完整，然后在業(yè)務(wù)場(chǎng)景中，調(diào)用 BuildKnowledgeIndexing 方法，構(gòu)建并使用 Eino Graph 實(shí)例。接下來將逐步介紹，KnowledgeIndexing 的開發(fā)過程：大模型資源創(chuàng)建火山引擎是字節(jié)跳動(dòng)的云服務(wù)平臺(tái)，可從中注冊(cè)和調(diào)用豆包大模型（有大量免費(fèi)額度）。
創(chuàng)建 doubao-embedding-large 作為知識(shí)庫構(gòu)建時(shí)的向量化模型，以及創(chuàng)建 doubao-pro-4k 資源作為 agent 對(duì)話時(shí)的模型。
「火山引擎在線推理」：https://console.volcengine.com/ark
啟動(dòng) Redis Stack本文將使用 Redis 作為 Vector Database，為方便用戶構(gòu)建環(huán)境，Docker 的快捷指令如下：
在 eino-examples/quickstart/eino_assistant 提供 docker-compose.yml
在 eino-examples/quickstart/eino_assistant/data 目錄下提供了 Redis 的初始知識(shí)庫
直接用redis官方的redisstack鏡像啟動(dòng)即可
# 切換到 eino_assistant 目錄cd xxx/eino-examples/quickstart/eino_assistantdocker-composeup-d
完成啟動(dòng)后，打開本地的 8001 可進(jìn)入 redis stack 的 web 界面
在瀏覽器打開鏈接：http://127.0.0.1:8001可視化開發(fā)「Eino 可視化開發(fā)」是為了降低 Eino AI 應(yīng)用開發(fā)的學(xué)習(xí)曲線，提升開發(fā)效率。對(duì)于熟悉 Eino 的開發(fā)者，也可選擇跳過「Eino 可視化開發(fā)」階段，直接基于 Eino 的 API 進(jìn)行全碼開發(fā)。
1. 安裝 EinoDev 插件，并打開 Eino Workflow 功能
Graph name: KnowledgeIndexing
Node trigger mode: Triggered after all predecessor nodes are executed
Input type: document.Source
Import path of input type: github.com/cloudwego/eino/components/document
Output type: [] string
其他置空
2. 按照上文「索引知識(shí)庫」中的流程說明，從 Eino Workflow 中選擇需要使用的組件庫，本文需要用到如下組件：
document/loader/file 從指定 URI 加載文件，解析成文本內(nèi)容，以 schema.Document 列表形式返回。
document/transformer/splitter/markdown 將從 FileLoader 中加載到的文本內(nèi)容，進(jìn)一步拆分成合適的大小，以平衡向量化計(jì)算 / 存儲(chǔ)的尺寸限制和召回的效果。
indexer/redis 將 schema.Document 的原文、索引字段 存儲(chǔ)在 Redis Vector Database 中
embedding/ark 采用 Ark 平臺(tái)的向量化模型，對(duì) schema.Document 中的 Content 等內(nèi)容進(jìn)行向量化計(jì)算
3. 將選中的組件按照預(yù)期的拓?fù)浣Y(jié)構(gòu)進(jìn)行編排，完成編排后，點(diǎn)擊 “生成代碼” 到指定目錄。
「索引知識(shí)庫」的代碼生成到：eino_assistant/eino/knowledgeindexing
本示例可直接復(fù)制 eino/knowledge_indexing.json 中的 Graph Schema，來快速構(gòu)建示例中的圖
4. 按需完善各個(gè)組件的構(gòu)造函數(shù)，在構(gòu)造函數(shù)中補(bǔ)充創(chuàng)建組件實(shí)例時(shí)，需要的配置內(nèi)容
5. 補(bǔ)充好組件的配置內(nèi)容后，即可調(diào)用 BuildKnowledgeIndexing 方法，在業(yè)務(wù)場(chǎng)景使用完善代碼
通過可視化開發(fā)，生成的 Eino 編排代碼，無法保證可直接使用，需要人工閱讀和檢查下代碼的完整性
生成核心函數(shù)是 BuildKnowledgeIndexing ()，用戶可在需要的地方調(diào)用此方法，創(chuàng)建實(shí)例進(jìn)行使用
在「索引知識(shí)庫」的場(chǎng)景下，需要將 BuildKnowledgeIndexing 封裝成一個(gè)指令，從環(huán)境變量中讀取模型配置等信息，初始化 BuildKnowledgeIndexing 的配置內(nèi)容，掃描指定目錄下的 Markdown 文件，執(zhí)行對(duì) Markdown 進(jìn)行索引和存儲(chǔ)的操作。詳細(xì)代碼可查看：cmd/knowledgeindexing/main.go
運(yùn)行PS: 示例項(xiàng)目中，已經(jīng)內(nèi)置了 eino 的一部分文檔向量化到 redis 中
1. 在 .env 文件中按照注釋說明，獲取并填寫 ARK_EMBEDDING_MODEL 和 ARK_API_KEY 的值，按如下指令，運(yùn)行 KnowledgeIndexing 指令
cd xxx/eino-examples/quickstart/eino_assistant # 進(jìn)入 eino assistant 的 example 中# 修改 .env 中所需的環(huán)境變量 (大模型信息、trace 平臺(tái)信息)source .env# 因示例的Markdown文件存放在 cmd/knowledgeindexing/eino-docs 目錄，代碼中指定了相對(duì)路徑 eino-docs，所以需在 cmd/knowledgeindexing 運(yùn)行指令cd cmd/knowledgeindexinggorunmain.go
2. 執(zhí)行運(yùn)行成功后，即完成 Eino 知識(shí)庫的構(gòu)建，可在 Redis Web UI 中看到向量化之后的內(nèi)容在瀏覽器打開鏈接：http://127.0.0.1:8001
Eino 智能體示例的倉庫路徑：https://github.com/cloudwego/eino-examples/tree/main/quickstart/eino_assistant下文中，采用相對(duì)于此目錄的相對(duì)路徑來標(biāo)識(shí)資源位置
構(gòu)建一個(gè)基于從 Redis VectorStore 中召回的 Eino 知識(shí)回答用戶問題，幫用戶執(zhí)行某些操作的 ReAct Agent，即典型的 RAG ReAct Agent�？筛鶕�(jù)對(duì)話上下文，自動(dòng)幫用戶記錄任務(wù)、Clone 倉庫，打開鏈接等。大模型資源創(chuàng)建繼續(xù)使用「索引知識(shí)庫」章節(jié)中創(chuàng)建的 doubao-embedding-large 和 doubao-pro-4k啟動(dòng) RedisSearch繼續(xù)使用「索引知識(shí)庫」章節(jié)中啟動(dòng)的 Redis Stack可視化開發(fā)
1. 打開 EinoDev 插件，進(jìn)入到 Eino Workflow 頁面，新建一張畫布
Graph Name: EinoAgent
Node Trigger Mode: Triggered after all predecessor nodes are executed
Input Type Name: *UserMessage
Input Package Path: ""
Output Type Name: *schema.Message
Output Import Path: github.com/cloudwego/eino/schema
其他置空
2. 按照上文「Eino 智能體」中的流程說明，從 Eino Workflow 中選擇需要使用的組件庫，本文需要用到如下組件：
lambda: 將開發(fā)者任意的函數(shù) func (ctx context.Context, input I) (output O, err error)，轉(zhuǎn)換成可被編排的節(jié)點(diǎn)，在 EinoAgent 中，有兩個(gè)轉(zhuǎn)換場(chǎng)景：
（1）將 *UserMessage 消息轉(zhuǎn)換成 ChatTemplate 節(jié)點(diǎn)的 map [string] any（2）將 *UserMessage 轉(zhuǎn)換成 RedisRetriever 的輸入 query
retriever/redis 根據(jù)用戶 Query 從 Redis Vector Database 根據(jù)語義相關(guān)性，召回和 Query 相關(guān)的上下文，以 schema.Document List 的形式返回。
prompt/chatTemplate 通過字符串字面量構(gòu)建 Prompt 模板，支持 文本替換符 和 消息替換符，將輸入的任意 map [string] any，轉(zhuǎn)換成可直接輸入給模型的 Message List。
flow/agent/react 基于開發(fā)者提供的 ChatModel 和 可調(diào)用的工具集，針對(duì)用戶的問題，自動(dòng)決策下一步的 Action，直至能夠產(chǎn)生最終的回答。
model/ark Ark 平臺(tái)提供的能夠進(jìn)行對(duì)話文本補(bǔ)全的大模型，例如豆包模型。作為 ReAct Agent 的依賴注入。
可調(diào)用的工具列表互聯(lián)網(wǎng)搜索工具 (DuckDuckGo)、EinoTool、GitClone、任務(wù)管理 (TaskManager)、 OpenURL
3. 將選中的組件按照預(yù)期的拓?fù)浣Y(jié)構(gòu)進(jìn)行編排，完成編排后，點(diǎn)擊 “生成代碼” 到指定目錄。
本示例中，「Eino 智能體」的代碼生成到：eino/einoagent
本示例可直接復(fù)制 eino/eino_agent.json 中的 Graph Schema，來快速構(gòu)建示例中的圖
4. 按需完善各個(gè)組件的構(gòu)造函數(shù)，在構(gòu)造函數(shù)中補(bǔ)充創(chuàng)建組件實(shí)例時(shí)，需要的配置內(nèi)容
5. 補(bǔ)充好組件的配置內(nèi)容后，即可調(diào)用 BuildEinoAgent 方法，在業(yè)務(wù)場(chǎng)景使用完善代碼在「Eino 智能體」的場(chǎng)景下，BuildEinoAgent 構(gòu)建的 Graph 實(shí)例可做到：根據(jù)用戶請(qǐng)求和對(duì)話歷史，從 Eino 知識(shí)庫中召回上下文， 然后結(jié)合可調(diào)用的工具列表，將 ChatModel 循環(huán)決策下一步是調(diào)用工具或輸出最終結(jié)果。下圖即是對(duì)生成的 BuildEinoAgent 函數(shù)的應(yīng)用，將 Eino Agent 封裝成 HTTP 服務(wù)接口：
運(yùn)行1. 在 .env 文件中按照注釋說明，獲取并填寫對(duì)應(yīng)各變量的值，按如下指令，啟動(dòng) Eino Agent Server
觀測(cè) (可選)如果在運(yùn)行時(shí)，在 .env 文件中指定了 LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY，便可在 Langfuse 平臺(tái)中，登錄對(duì)應(yīng)的賬號(hào)，查看請(qǐng)求的 Trace 詳情。
相關(guān)鏈接：THE END轉(zhuǎn)載請(qǐng)聯(lián)系本公眾號(hào)獲得授權(quán)
