Eino 深度实战：Go 语言 LLM 应用开发的组件化革命——从架构哲学到生产级 Agent 构建的完全指南（2026）

引言：为什么 Go 社区需要一个"LangChain"

Python 在 AI 应用开发领域占据了绝对统治地位——LangChain、LlamaIndex、CrewAI 等框架让 Python 开发者可以快速搭建 LLM 应用。但现实是，绝大多数生产级后端服务跑在 Go 上。微服务、API Gateway、消息队列、云原生基础设施，Go 是当之无愧的主力语言。

这就产生了一个尴尬的断层：你的业务服务用 Go 写，但 AI 能力用 Python 接入。多语言栈带来额外的运维成本、部署复杂度和团队协作壁垒。

2025 年，字节跳动 CloudWeGo 团队开源了 Eino（读作 ['aino]），一个专为 Go 语言设计的 LLM 应用开发框架。截至 2026 年 6 月，GitHub 星标已突破 11,500+，Fork 数超过 940，最新版本 v0.9.2，背后是字节跳动在生产环境大规模使用的验证。

Eino 不是简单的 LangChain Go 移植版。它从 LangChain、Google ADK 等框架中汲取灵感，但严格遵循 Go 的设计哲学——接口抽象、组合优于继承、显式错误处理。这是一篇面向 Go 程序员的深度指南，从架构设计到代码实战，带你完整掌握 Eino。

一、核心定位：组件化 + 编排 + Agent 三件套

Eino 的核心定位用一句话概括：组件化 + 编排 + Agent，三件套搞定 AI 应用。

1.1 组件化思维：Everything is a Component

Eino 的设计哲学核心是万物皆组件：

• Model 是组件 —— 封装大模型调用
• Prompt 是组件 —— 提示词模板管理
• Tool 是组件 —— 外部工具调用
• Memory 是组件 —— 对话记忆管理
• Retriever 是组件 —— 知识检索
• Workflow 本身也是组件 —— 可嵌套、可复用

所有组件都遵循统一的接口设计，意味着你可以自由组合、替换、编排任何组件。换一个模型？改一行配置。换一个向量数据库？换一个 Retriever 实现。上层业务代码完全不动。

这种设计哲学与 Go 语言的 io.Reader / io.Writer 接口设计如出一辙——定义最小化的接口，通过组合实现复杂功能。

1.2 编排能力：Chain / Graph / Workflow

Eino 提供三种编排方式，覆盖从简单到复杂的所有场景：

• Chain（链式调用）：简单的线性流水线，A → B → C，适合数据处理管道
• Graph（图编排）：有向无环图，支持分支、合并、条件路由，适合复杂的决策逻辑
• Workflow（工作流）：更高级的编排，支持循环、人工介入、状态管理和恢复

1.3 Agent 能力

从最简单的 ChatModelAgent（模型 + 工具调用）到复杂的 DeepAgent（多步推理、工具链、记忆管理），Eino 提供了完整的 Agent 构建方案。

二、架构全景：三层抽象设计

Eino 的架构分为清晰的三层，每一层职责明确、边界清晰：

┌──────────────────────────────────────────┐
│         Application Layer                │  你的业务代码
│   (API Handler / Business Logic)         │
├──────────────────────────────────────────┤
│         Orchestration Layer              │  Chain / Graph / Workflow
│   (流程编排 / 条件路由 / 状态管理)          │
├──────────────────────────────────────────┤
│         Component Layer                  │  ChatModel / Tool / Retriever
│   (AI 能力抽象 / 可替换实现)               │  Memory / Embedding / Prompt
└──────────────────────────────────────────┘

这种分层设计有几个关键优势：

1. 关注点分离：业务逻辑不关心具体用哪个模型，编排层不关心业务语义
2. 可测试性：每一层都可以独立测试，Mock 替换非常方便
3. 可演进性：升级模型或更换组件不影响上层代码

2.1 组件层详解

组件层定义了所有 AI 能力的抽象接口。核心组件一览：

2.2 编排层详解

编排层是 Eino 的灵魂。它不只是一个简单的函数调用链——它是一个完整的图执行引擎，支持：

• 节点注册与连接
• 条件分支（基于运行时数据路由到不同节点）
• 并行执行（多个节点同时运行）
• 状态传递（节点间的数据流）
• 错误处理（节点失败后的回退策略）

三、环境搭建与快速开始

3.1 项目初始化

# 创建项目目录
mkdir eino-demo && cd eino-demo
go mod init eino-demo

# 安装 Eino 核心
go get github.com/cloudwego/eino@latest

# 安装 OpenAI 模型扩展（兼容 DeepSeek/Qwen/Ollama）
go get github.com/cloudwego/eino-ext/components/model/openai@latest

# 安装 OpenAI Embedding 扩展（可选）
go get github.com/cloudwego/eino-ext/components/embedding/openai@latest

3.2 第一个对话程序

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/schema"
)

