274 lines
7.5 KiB
Markdown
274 lines
7.5 KiB
Markdown
|
---
|
||
|
|
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)
|