eino-component

Eino 组件指南

组件选择指南

ChatModel——LLM 推理（经典 Message 路径）

提供商	包	备注
OpenAI	model/openai	也支持 Azure，设置 ByAzure: true 即可
Claude	model/claude	也支持 AWS Bedrock，设置 ByBedrock: true 即可
Gemini	model/gemini	需要 genai.Client
Ark (Volcengine)	model/ark	Doubao 模型
Ollama	model/ollama	本地模型
DeepSeek	model/deepseek	支持推理
Qwen	model/qwen	阿里云 DashScope API
Qianfan	model/qianfan	百度 ERNIE 模型
OpenRouter	model/openrouter	多提供商路由

AgenticModel——LLM 推理（AgenticMessage 路径）

AgenticModel 处理 *schema.AgenticMessage，其内容采用基于块的结构（推理、文本、图像、音频、视频、工具调用/结果）。工具始终通过 model.WithTools 选项在调用时传入（没有 WithTools 方法）。

提供商	包	备注
OpenAI	model/agenticopenai	GPT-4o、o1、o3 系列
Gemini	model/agenticgemini	Gemini 2.x 模型
DeepSeek	model/agenticdeepseek	支持推理的 DeepSeek-R1
Ark (Volcengine)	model/agenticark	Doubao 模型（Agentic 路径）
Qwen	model/agenticqwen	通过 DashScope 使用 Qwen 系列

详细配置参考：

• reference/model/agenticopenai.md
• reference/model/agenticgemini.md
• reference/model/agenticdeepseek.md
• reference/model/agenticark.md
• reference/model/agenticqwen.md

Embedding——文本转向量

提供商	包	备注
OpenAI	embedding/openai	text-embedding-3-small/large、ada-002
Ark	embedding/ark	Volcengine 嵌入模型
Gemini	embedding/gemini	Google 嵌入模型
DashScope	embedding/dashscope	阿里云嵌入模型
Ollama	embedding/ollama	本地嵌入模型
Qianfan	embedding/qianfan	百度嵌入模型

Retriever——向量/关键词搜索

后端	包	备注
Redis	retriever/redis	KNN 和范围向量搜索
Milvus 2.x	retriever/milvus2	稠密 + 稀疏混合、BM25
Elasticsearch 8	retriever/es8	近似向量搜索
Qdrant	retriever/qdrant	向量相似度搜索

Indexer——存储带向量的文档

后端	包
Redis	indexer/redis
Milvus 2.x	indexer/milvus2
Elasticsearch 8	indexer/es8
Qdrant	indexer/qdrant

Tools——模型可调用的函数

工具	包	备注
MCP	tool/mcp	Model Context Protocol 工具
Google Search	tool/googlesearch	Custom Search JSON API
DuckDuckGo	tool/duckduckgo	网络搜索（使用 v2）
Bing Search	tool/bingsearch	Bing Web Search API
HTTP Request	tool/httprequest	通用 HTTP 调用
Command Line	tool/commandline	Shell 命令执行
Browser Use	tool/browseruse	浏览器自动化

接口速查

// BaseModel (generic)
type BaseModel[M any] interface {
    Generate(ctx context.Context, input []M, opts ...Option) (M, error)
    Stream(ctx context.Context, input []M, opts ...Option) (*schema.StreamReader[M], error)
}

// Type aliases
type BaseChatModel = BaseModel[*schema.Message]       // classic path
type AgenticModel = BaseModel[*schema.AgenticMessage] // agentic path

// ToolCallingChatModel (classic path, adds WithTools)
type ToolCallingChatModel interface {
    BaseChatModel
    WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
}

// Embedding
type Embedder interface {
    EmbedStrings(ctx context.Context, texts []string, opts ...Option) ([][]float64, error)
}

// Retriever
type Retriever interface {
    Retrieve(ctx context.Context, query string, opts ...Option) ([]*schema.Document, error)
}

// Indexer
type Indexer interface {
    Store(ctx context.Context, docs []*schema.Document, opts ...Option) (ids []string, err error)
}

// Document
type Loader interface {
    Load(ctx context.Context, src Source, opts ...LoaderOption) ([]*schema.Document, error)
}
type Transformer interface {
    Transform(ctx context.Context, src []*schema.Document, opts ...TransformerOption) ([]*schema.Document, error)
}

// Tool
type BaseTool interface {
    Info(ctx context.Context) (*schema.ToolInfo, error)
}

type InvokableTool interface {
    BaseTool
    InvokableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (string, error)
}

// Prompt
type ChatTemplate interface {
    Format(ctx context.Context, vs map[string]any, opts ...Option) ([]*schema.Message, error)
}

安装

go get github.com/cloudwego/eino-ext/components/{type}/{impl}@latest
# Examples:
go get github.com/cloudwego/eino-ext/components/model/openai@latest
go get github.com/cloudwego/eino-ext/components/model/agenticopenai@latest
go get github.com/cloudwego/eino-ext/components/retriever/milvus2@latest
go get github.com/cloudwego/eino-ext/components/tool/mcp@latest