func main() {
    ctx := context.Background()

    // 创建模型组件 —— 这是所有 AI 应用的起点
    model, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
        APIKey: os.Getenv("OPENAI_API_KEY"),
        Model:  "gpt-4o",
    })
    if err != nil {
        log.Fatalf("创建 ChatModel 失败: %v", err)
    }

    // 构造消息列表
    messages := []*schema.Message{
        schema.SystemMessage("你是一个资深 Go 语言工程师，擅长后端架构设计"),
        schema.UserMessage("用 300 字解释 Go 语言的 goroutine 调度器 GMP 模型"),
    }

    // 一次性生成完整回复
    response, err := model.Generate(ctx, messages)
    if err != nil {
        log.Fatalf("生成失败: %v", err)
    }

    fmt.Println("模型回复：")
    fmt.Println(response.Content)
}

3.3 流式输出实战

流式输出是现代 AI 应用的标配——用户不需要等待完整生成才能看到内容。Eino 的流式接口非常 Go 化：

package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "os"

    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/schema"
)

func streamChat(ctx context.Context, model *openai.ChatModel, question string) error {
    messages := []*schema.Message{
        schema.SystemMessage("你是一个技术助手"),
        schema.UserMessage(question),
    }

    // 获取流式 Reader —— 注意这里用 Stream 而不是 Generate
    reader, err := model.Stream(ctx, messages)
    if err != nil {
        return err
    }
    defer reader.Close()

    // 逐 chunk 读取并输出
    for {
        chunk, err := reader.Recv()
        if err != nil {
            if err == io.EOF {
                break // 正常结束
            }
            return err // 异常
        }
        fmt.Print(chunk.Content) // 逐字输出，用户体验更好
    }
    fmt.Println()
    return nil
}

3.4 模型切换的艺术

Eino 最实用的特性之一是模型无关。切换模型提供商只需要改配置，代码完全不动：

// 使用 DeepSeek —— 只需改 BaseURL 和 APIKey
model, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
    BaseURL: "https://api.deepseek.com/v1",
    APIKey:  os.Getenv("DEEPSEEK_API_KEY"),
    Model:   "deepseek-chat",
})

// 使用通义千问
model, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
    BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
    APIKey:  os.Getenv("QWEN_API_KEY"),
    Model:   "qwen-plus",
})

// 使用本地 Ollama —— 开发阶段零成本
model, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
    BaseURL: "http://localhost:11434/v1",
    Model:   "qwen2.5:14b",
    // APIKey 不需要，Ollama 本地部署无需鉴权
})

背后的原理很简单：Eino 的 OpenAI 扩展基于 OpenAI 兼容协议，而几乎所有主流模型提供商都支持这个协议（DeepSeek、Qwen、Ollama、vLLM、LiteLLM 等）。这种统一的接口设计让模型切换变得像换数据库驱动一样简单。

实际建议：开发阶段用本地 Ollama 模型节省 API 费用，测试和预发环境用 DeepSeek/Qwen 这类性价比高的模型，生产环境用 GPT-4o 或 Claude。三套环境，一套代码。

四、提示词工程：Eino 的模板系统

4.1 FString 模板引擎

Eino 内置了 FString 模板引擎，支持变量占位符的动态注入。这比 Python 的 f-string 略显朴素，但完全满足 Go 的工程需求：

import (
    "github.com/cloudwego/eino/components/prompt"
    "github.com/cloudwego/eino/schema"
)

