Eino 组件实战：Embedding 原理与落地用法

关键参数说明：

• APIKey：调用模型的密钥。
• Model：选择具体的 Embedding 模型。
• Dimensions：向量维度。
• Timeout：超时时间。

调用 EmbedStrings

创建好对象后，直接调用即可：

texts := []string{"hello", "how are you"}
vectors, err := embedder.EmbedStrings(ctx, texts)
if err != nil {
    panic(err)
}

这里要注意，texts[0] 对应 vectors[0]，保持一一对应关系。

完整示例

下面是一个标准的 Go 入口文件写法，涵盖了初始化和调用的完整流程：

package main

import (
    "context"
    "fmt"
    "log"
    "github.com/cloudwego/eino-ext/components/embedding/openai"
)

func main() {
    ctx := context.Background()
    defaultDim := 3072
    accessKey := "your-api-key"

    embedder, err := openai.NewEmbedder(ctx, &openai.EmbeddingConfig{
        APIKey:     accessKey,
        Model:      "text-embedding-3-large",
        Dimensions: &defaultDim,
        Timeout:    0,
    })
    if err != nil {
        log.Fatal(err)
    }

    texts := []string{"退款怎么申请", "如何进行退钱操作", "今天天气不错"}
    vectors, err := embedder.EmbedStrings(ctx, texts)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("文本数量:", len(vectors))
    fmt.Println("第一条文本向量维度:", len(vectors[0]))
}

进阶配置

1. 使用 Option 覆盖参数

公共 Option 很有用，比如 WithModel。你可以在调用时临时覆盖初始化时的模型参数。

vectors, err := embedder.EmbedStrings(ctx, texts, embedding.WithModel("text-embedding-3-small"))

适合平时默认用大模型，特定场景为了省钱或提速改用小模型的情况。不过要注意，虽然不同模型的向量有一定兼容性，但频繁切换可能会影响效果，建议尽量保持一致。

2. 在编排中使用

如果你在使用 Eino 的 Chain 或 Graph，可以直接把 Embedding 当成节点塞进去。

在 Chain 中：

chain := compose.NewChain[[]string, [][]float64]()
chain.AppendEmbedding(embedder)

这意味着整条链专门做'文本 -> 向量'的转换。

在 Graph 中：

graph := compose.NewGraph[[]string, [][]float64]()
graph.AddEmbeddingNode("embedding_node", embedder)

将 Embedding 作为图中的一个节点，后面可以接其他节点继续处理。

3. 使用 Callback 监控

Callback 类似于生命周期钩子，用于记录日志、统计 Token 或调试输入输出。

handler := &callbacksHelper.EmbeddingCallbackHandler{
    OnStart: func(ctx context.Context, runInfo *callbacks.RunInfo, input *embedding.CallbackInput) context.Context {
        log.Printf("开始 embedding，文本数：%d, 内容：%v\n", len(input.Texts), input.Texts)
        return ctx
    },
    OnEnd: func(ctx context.Context, runInfo *callbacks.RunInfo, output *embedding.CallbackOutput) context.Context {
        log.Printf("embedding 完成，生成向量数：%d\n", len(output.Embeddings))
        return ctx
    },
}

运行时通过 compose.WithCallbacks 传入：

callbackHandler := callbacksHelper.NewHandlerHelper().Embedding(handler).Handler()
runnable, _ := chain.Compile(ctx)
vectors, err := runnable.Invoke(ctx, []string{"hello", "how are you"}, compose.WithCallbacks(callbackHandler))

这样你就能清楚看到输入了什么、何时开始结束、输出了多少向量以及 Token 消耗情况。

典型场景：RAG 知识库问答

真实业务中，Embedding 很少单独使用，通常是 RAG 链路的一环。我们以知识库问答为例，梳理一下整体流程。

第一步：把知识库切块 将长文档切成合适的段落（Chunk）。

chunks := []string{
    "退款申请需要在订单完成后 7 天内提交",
    "修改收货地址请在发货前联系人工客服",
    "发票可在订单详情页申请",
}

第二步：给每个 chunk 生成向量

chunkVectors, err := embedder.EmbedStrings(ctx, chunks)

第三步：存起来 通常会存到向量数据库，同时保存原文、来源和 Chunk ID。

第四步：用户提问时，也生成向量

query := []string{"订单下完以后地址还能改吗"}
queryVector, err := embedder.EmbedStrings(ctx, query)

第五步：检索最相近的 chunk 拿 query 的向量去向量库里找最相似的几段知识。

第六步：交给大模型回答 把召回结果喂给 LLM，生成最终回复。至此，完整的 RAG 闭环才形成。

模板总结

为了方便大家上手，这里整理了一个最小步骤和常见增强项的模板。

最小步骤：

1. 初始化 Embedder
2. 调用 EmbedStrings
3. 拿到 [][]float64 向量

常见增强： 4. 用 Option 临时覆盖参数 5. 用 Callback 打日志和监控 6. 放进 Chain / Graph 编排

参考代码模板：

package main

import (
    "context"
    "fmt"
    "log"
    "github.com/cloudwego/eino/components/embedding"
    embeddingOpenAI "github.com/cloudwego/eino-ext/components/embedding/openai"
)

func main() {
    ctx := context.Background()
    defaultDim := 3072
    accessKey := "your-api-key"

    embedder, err := embeddingOpenAI.NewEmbedder(ctx, &embeddingOpenAI.EmbeddingConfig{
        APIKey:     accessKey,
        Model:      "text-embedding-3-large",
        Dimensions: &defaultDim,
        Timeout:    0,
    })
    if err != nil {
        log.Fatal(err)
    }

    texts := []string{"退款怎么申请", "如何退钱", "修改收货地址的方法"}
    vectors, err := embedder.EmbedStrings(
        ctx, texts,
        embedding.WithModel("text-embedding-3-small"),
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("生成了 %d 个向量\n", len(vectors))
    fmt.Printf("每个向量维度：%d\n", len(vectors[0]))
}

结语

希望大家记住：Embedding 的'用法'就是先把文本喂进去生成向量，再把这个向量用于检索、匹配、聚类等后续处理。

会调用 Embedding 很简单，但会用 Embedding 做业务才是关键。前者是 NewEmbedder + EmbedStrings，后者则是从切块、存储、检索到大模型回答的完整链路。掌握这两者的区别，才算真正入门了大模型应用开发。

参考资料

1. OpenAI 开发者 - 向量嵌入
2. CloudWeGo 官方文档 - Embedding 使用说明