1
┌─────────────────────────────────────────┐
2
│         ADK / Flow / Compose            │  ← 上层编排
3
├─────────────────────────────────────────┤
4
│  ChatModel │ Retriever │ Parser │ ...   │  ← 组件接口
5
├─────────────────────────────────────────┤
6
│  OpenAI │ ARK │ VikingDB │ PDF │ HTML   │  ← 具体实现
7
└─────────────────────────────────────────┘

1
组件层三大类：
2
  Model:    A/B 路由（ABRouter）/ HTTP 日志（CurlRT）
3
  Retriever: Multi-Query（改写查询）/ Router（多数据源路由）
4
  Parser:   TextParser → ExtParser → CustomParser（按扩展名分发）
5

6
核心模式：全都实现统一接口 → 可在任何编排中自由插拔

1
100% 用户请求
2
  ├─ 90% → GPT-4o（主力，稳定）
3
  └─ 10% → DeepSeek（实验，观察）

1
import "github.com/cloudwego/eino-examples/components/model/abtest"
2

3
// 准备两个候选模型
4
gpt4o, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{...})
5
deepseek, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
6
    BaseURL: "https://api.deepseek.com/v1",  // 指向 DeepSeek
7
    Model:   "deepseek-chat",
8
})
9

10
// 路由器：根据 userID 最后一位做 A/B 分流
11
router := abtest.NewABRouterChatModel(func(
12
    ctx context.Context, in []*schema.Message, _ ...model.Option,
13
) (string, model.BaseChatModel, error) {
14
    // 从 context 中提取 userID（实际项目中从请求上下文拿）
15
    userID, _ := ctx.Value("userID").(string)
16
    if userID != "" && userID[len(userID)-1] < '5' {  // 50% 流量
17
        return "deepseek", deepseek, nil  // 实验组
18
    }
19
    return "gpt4o", gpt4o, nil            // 对照组
20
})
21

22
// 使用方式和普通 ChatModel 完全一样！
23
msg, _ := router.Generate(ctx, messages)

1
client := &http.Client{
2
    Transport: httptransport.NewCurlRT(
3
        http.DefaultTransport,          // 基础 Transport（真正发请求的）
4
        httptransport.WithLogger(log.Default()),
5
        httptransport.WithPrintAuth(false),              // ⚠️ API Key 脱敏（默认不打印）
6
        httptransport.WithMaskHeaders([]string{"X-API-KEY"}),
7
        httptransport.WithStreamLogging(true),            // 流式响应也记录
8
        httptransport.WithMaxStreamLogBytes(8192),
9
    ),
10
}
11

12
// 注入到 ChatModel — 之后调用时自动打印日志
13
chatModel, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
14
    HTTPClient: client,
15
})

1
[curl request] curl -X POST 'https://api.openai.com/v1/chat/completions' \
2
  -H 'Content-Type: application/json' \
3
  -H 'Authorization: <redacted>' \
4
  --data '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

1
[curl response] HTTP/1.1 200
2
{"id":"chatcmpl-xxx","choices":[{"message":{"role":"assistant","content":"Hello! How can I help?"}}]}

1
用户输入: "怎么提高代码质量"
2
向量库里相关文档的标题实际是:
3
  "单元测试最佳实践"
4
  "Code Review 流程规范"
5
  "静态分析工具配置指南"

1
用户输入: "tourist attraction"（太模糊）
2
    ↓ LLM 自动改写
3
变体1: "best tourist attractions for families"     ← 从"亲子"角度
4
变体2: "outdoor sightseeing spots recommendations"  ← 从"户外"角度
5
变体3: "popular travel destinations and landmarks"  ← 从"知名景点"角度
6
    ↓ 分别检索同一向量库
7
结果1: [doc_a, doc_b]
8
结果2: [doc_b, doc_d]     →  FusionFunc 合并去重 → [doc_a, doc_b, doc_c, doc_d, doc_e, doc_f]
9
结果3: [doc_c, doc_e, doc_f]

1
import "github.com/cloudwego/eino/flow/retriever/multiquery"
2

3
mqr, _ := multiquery.NewRetriever(ctx, &multiquery.Config{
4
    RewriteHandler: func(ctx context.Context, query string) ([]string, error) {
5
        out, _ := llm.Generate(ctx, []*schema.Message{
6
            schema.SystemMessage("Generate 3 rewritten search queries, one per line."),
7
            schema.UserMessage(query),
8
        })
9
        return strings.Split(out.Content, "\n"), nil
10
    },
11
    MaxQueriesNum: 3,        // 最多生成 3 个变体
12
    OrigRetriever: vk,        // 底层向量检索引擎
13
})
14