// 创建带变量的提示词模板
template, err := prompt.FromMessages(
    schema.FString, // 指定使用 FString 模板引擎
    schema.SystemMessage("你是一个{role}，擅长{skill}领域的问题"),
    schema.UserMessage("{question}"),
)
if err != nil {
    log.Fatal(err)
}

// 动态渲染模板
messages, err := template.Format(map[string]any{
    "role":     "Go 后端架构师",
    "skill":    "高并发系统设计和分布式架构",
    "question": "如何设计一个支撑百万用户同时在线的即时通讯系统？",
})

4.2 管理多套提示词

生产环境通常需要管理多套提示词（不同场景、不同版本）。Eino 的模板系统配合配置文件可以优雅地解决这个问题：

// 提示词配置结构
type PromptConfig struct {
    SystemPrompt string `yaml:"system_prompt"`
    Template     string `yaml:"template"`
}

// 从配置文件加载提示词
func loadPrompts(path string) map[string]*PromptConfig {
    data, _ := os.ReadFile(path)
    var prompts map[string]*PromptConfig
    yaml.Unmarshal(data, &prompts)
    return prompts
}

// 使用
prompts := loadPrompts("prompts.yaml")
techTemplate, _ := prompt.FromMessages(
    schema.FString,
    schema.SystemMessage(prompts["tech_assistant"].SystemPrompt),
    schema.UserMessage(prompts["tech_assistant"].Template),
)

五、Tool Calling：让 Agent 操控外部世界

Tool Calling 是 AI Agent 区别于普通对话系统的核心能力——模型不是只会"说话"，而是能"做事"。

5.1 定义一个工具

Eino 的 Tool 定义非常 Go 化——就是一个普通的 Go 函数，加上结构化的输入输出类型：

package tools

import "context"

// ========== 工具入参 ==========
type WeatherRequest struct {
    City string `json:"city" jsonschema:"description=要查询的城市名称，如：北京、上海"`
}

// ========== 工具出参 ==========
type WeatherResponse struct {
    City     string `json:"city"`
    Temp     string `json:"temp"`
    Weather  string `json:"weather"`
    Humidity string `json:"humidity"`
    Wind     string `json:"wind"`
}

// ========== 工具实现 ==========
func GetWeather(ctx context.Context, req *WeatherRequest) (*WeatherResponse, error) {
    // 生产环境调用真实天气 API
    // 这里用模拟数据演示
    mockData := map[string]WeatherResponse{
        "北京": {City: "北京", Temp: "28°C", Weather: "晴", Humidity: "45%", Wind: "北风3级"},
        "上海": {City: "上海", Temp: "31°C", Weather: "多云", Humidity: "72%", Wind: "东南风2级"},
        "深圳": {City: "深圳", Temp: "33°C", Weather: "阵雨", Humidity: "85%", Wind: "南风4级"},
    }
    if data, ok := mockData[req.City]; ok {
        return &data, nil
    }
    return &WeatherResponse{City: req.City, Temp: "未知", Weather: "未知"}, nil
}

5.2 注册为 Eino Tool

import (
    "github.com/cloudwego/eino/components/tool"
)

// 将普通 Go 函数注册为 Eino Tool
var WeatherTool = tool.NewTool(
    GetWeather,
    &tool.ToolInfo{
        Name: "get_weather",
        Desc: "获取指定城市的实时天气信息，包括温度、天气状况、湿度和风力",
    },
)

Eino 会自动从 Go 结构体的 jsonschema tag 提取参数描述，生成模型能理解的 Tool Schema。这意味着你不需要额外编写 JSON Schema——Go 的类型系统就是你的 Schema。

5.3 多工具 Agent

import "github.com/cloudwego/eino/agent"

func createMultiToolAgent(ctx context.Context, model *openai.ChatModel) *agent.ChatModelAgent {
    a := agent.NewChatModelAgent(ctx, model)

    // 一次性注册多个工具
    a.AddTools(
        WeatherTool,
        SearchTool,       // 搜索工具
        CodeExecTool,      // 代码执行工具
        DBQueryTool,       // 数据库查询工具
    )

    return a
}

// 使用
agent := createMultiToolAgent(ctx, model)
resp, _ := agent.Generate(ctx, []*schema.Message{
    schema.UserMessage("帮我查一下北京今天的天气，顺便搜索一下 Go 1.24 有什么新特性"),
})

