eino-guide

Eino 框架指南

Eino（读作“i know”）是一个用于构建大模型应用的 Go 框架。

核心概念

组件

用于 AI 能力的标准化接口。每个接口都有多个可互换的实现。

组件	功能	关键接口
ChatModel	大模型推理（生成 / 流式输出）	model.BaseChatModel, model.ToolCallingChatModel
Tool	模型可调用的函数	tool.InvokableTool, tool.EnhancedInvokableTool
Embedding	将文本转换为向量	embedding.Embedder
Retriever	向量 / 关键词搜索	retriever.Retriever
Indexer	将文档与向量一同存储	indexer.Indexer
ChatTemplate	使用变量格式化提示词	prompt.ChatTemplate
Document Loader/Transformer	加载和处理文档	document.Loader, document.Transformer
Callback Handler	可观测性与追踪	callbacks.Handler

实现位于 eino-ext（OpenAI、Claude、Gemini、Ark、Ollama、Milvus、Redis、Elasticsearch 等）。

-> 使用 /eino-component 选择、配置和使用组件。

编排（Compose）

用于将组件连接为可执行流水线的 3 种 API。它们都会编译为一个 Runnable[I, O]，支持 4 种执行模式（Invoke、Stream、Collect、Transform）。

API	拓扑结构	使用场景
Graph	有向图，支持循环	包含分支、循环的复杂流程（例如 ReAct 模式）
Chain	线性顺序	简单流水线（例如模板 -> 模型）
Workflow	支持字段级映射的 DAG	通过结构体字段路由的并行分支

Compose 层会自动处理类型检查、节点间的流转换、并发、回调注入和选项分发。

-> 使用 /eino-compose 构建图、链、工作流，并处理流式输出、回调和状态管理。

ADK（Agent 开发工具包）

用于构建 AI Agent 的高级抽象，封装了模型-工具-循环模式。

概念	功能
ChatModelAgent	ReAct 风格的 Agent：模型生成内容、调用工具并循环执行，直至完成
DeepAgent	预构建 Agent，具备文件系统后端、工具搜索和摘要功能
Runner	执行 Agent、管理检查点并发出事件流
Middleware (Handlers)	拦截并扩展 Agent 行为（文件系统、摘要、计划-任务等）
Interrupt/Resume	人机协作：暂停 Agent、获取用户输入，并从检查点恢复
AgentTool	将 Agent 封装为可由其他 Agent 调用的工具

-> 使用 /eino-agent 构建 Agent、配置中间件和运行器，并实现人机协作。

Schema

各层共用的数据类型：

• schema.Message -- 对话消息（system/user/assistant/tool 角色、内容、工具调用）
• schema.Document -- 包含内容、元数据和向量嵌入的文档
• schema.ToolInfo -- 带有 JSON 架构参数的工具描述
• schema.StreamReader[T] -- 通用流式读取器（始终使用 defer stream.Close()）

仓库

仓库	作用
github.com/cloudwego/eino	核心：接口、架构、Compose 引擎、ADK、回调
github.com/cloudwego/eino-ext	实现：模型提供方、向量存储、工具、回调处理器

软件包速览

eino（核心）：

软件包	包含内容
schema	Message、Document、ToolInfo、StreamReader
components/model	ChatModel 和 AgenticModel 接口
components/tool	工具接口（BaseTool、InvokableTool、StreamableTool 及其增强变体）
components/embedding	Embedder 接口
components/retriever	Retriever 接口
components/indexer	Indexer 接口
components/document	Loader、Transformer 接口
components/prompt	ChatTemplate 接口
compose	Graph、Chain、Workflow、ToolsNode、Runnable、状态、检查点
callbacks	Handler 接口、全局／单次运行注册
adk	Agent、Runner、ChatModelAgent、中间件、中断／恢复
adk/prebuilt/deep	DeepAgent 预设

eino-ext（实现）：

软件包	包含内容
components/model/{provider}	ChatModel 实现（openai、claude、gemini、ark、ollama、deepseek、qwen 等）
components/embedding/{provider}	Embedding 实现（openai、ark、ollama 等）
components/retriever/{backend}	Retriever 实现（redis、milvus2、es8、qdrant）
components/indexer/{backend}	Indexer 实现（redis、milvus2、es8、qdrant）
components/tool/{type}	工具实现（mcp、googlesearch、duckduckgo、bingsearch 等）
callbacks/{provider}	回调处理程序（cozeloop、apmplus、langfuse、langsmith）
adk/backend/local	DeepAgent 的本地文件系统 Backend

选择合适的方法

场景	方法	技能
单次模型调用（生成或流式传输）	直接使用 ChatModel	/eino-component
带工具的多轮 Agent	ChatModelAgent + Runner	/eino-agent
生产环境中的 Agent，支持文件系统和工具搜索	DeepAgent	/eino-agent
线性管道（模板 -> 模型）	Chain	/eino-compose
带分支或循环的复杂流程	Graph	/eino-compose
带字段映射的并行分支	Workflow	/eino-compose
RAG（嵌入 + 索引 + 检索）	Indexer + Retriever + Embedding	/eino-component
需要人工审批的 Agent	Interrupt/Resume + Runner	/eino-agent
可观测性与追踪	回调处理程序	/eino-component

参考文件

• reference/schema.md -- 所有层级共用的核心数据类型：Message、Document、ToolInfo、StreamReader
• reference/runnable.md -- Runnable[I, O] 接口、四种执行模式、运行时选项
• reference/quick-start.md -- 三个完整可运行示例（ChatModel、Agent+Runner、Chain）

给 Agent 的说明

1. 问题明确时，将其路由到相应技能（/eino-component、/eino-compose、/eino-agent）。请参阅“选择合适的方法”表格。
2. 始终使用来自 github.com/cloudwego/eino 和 github.com/cloudwego/eino-ext 的实际导入路径提供 Go 代码示例。
3. 对于组件实现细节，生成代码前务必先阅读提供方的参考文件。不要臆测构造函数或配置的命名约定。
4. 对于 Agent 使用场景，优先采用 ADK（ChatModelAgent + Runner），而不是用 compose 图手动构建 ReAct 循环。对于需要抢占和生命周期管理的交互式多轮应用，建议使用 TurnLoop。
5. 展示流式代码时，始终包含 defer stream.Close()。