15
docs, _ := mqr.Retrieve(ctx, "tourist attraction")
16
// docs 包含所有变体的合并结果

1
你的系统有三个向量库:
2
  product_vdb  → 存商品信息（名称、价格、规格）
3
  review_vdb   → 存用户评价（打分、评论文本）
4
  faq_vdb      → 存常见问题（Q&A 对）
5

6
用户问"这个商品多少钱？" → 搜 product_vdb
7
用户问"这个商品好用吗？" → 搜 review_vdb
8
用户问"怎么退货？"      → 搜 faq_vdb

1
rr, _ := router.NewRetriever(ctx, &router.Config{
2
    Retrievers: map[string]retriever.Retriever{
3
        "product":  productRetriever,   // 商品向量库
4
        "review":   reviewRetriever,    // 评价向量库
5
        "faq":      faqRetriever,       // FAQ 向量库
6
    },
7
    Router: func(ctx context.Context, query string) ([]string, error) {
8
        var targets []string
9
        // 按关键词路由到不同引擎
10
        if strings.Contains(query, "价格") || strings.Contains(query, "规格") {
11
            targets = append(targets, "product")
12
        }
13
        if strings.Contains(query, "评价") || strings.Contains(query, "好用") {
14
            targets = append(targets, "review")
15
        }
16
        if strings.Contains(query, "退货") || strings.Contains(query, "怎么") {
17
            targets = append(targets, "faq")
18
        }
19
        if len(targets) == 0 {
20
            targets = []string{"product", "review", "faq"}  // 兜底：全搜
21
        }
22
        return targets, nil
23
    },
24
    FusionFunc: nil,  // nil = 默认 RRF（Reciprocal Rank Fusion）融合
25
})

1
import "github.com/cloudwego/eino/components/document/parser"
2

3
textParser := parser.TextParser{}
4
docs, _ := textParser.Parse(ctx, strings.NewReader("hello world"))

1
extParser, _ := parser.NewExtParser(ctx, &parser.ExtParserConfig{
2
    Parsers: map[string]parser.Parser{
3
        ".html": htmlParser,     // → 用 CSS Selector 提取 body 内容
4
        ".pdf":  pdfParser,      // → 用 PDF 解析引擎提取文本
5
    },
6
    FallbackParser: textParser,  // 未知格式 → 当纯文本读
7
})
8

9
file, _ := os.Open("./testdata/test.html")
10
docs, _ := extParser.Parse(ctx, file, parser.WithURI(filePath))
11
// ↑ WithURI 必须传——ExtParser 靠文件路径后缀判断格式

1
// A/B 测试路由
2
"github.com/cloudwego/eino-examples/components/model/abtest"
3

4
// HTTP 传输日志
5
"github.com/cloudwego/eino-examples/components/model/httptransport"
6

7
// 检索器增强
8
"github.com/cloudwego/eino/flow/retriever/multiquery"   // Multi-Query
9
"github.com/cloudwego/eino/flow/retriever/router"        // Router
10

11
// 文档解析器
12
"github.com/cloudwego/eino/components/document/parser"         // Parser 接口, TextParser, ExtParser
13
"github.com/cloudwego/eino-ext/components/document/parser/html" // HTML
14
"github.com/cloudwego/eino-ext/components/document/parser/pdf"  // PDF

1
┌──────────────────────────────────────────────────┐
2
│  ADK 层（入门笔记 §1~§7）                           │
3
│  ChatModelAgent, Runner, Middleware, Interrupt   │
4
├──────────────────────────────────────────────────┤
5
│  Flow 层（附录一：Flow 流程模块）                    │
6
│  react.NewAgent, host.NewMultiAgent              │
7
├──────────────────────────────────────────────────┤
8
│  Compose 层（入门笔记 §6.4）                        │
9
│  Graph, Chain, Workflow, Branch, ProcessState    │
10
├──────────────────────────────────────────────────┤
11
│  组件层（本附录）                                   │
12
│  ChatModel, Retriever, Parser, Tool              │
13
└──────────────────────────────────────────────────┘

1
Model:
2
  ABRouter = 流量分配器（A/B测试 / 成本优化 / 灰度发布）
3
  CurlRT   = HTTP 调试器（cURL风格日志 + API Key 自动脱敏）
4

5
Retriever:
6
  MultiQuery = 用 LLM 改写查询 → 多角度搜同一个库 → 合并去重
7
  Router     = 分析查询内容 → 分派到不同库 → 结果融合
8

9
Parser:
10
  TextParser → ExtParser(按扩展名映射) → CustomParser(WrapImplSpecificOptFn)