// 模型会自动：
// 1. 解析用户意图（需要天气 + 需要搜索）
// 2. 并行调用 get_weather 和 search
// 3. 综合两个工具的返回结果生成最终回答

六、RAG 实战：构建知识增强的 AI 应用

RAG（Retrieval-Augmented Generation，检索增强生成）是当前最实用的 AI 应用架构之一。它解决了一个核心问题：大模型的训练数据有截止日期，无法获取最新信息；而企业有大量内部知识需要 AI 理解和利用。

6.1 RAG 架构全景

用户提问
    │
    ▼
┌──────────────┐
│ Embedding     │  将问题转化为向量
│ Model         │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Retriever    │  从向量数据库中检索相关文档
│               │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Context      │  将检索结果 + 用户问题拼接为完整上下文
│ Assembly      │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ LLM          │  基于增强上下文生成回答
│ Generate      │
└──────┬───────┘
       │
       ▼
   最终回答

6.2 完整 RAG Chain 实现

package main

import (
    "context"
    "fmt"
    "log"
    "strings"

    "github.com/cloudwego/eino/components/prompt"
    "github.com/cloudwego/eino/compose"
    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/schema"
)

// 构建完整的 RAG 处理链
func buildRAGChain(
    ctx context.Context,
    model *openai.ChatModel,
    ret retriever.Retriever, // 你的 Retriever 实现
) *compose.Chain[string, string] {

    // Step 1: 文档拼接器 —— 将检索到的文档合并为文本
    docAssembler := compose.NewLambda(
        func(ctx context.Context, docs []*schema.Document) (string, error) {
            var sb strings.Builder
            for i, doc := range docs {
                sb.WriteString(fmt.Sprintf("[文档 %d]\n%s\n\n", i+1, doc.Content))
            }
            return sb.String(), nil
        },
    )

    // Step 2: RAG 提示词模板
    ragTemplate, _ := prompt.FromMessages(
        schema.FString,
        schema.SystemMessage(`你是一个知识库问答助手。请根据以下参考资料回答用户问题。

注意事项：
1. 只使用参考资料中提供的信息，不要编造
2. 如果参考资料中没有相关信息，请如实说明
3. 回答时引用具体的参考来源

参考资料：
{context}`),
        schema.UserMessage("{question}"),
    )

    // Step 3: 串联成 Chain
    chain := compose.NewChain[string, string]()
    chain.
        AppendRetriever(ret).             // 检索相关文档
        AppendLambda(docAssembler).        // 拼接文档内容
        AppendPromptTemplate(ragTemplate).   // 构建 RAG 提示词
        AppendChatModel(model).             // LLM 生成回答
        AppendTransform(compose.NewLambda(
            func(ctx context.Context, msg *schema.Message) (string, error) {
                return msg.Content, nil
            },
        ))

    return chain
}

func main() {
    ctx := context.Background()

    // 初始化模型
    model, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
        APIKey: os.Getenv("OPENAI_API_KEY"),
        Model:  "gpt-4o",
    })

    // 初始化 Retriever（可以是向量数据库、BM25、混合检索）
    ret := initRetriever(ctx)

    // 构建 Chain
    chain := buildRAGChain(ctx, model, ret)

    // 使用
    answer, err := chain.Invoke(ctx, "Go 1.22 的 sync.Once 做了哪些改进？")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(answer)
}

6.3 混合检索策略

生产环境的 RAG 通常采用混合检索（向量检索 + 关键词检索）以提高召回率：

// 并发执行两种检索，合并结果
func hybridRetrieve(ctx context.Context, query string, vectorRet, bm25Ret retriever.Retriever) []*schema.Document {
    type result struct {
        docs []*schema.Document
        err  error
    }

    ch := make(chan result, 2)

    // 向量检索
    go func() {
        docs, err := vectorRet.Retrieve(ctx, query)
        ch <- result{docs, err}
    }()

    // BM25 关键词检索
    go func() {
        docs, err := bm25Ret.Retrieve(ctx, query)
        ch <- result{docs, err}
    }()

    // 合并去重
    seen := make(map[string]bool)
    var allDocs []*schema.Document
    for i := 0; i < 2; i++ {
        r := <-ch
        if r.err != nil {
            log.Printf("检索失败: %v", r.err)
            continue
        }
        for _, doc := range r.docs {
            if !seen[doc.ID] {
                seen[doc.ID] = true
                allDocs = append(allDocs, doc)
            }
        }
    }

    return allDocs
}