ChatModel 用法（经典路径）

生成

resp, err := chatModel.Generate(ctx, []*schema.Message{
    {Role: schema.User, Content: "Hello"},
})
fmt.Println(resp.Content)

流式传输

reader, err := chatModel.Stream(ctx, messages)
defer reader.Close()
for {
    chunk, err := reader.Recv()
    if errors.Is(err, io.EOF) { break }
    if err != nil { return err }
    fmt.Print(chunk.Content)
}

工具调用

withTools, err := chatModel.WithTools([]*schema.ToolInfo{toolInfo})
resp, err := withTools.Generate(ctx, messages)
// resp.ToolCalls contains model's tool invocations

AgenticModel 用法

import (
    "github.com/cloudwego/eino-ext/components/model/agenticopenai"
    "github.com/cloudwego/eino/components/model"
    "github.com/cloudwego/eino/schema"
)

// Create agentic model
am, _ := agenticopenai.New(ctx, &agenticopenai.Config{
    Model:  "gpt-4o",
    APIKey: "your-key",
})

// Tools passed at call time via option for AgenticModel-interface code
resp, err := am.Generate(ctx,
    []*schema.AgenticMessage{schema.UserAgenticMessage("Search for Go tutorials")},
    model.WithTools(toolInfos),
)

// Response contains typed ContentBlocks
for _, block := range resp.ContentBlocks {
    switch block.Type {
    case schema.ContentBlockTypeAssistantGenText:
        fmt.Println(block.AssistantGenText.Text)
    case schema.ContentBlockTypeFunctionToolCall:
        fmt.Printf("Tool call: %s(%s)\n", block.FunctionToolCall.Name, block.FunctionToolCall.Arguments)
    case schema.ContentBlockTypeReasoning:
        fmt.Printf("Reasoning: %s\n", block.Reasoning.Text)
    }
}

RAG 组件

Embedding + Indexer + Retriever 构成 RAG 工作流：

// 1. Embed and store documents
indexer, _ := redisIndexer.NewIndexer(ctx, &redisIndexer.IndexerConfig{
    Client: redisClient, KeyPrefix: "doc:", Embedding: embedder,
})
ids, _ := indexer.Store(ctx, docs)

// 2. Retrieve relevant documents
retriever, _ := redisRetriever.NewRetriever(ctx, &redisRetriever.RetrieverConfig{
    Client: redisClient, Index: "my_index", Embedding: embedder,
})
docs, _ := retriever.Retrieve(ctx, "user query", retriever.WithTopK(5))

工具用法

MCP 工具

import mcpp "github.com/cloudwego/eino-ext/components/tool/mcp"

tools, err := mcpp.GetTools(ctx, &mcpp.Config{Cli: mcpClient})

自定义 InvokableTool

实现 Info() 和 InvokableRun()，即可创建自定义工具。

给 Agent 的说明

• 各实现的构造函数签名和 Config 结构体名称各不相同。生成初始化代码前，请务必先阅读 reference/{type}/{impl}.md 中对应提供方的参考文件。
• 根据用户需求，使用 BaseChatModel（经典路径）或 AgenticModel（Agentic 路径）。
• model.AgenticModel 接口不会新增 WithTools 方法。对于面向接口的代码，建议在调用时使用 model.WithTools(...)。
• 对于 ADK Agent，ChatModelAgentConfig.Model 字段接受 model.BaseModel[M]——两种路径都可以无缝使用。
• 对于 RAG，请确保索引和检索使用相同的 Embedder 模型。
• 各组件的详细文档请参阅参考文件。

参考文件

需要详细了解 API、配置和示例时，按需阅读文件。每个 {type}/ 目录都包含一个 overview.md（接口和常见模式）以及各实现对应的文件：

• reference/model/*.md -- ChatModel 和 AgenticModel 接口、工具绑定、流式处理，以及各提供方的配置（openai、claude、gemini、ark、ollama、deepseek、qwen、qianfan、openrouter）
• reference/embedding/*.md -- Embedder 接口和各提供方的配置（openai、ark、ollama 等）
• reference/retriever/*.md -- Retriever 接口、RAG 示例，以及各后端的配置（redis、milvus2、es8）
• reference/indexer/*.md -- Indexer 接口、索引管线，以及各后端的配置（redis、milvus2、es8、qdrant）
• reference/tool/*.md -- 工具接口、自定义工具创建、MCP 集成、搜索工具、实用工具
• reference/document/pipeline.md -- Loader、Parser、Transformer 接口及完整的管线示例
• reference/prompt.md -- ChatTemplate、FString/GoTemplate/Jinja2 格式、消息辅助工具
• reference/callback/*.md -- Callback 处理程序接口、注册模式，以及各提供方的配置（cozeloop、apmplus、langfuse、langsmith）