vault backup: 2026-04-29 18:36:58

2026-04-29 18:36:58 +08:00
parent bce0924def
commit 7bb4b3b498
96 changed files with 29367 additions and 0 deletions
@@ -0,0 +1,273 @@
+---
+Description: ""
+date: "2025-07-21"
+lastmod: ""
+tags: []
+title: Embedding 使用说明
+weight: 2
+---
+
+## **基本介绍**
+
+Embedding 组件是一个用于将文本转换为向量表示的组件。它的主要作用是将文本内容映射到向量空间，使得语义相似的文本在向量空间中的距离较近。这个组件在以下场景中发挥重要作用：
+
+- 文本相似度计算
+- 语义搜索
+- 文本聚类分析
+
+## **组件定义**
+
+### **接口定义**
+
+```go
+type Embedder interface {
+    EmbedStrings(ctx context.Context, texts []string, opts ...Option) ([][]float64, error)
+}
+```
+
+#### **EmbedStrings 方法**
+
+- 功能：将一组文本转换为向量表示
+- 参数：
+  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
+  - texts：待转换的文本列表
+  - opts：转换选项，用于配置转换行为
+- 返回值：
+  - `[][]float64`：文本对应的向量表示列表，每个向量的维度由具体的实现决定
+  - error：转换过程中的错误信息
+
+### **公共 Option**
+
+Embedding 组件使用 EmbeddingOption 来定义可选参数，下方是抽象出的公共 option。每个具体的实现可以定义自己的特定 Option，通过 WrapEmbeddingImplSpecificOptFn 函数包装成统一的 EmbeddingOption 类型。
+
+```go
+type Options struct {
+    // Model 是用于生成向量的模型名称
+    Model *string
+}
+```
+
+可以通过以下方式设置选项：
+
+```go
+// 设置模型名称
+WithModel(model string) Option
+```
+
+## **使用方式**
+
+### **单独使用**
+
+> 代码位置：eino-ext/components/embedding/openai/examples/embedding
+
+```go
+import "github.com/cloudwego/eino-ext/components/embedding/openai"
+
+embedder, _ := openai.NewEmbedder(ctx, &openai.EmbeddingConfig{
+    APIKey:     accessKey,
+    Model:      "text-embedding-3-large",
+    Dimensions: &defaultDim,
+    Timeout:    0,
+})
+
+vectorIDs, _ := embedder.EmbedStrings(ctx, []string{"hello", "how are you"})
+```
+
+### **在编排中使用**
+
+> 代码位置：eino-ext/components/embedding/openai/examples/embedding
+
+```go
+// 在 Chain 中使用
+chain := compose.NewChain[[]string, [][]float64]()
+chain.AppendEmbedding(embedder)
+
+// 在 Graph 中使用
+graph := compose.NewGraph[[]string, [][]float64]()
+graph.AddEmbeddingNode("embedding_node", embedder)
+```
+
+## **Option 和 Callback 使用**
+
+### **Option 使用示例**
+
+```go
+// 使用选项 (以独立使用组件为例)
+vectors, err := embedder.EmbedStrings(ctx, texts,
+    embedding.WithModel("text-embedding-3-small"),
+)
+```
+
+### **Callback 使用示例**
+
+> 代码位置：eino-ext/components/embedding/openai/examples/embedding
+
+```go
+import (
+    "github.com/cloudwego/eino/callbacks"
+    "github.com/cloudwego/eino/components/embedding"
+    "github.com/cloudwego/eino/compose"
+    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
+    "github.com/cloudwego/eino-ext/components/embedding/openai"
+)
+
+handler := &callbacksHelper.EmbeddingCallbackHandler{
+    OnStart: func(ctx context.Context, runInfo *callbacks.RunInfo, input *embedding.CallbackInput) context.Context {
+       log.Printf("input access, len: %v, content: %s\n", len(input.Texts), input.Texts)
+       return ctx
+    },
+    OnEnd: func(ctx context.Context, runInfo *callbacks.RunInfo, output *embedding.CallbackOutput) context.Context {
+       log.Printf("output finished, len: %v\n", len(output.Embeddings))
+       return ctx
+    },
+}
+
+callbackHandler := callbacksHelper.NewHandlerHelper().Embedding(handler).Handler()
+
+chain := compose.NewChain[[]string, [][]float64]()
+chain.AppendEmbedding(embedder)
+
+// 编译并运行
+runnable, _ := chain.Compile(ctx)
+vectors, _ = runnable.Invoke(ctx, []string{"hello", "how are you"},
+    compose.WithCallbacks(callbackHandler))
+
+log.Printf("vectors in chain: %v", vectors)
+```
+
+## **已有实现**
+
+1. OpenAI Embedding: 使用 OpenAI 的文本嵌入模型生成向量 [Embedding - OpenAI](/zh/docs/eino/ecosystem_integration/embedding/embedding_openai)
+2. ARK Embedding: 使用 ARK 平台的模型生成向量 [Embedding - ARK](/zh/docs/eino/ecosystem_integration/embedding/embedding_ark)
+
+## **自行实现参考**
+
+实现自定义的 Embedding 组件时，需要注意以下几点：
+
+1. 注意处理公共 option
+2. 注意实现 callback 机制
+
+### **Option 机制**
+
+自定义 Embedding 需要实现自己的 Option 机制：
+
+```go
+// 定义 Option 结构体
+type MyEmbeddingOptions struct {
+    BatchSize int
+    MaxRetries int
+    Timeout time.Duration
+}
+
+// 定义 Option 函数
+func WithBatchSize(size int) embedding.Option {
+    return embedding.WrapEmbeddingImplSpecificOptFn(func(o *MyEmbeddingOptions) {
+        o.BatchSize = size
+    })
+}
+```
+
+### **Callback 处理**
+
+Embedder 实现需要在适当的时机触发回调。框架已经定义了标准的回调输入输出结构体：
+
+```go
+// CallbackInput 是 embedding 回调的输入
+type CallbackInput struct {
+    // Texts 是待转换的文本列表
+    Texts []string
+    // Config 是生成向量的配置信息
+    Config *Config
+    // Extra 是回调的额外信息
+    Extra map[string]any
+}
+
+// CallbackOutput 是 embedding 回调的输出
+type CallbackOutput struct {
+    // Embeddings 是生成的向量列表
+    Embeddings [][]float64
+    // Config 是生成向量的配置信息
+    Config *Config
+    // TokenUsage 是 token 使用情况
+    TokenUsage *TokenUsage
+    // Extra 是回调的额外信息
+    Extra map[string]any
+}
+
+// TokenUsage 是 token 使用情况
+type TokenUsage struct {
+    // PromptTokens 是提示词的 token 数量
+    PromptTokens int
+    // CompletionTokens 是补全的 token 数量
+    CompletionTokens int
+    // TotalTokens 是总的 token 数量
+    TotalTokens int
+}
+```
+
+### **完整实现示例**
+
+```go
+type MyEmbedder struct {
+    model string
+    batchSize int
+}
+
+func NewMyEmbedder(config *MyEmbedderConfig) (*MyEmbedder, error) {
+    return &MyEmbedder{
+        model: config.DefaultModel,
+        batchSize: config.DefaultBatchSize,
+    }, nil
+}
+
+func (e *MyEmbedder) EmbedStrings(ctx context.Context, texts []string, opts ...embedding.Option) ([][]float64, error) {
+    // 1. 处理选项
+    options := &MyEmbeddingOptions{
+        Options: &embedding.Options{},
+        BatchSize: e.batchSize,
+    }
+    options.Options = embedding.GetCommonOptions(options.Options, opts...)
+    options = embedding.GetImplSpecificOptions(options.Options, opts...)
+    
+    // 2. 获取 callback manager
+    cm := callbacks.ManagerFromContext(ctx)
+    
+    // 3. 开始生成前的回调
+    ctx = cm.OnStart(ctx, info, &embedding.CallbackInput{
+        Texts: texts,
+        Config: &embedding.Config{
+            Model: e.model,
+        },
+    })
+    
+    // 4. 执行向量生成逻辑
+    vectors, tokenUsage, err := e.doEmbed(ctx, texts, options)
+    
+    // 5. 处理错误和完成回调
+    if err != nil {
+        ctx = cm.OnError(ctx, info, err)
+        return nil, err
+    }
+    
+    ctx = cm.OnEnd(ctx, info, &embedding.CallbackOutput{
+        Embeddings: vectors,
+        Config: &embedding.Config{
+            Model: e.model,
+        },
+        TokenUsage: tokenUsage,
+    })
+    
+    return vectors, nil
+}
+
+func (e *MyEmbedder) doEmbed(ctx context.Context, texts []string, opts *MyEmbeddingOptions) ([][]float64, *TokenUsage, error) {
+    // 实现逻辑
+    return vectors, tokenUsage, nil
+}
+```
+
+## 其他参考文档
+
+- [Eino: Document Loader 使用说明](/zh/docs/eino/core_modules/components/document_loader_guide)
+- [Eino: Indexer 使用说明](/zh/docs/eino/core_modules/components/indexer_guide)
+- [Eino: Retriever 使用说明](/zh/docs/eino/core_modules/components/retriever_guide)