七、Graph 编排：构建复杂的多步工作流

当 AI 应用的处理逻辑不再是简单的线性流水线时，Graph 编排就派上用场了。Graph 支持条件分支、并行执行、状态管理等复杂模式。

7.1 意图路由 Graph

一个典型的场景：根据用户输入的意图，路由到不同的处理节点。

func buildRouterGraph(ctx context.Context, model *openai.ChatModel) *compose.Graph[string, string] {
    graph := compose.NewGraph[string, string]()

    // 节点 1：意图分类器
    classifier := compose.NewLambda(func(ctx context.Context, input string) (string, error) {
        messages := []*schema.Message{
            schema.SystemMessage(
                "你是一个意图分类器。将用户输入分为以下三类之一：\n" +
                "- code：需要生成或分析代码\n" +
                "- search：需要搜索信息\n" +
                "- chat：普通对话\n\n" +
                "只输出分类名称，不要输出其他内容。",
            ),
            schema.UserMessage(input),
        }
        resp, err := model.Generate(ctx, messages)
        if err != nil {
            return "", err
        }
        return strings.TrimSpace(resp.Content), nil
    })

    // 节点 2：代码生成处理器
    codeHandler := compose.NewLambda(func(ctx context.Context, input string) (string, error) {
        messages := []*schema.Message{
            schema.SystemMessage("你是一个代码生成专家。请生成高质量的、可直接运行的代码。"),
            schema.UserMessage(input),
        }
        resp, _ := model.Generate(ctx, messages)
        return resp.Content, nil
    })

    // 节点 3：搜索处理器
    searchHandler := compose.NewLambda(func(ctx context.Context, input string) (string, error) {
        // 调用搜索 API 获取信息
        results := searchAPI(input)
        messages := []*schema.Message{
            schema.SystemMessage("根据以下搜索结果回答用户问题：\n" + results),
            schema.UserMessage(input),
        }
        resp, _ := model.Generate(ctx, messages)
        return resp.Content, nil
    })

    // 节点 4：普通对话处理器
    chatHandler := compose.NewLambda(func(ctx context.Context, input string) (string, error) {
        messages := []*schema.Message{
            schema.SystemMessage("你是一个友好的助手，简洁专业地回答问题。"),
            schema.UserMessage(input),
        }
        resp, _ := model.Generate(ctx, messages)
        return resp.Content, nil
    })

    // 构建图结构
    graph.
        AddNode("classifier", classifier).
        AddNode("code", codeHandler).
        AddNode("search", searchHandler).
        AddNode("chat", chatHandler).
        AddEdge(compose.START, "classifier").    // 开始 → 分类
        AddBranch("classifier",                    // 分类 → 条件路由
            func(ctx context.Context, intent string) (string, error) {
                return intent, nil
            },
        ).
        AddEdge("code", compose.END).            // 各处理器 → 结束
        AddEdge("search", compose.END).
        AddEdge("chat", compose.END)

    return graph
}

7.2 带人工审核的工作流

企业级 AI 应用通常需要人工审核环节——AI 生成的内容不能直接对外发布。Eino 支持 Human-in-the-Loop 模式：

// 审核节点：工作流在这里暂停，等待人工确认
reviewNode := compose.NewLambda(func(ctx context.Context, draft string) (string, error) {
    fmt.Printf("\n========== AI 生成内容（待审核）==========\n")
    fmt.Printf("%s\n", draft)
    fmt.Printf("==========================================\n")
    fmt.Print("审核结果 [approve/reject]: ")

    var decision string
    fmt.Scanln(&decision)

    switch decision {
    case "approve":
        return draft, nil
    case "reject":
        return "", fmt.Errorf("内容被审核员拒绝")
    default:
        return "", fmt.Errorf("无效的审核指令: %s", decision)
    }
})

八、Memory：让 Agent 拥有记忆

无状态的对话不是真正的对话。Eino 提供了完整的记忆管理方案。

8.1 短期记忆（Buffer Memory）

import "github.com/cloudwego/eino/components/memory"

// 创建 Buffer Memory —— 保留最近 N 条消息
mem, _ := memory.NewBufferMemory(ctx, &memory.BufferMemoryConfig{
    MaxMessages: 20, // 保留最近 20 条消息（10 轮对话）
})

// 添加消息
mem.AddMessage(ctx, schema.UserMessage("我叫张三，是一名 Go 后端开发工程师"))
mem.AddMessage(ctx, schema.AssistantMessage("你好张三！很高兴认识你。"))

// 获取全部历史
history, _ := mem.GetMessages(ctx)

8.2 带记忆的完整 Agent

func createAgentWithMemory(ctx context.Context, model *openai.ChatModel) *agent.ChatModelAgent {
    // 创建记忆组件
    mem, _ := memory.NewBufferMemory(ctx, &memory.BufferMemoryConfig{
        MaxMessages: 20,
    })

    // 创建 Agent 并绑定记忆
    a := agent.NewChatModelAgent(ctx, model)
    a.WithMemory(mem)

    return a
}

func main() {
    agent := createAgentWithMemory(ctx, model)

    // 第一轮对话
    agent.Generate(ctx, []*schema.Message{
        schema.UserMessage("我叫张三，在一家金融科技公司做 Go 后端"),
    })

    // 第二轮对话 —— Agent 会记住之前的信息
    resp, _ := agent.Generate(ctx, []*schema.Message{
        schema.UserMessage("我叫什么名字？做什么工作的？"),
    })
    // 输出：你叫张三，在一家金融科技公司从事 Go 后端开发工作。
}

8.3 摘要记忆：突破上下文窗口限制

当对话历史很长时，保留所有原始消息不现实。摘要记忆通过定期压缩历史来解决这个问题：

// 摘要记忆策略：
// 1. 当消息数超过阈值时，将旧消息压缩为摘要
// 2. 保留最近 N 条原始消息 + 摘要
// 3. 模型看到的完整上下文 = 摘要 + 最近消息

type SummaryMemory struct {
    summary    string
    recent     []*schema.Message
    maxRecent  int
    summarizer *openai.ChatModel
}

func (m *SummaryMemory) AddMessage(ctx context.Context, msg *schema.Message) error {
    m.recent = append(m.recent, msg)

    // 超过阈值时触发摘要
    if len(m.recent) > m.maxRecent {
        m.summarize(ctx)
    }
    return nil
}

func (m *SummaryMemory) summarize(ctx context.Context) {
    // 取旧消息生成摘要
    old := m.recent[:len(m.recent)-5] // 保留最近 5 条
    m.recent = m.recent[len(m.recent)-5:]

    resp, _ := m.summarizer.Generate(ctx, []*schema.Message{
        schema.SystemMessage("请将以下对话历史压缩为一段简洁的摘要，保留关键信息："),
        schema.UserMessage(formatMessages(old)),
    })
    m.summary = resp.Content
}

九、与 Hertz 集成：构建生产级 AI HTTP 服务

字节跳动的 Hertz 是一个高性能 HTTP 框架（基于 Netpoll），与 Eino 同属 CloudWeGo 生态，天然适配。

9.1 SSE 流式聊天接口

package main

import (
    "context"
    "fmt"
    "io"
    "net/http"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
)

func main() {
    h := server.Default(server.WithHostPorts("0.0.0.0:8080"))

    // SSE 流式聊天端点
    h.GET("/api/chat/stream", func(ctx context.Context, c *app.RequestContext) {
        question := c.Query("q")
        if question == "" {
            c.JSON(consts.StatusBadRequest, map[string]string{"error": "参数 q 不能为空"})
            return
        }

        messages := []*schema.Message{
            schema.SystemMessage("你是一个技术助手，回答简洁专业"),
            schema.UserMessage(question),
        }

        reader, err := model.Stream(context.Background(), messages)
        if err != nil {
            c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
            return
        }
        defer reader.Close()

        // 设置 SSE 响应头
        c.SetContentType("text/event-stream")
        c.Header("Cache-Control", "no-cache")
        c.Header("Connection", "keep-alive")
        c.Header("X-Accel-Buffering", "no") // 防止 Nginx 缓冲
        c.SetStatusCode(consts.StatusOK)

        for {
            chunk, err := reader.Recv()
            if err == io.EOF {
                c.Write([]byte("data: [DONE]\n\n"))
                c.Flush()
                break
            }
            if err != nil {
                break
            }
            data := fmt.Sprintf("data: {\"content\":\"%s\"}\n\n", chunk.Content)
            c.Write([]byte(data))
            c.Flush()
        }
    })

    // 非流式聊天端点
    h.POST("/api/chat", func(ctx context.Context, c *app.RequestContext) {
        var req ChatRequest
        c.Bind(&req)

        messages := []*schema.Message{
            schema.SystemMessage("你是一个技术助手"),
            schema.UserMessage(req.Message),
        }

        response, err := model.Generate(context.Background(), messages)
        if err != nil {
            c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
            return
        }

        c.JSON(consts.StatusOK, ChatResponse{
            Content: response.Content,
        })
    })

    h.Spin()
}

9.2 中间件设计

生产环境需要限流、鉴权、日志等中间件：

// Token 鉴权中间件
func AuthMiddleware() app.HandlerFunc {
    return func(ctx context.Context, c *app.RequestContext) {
        token := c.GetHeader("Authorization")
        if token == "" || !validateToken(strings.TrimPrefix(token, "Bearer ")) {
            c.JSON(consts.StatusUnauthorized, map[string]string{"error": "未授权"})
            c.Abort()
            return
        }
        c.Next(ctx)
    }
}

// 限流中间件（基于令牌桶）
func RateLimitMiddleware() app.HandlerFunc {
    limiter := rate.NewLimiter(rate.Limit(10), 100) // 10 QPS，突发 100
    return func(ctx context.Context, c *app.RequestContext) {
        if !limiter.Allow() {
            c.JSON(consts.StatusTooManyRequests, map[string]string{"error": "请求过于频繁"})
            c.Abort()
            return
        }
        c.Next(ctx)
    }
}

十、可观测性：生产环境的必备能力

没有可观测性的 AI 服务就像黑盒——出问题你都不知道是模型问题、网络问题还是代码问题。

10.1 链路追踪

Eino 内置了可观测性支持：

import "github.com/cloudwego/eino/components/observability"

// 启用追踪 —— 与 OpenTelemetry 集成
compose.WithTracer(observability.NewOTelTracer(
    observability.WithServiceName("eino-demo"),
    observability.WithExporter(endpoint),
))

// 启用结构化日志
compose.WithLogger(log.New(os.Stdout, "[Eino] ", log.LstdFlags|log.Lmicroseconds))

10.2 关键指标监控

在生产环境中，你需要监控这些关键指标：

// 自定义指标收集器
type MetricsCollector struct {
    requestCount    prometheus.Counter
    tokenUsage      *prometheus.CounterVec
    latencyHistogram *prometheus.HistogramVec
    toolCallCount   *prometheus.CounterVec
}

// 在每个组件调用中埋点
func withMetrics[T any](name string, fn func() (T, error)) (T, error) {
    start := time.Now()
    result, err := fn()
    duration := time.Since(start)

    mc.requestCount.Inc()
    mc.latencyHistogram.WithLabelValues(name).Observe(duration.Seconds())

    return result, err
}

十一、Eino vs LangChain：设计哲学对比

作为一个 Go 程序员，理解两个框架的设计差异有助于你做出正确的技术选型。

选择建议：

• 如果你的后端已经是 Go 技术栈，Eino 是最佳选择——不需要引入 Python 运行时
• 如果你需要快速验证 AI 想法，LangChain 的生态更成熟
• 如果你需要高并发、低延迟的 AI 服务，Go + Eino 的性能优势明显

十二、性能优化实践

12.1 连接池与复用

// 模型客户端复用 —— 不要每次请求都创建新的 ChatModel
var globalModel *openai.ChatModel

func initModel() {
    m, err := openai.NewChatModel(context.Background(), &openai.ChatModelConfig{
        APIKey: os.Getenv("OPENAI_API_KEY"),
        Model:  "gpt-4o",
    })
    if err != nil {
        log.Fatal(err)
    }
    globalModel = m
}

// 在 HTTP handler 中直接使用全局 model
h.GET("/api/chat", func(ctx context.Context, c *app.RequestContext) {
    reader, _ := globalModel.Stream(ctx, messages)
    // ...
})

12.2 并发检索优化

// 并行调用多个 Retriever，减少总延迟
func parallelRetrieve(ctx context.Context, query string, retrievers []retriever.Retriever) []*schema.Document {
    var (
        allDocs []*schema.Document
        mu      sync.Mutex
        wg      sync.WaitGroup
    )

    for _, r := range retrievers {
        wg.Add(1)
        go func(ret retriever.Retriever) {
            defer wg.Done()
            docs, err := ret.Retrieve(ctx, query)
            if err == nil {
                mu.Lock()
                allDocs = append(allDocs, docs...)
                mu.Unlock()
            }
        }(r)
    }
    wg.Wait()

    return allDocs
}

12.3 流式处理缓冲优化

// 使用 bufio.Writer 减少 I/O 次数，提高 SSE 吞吐
func handleSSEStream(reader Stream[*schema.Message], w io.Writer) {
    bw := bufio.NewWriterSize(w, 4096) // 4KB 缓冲区
    defer bw.Flush()

    for {
        chunk, err := reader.Recv()
        if err == io.EOF {
            break
        }
        bw.WriteString(chunk.Content)
        // 不需要每次都 Flush，bufio 会在缓冲区满时自动刷新
    }
}

12.4 缓存策略

// 语义缓存 —— 相似问题的回答可以复用
type SemanticCache struct {
    embedder  embedding.Embedder
    store     *lru.Cache // 或 Redis
    threshold float64   // 相似度阈值
}

func (c *SemanticCache) Get(ctx context.Context, question string) (string, bool) {
    queryVec, _ := c.embedder.Embed(ctx, question)

    // 在缓存中查找相似问题
    for _, item := range c.store.Items() {
        similarity := cosineSimilarity(queryVec, item.Vector)
        if similarity >= c.threshold {
            return item.Answer, true
        }
    }
    return "", false
}

十三、总结与展望

Eino 代表了 Go 语言在 AI 应用开发领域的一个重要里程碑。它不是简单的"LangChain Go 版"——而是一个真正遵循 Go 设计哲学的 AI 框架。

核心价值回顾

1. 组件化设计：万物皆组件，自由组合、随时替换，符合 Go 的接口组合哲学
2. 模型无关：切换模型提供商只需改配置，代码零改动
3. 编排灵活：Chain / Graph / Workflow 三级编排，从简单到复杂全覆盖
4. Agent 完整：从基础工具调用到多步推理，Agent 能力开箱即用
5. 工程化就绪：可观测性、链路追踪、性能优化，生产环境所需一应俱全
6. Go 生态融合：与 Hertz、Kitex 等 CloudWeGo 组件无缝集成，与 Go 的并发模型天然适配

适用场景

• 微服务 AI 能力接入：在已有的 Go 微服务中增加 AI 功能
• AI API 网关：统一管理多个模型提供商，实现负载均衡和故障转移
• RAG 知识库服务：构建企业级知识问答系统
• AI Agent 平台：构建可扩展的 Agent 编排平台

不适用场景

如果你的项目主要是数据科学和模型训练，Python 生态（LangChain + PyTorch + Transformers）仍然是更好的选择。Eino 的定位是应用开发框架，不是模型训练框架。

展望

Eino 目前处于快速发展阶段（v0.9.2），CloudWeGo 团队持续迭代。随着 Go 在 AI 应用开发领域的采用率不断提升，Eino 有望成为 Go 生态中最重要的 AI 框架之一。

对于 Go 程序员来说，现在是学习 Eino 的最佳时机——框架已经足够成熟用于生产环境，同时社区还很小，你的贡献和反馈会有更大的影响力。

参考资源

• Eino GitHub 仓库：https://github.com/cloudwego/eino
• CloudWeGo 官网：https://www.cloudwego.io
• Eino 扩展组件：https://github.com/cloudwego/eino-ext
• Hertz HTTP 框架：https://github.com/cloudwego/hertz