跳转至

SAGE Embedding 系统 🎯

Date: 2024-09-27\ Author: SAGE Team\ Summary: Embedding 迁移说明

版本: 2.0.0\ 状态: ✅ Production Ready\ 更新: 2024-10-06

统一、灵活、高性能的文本向量化解决方案

📚 文档导航

🌟 简介

SAGE Embedding 系统提供了统一、灵活、高性能的文本向量化解决方案，支持 11 种不同的 embedding 方法，从本地快速哈希到云端高质量语义模型，满足各种应用场景需求。

核心特性

  • ✅ 11 种 embedding 方法 - 本地和云端全覆盖
  • ✅ 统一接口 - 一次学习，处处使用
  • ✅ CLI 工具 - 5 个实用命令
  • ✅ 批量优化 - 10-1000倍性能提升
  • ✅ 完整集成 - Pipeline Builder 内置支持
  • ✅ 完善测试 - 27 个单元测试

🚀 快速开始

安装

# SAGE 已内置 embedding 系统，无需额外安装
cd /path/to/SAGE

30 秒上手

from sage.common.components.sage_embedding import EmbeddingFactory

# 创建 embedder
embedder = EmbeddingFactory.create("hash", dimension=384)

# 生成向量
vector = embedder.embed("Hello, SAGE!")
print(f"向量维度: {len(vector)}")  # 384

# 批量处理
texts = ["文本1", "文本2", "文本3"]
vectors = embedder.embed_batch(texts)
print(f"生成了 {len(vectors)} 个向量")

CLI 快速体验

# 1. 查看所有方法
sage embedding list

# 2. 测试一个方法
sage embedding test hash --text "Hello, SAGE!"

# 3. 对比性能
sage embedding benchmark hash mockembedder

# 4. Pipeline Builder 中使用
sage pipeline build \
  --embedding-method hash \
  --name "我的 Pipeline"

📚 支持的方法

本地方法（免费、离线）

方法 速度 质量 用途
hash ⚡⚡⚡⚡⚡ ⭐⭐ 快速原型、测试
mockembedder ⚡⚡⚡⚡⚡ ⭐ 基准测试
hf ⚡⚡-⚡⚡⚡ ⭐⭐⭐⭐⭐ 生产环境、离线部署
ollama ⚡⚡⚡ ⭐⭐⭐⭐ 本地 LLM 集成

云端 API（高质量、需要 Key）

方法 速度 质量 优势
openai ⚡⚡ ⭐⭐⭐⭐⭐ 最佳质量、多语言
zhipu ⚡⚡ ⭐⭐⭐⭐ 中文优化、性价比高
cohere ⚡⚡⚡ ⭐⭐⭐⭐ 多语言、英文优化
jina ⚡⚡⚡ ⭐⭐⭐⭐ 多语言、大上下文
bedrock ⚡⚡ ⭐⭐⭐⭐ AWS 集成
siliconcloud ⚡⚡ ⭐⭐⭐ 国内服务
nvidia_openai ⚡⚡ ⭐⭐⭐⭐ NVIDIA 优化

📖 使用文档

核心文档

  1. 快速参考 ⭐ 推荐新手

  2. 一页纸速查表

  3. 常用命令和代码

  4. 常见问题解答

  5. 完整总结

  6. 系统架构

  7. 所有功能详解

  8. 性能对比

  9. Pipeline Builder 集成

  10. 知识库检索增强

  11. CLI 使用指南
  12. 最佳实践

阶段文档

示例代码

  • examples/tutorials/embedding_demo.py - 基础示例
  • examples/tutorials/pipeline_builder_embedding_demo.py - Pipeline Builder 集成

🎯 使用场景

场景 1: 快速原型开发

# 使用 hash 方法（最快）
sage pipeline build \
  --name "快速测试" \
  --embedding-method hash

何时使用: 本地开发、CI/CD、结构验证

场景 2: 高质量离线部署

# 使用 HuggingFace 本地模型
sage pipeline build \
  --name "生产环境" \
  --embedding-method hf \
  --embedding-model BAAI/bge-base-zh-v1.5

何时使用: 企业内网、数据隐私、离线环境

场景 3: 云端最优质量

# 使用 OpenAI API
export OPENAI_API_KEY=sk-xxx
sage pipeline build \
  --name "高端服务" \
  --embedding-method openai \
  --embedding-model text-embedding-3-small

何时使用: 对质量要求极高、云端部署

场景 4: 成本优化

# 使用国内服务（如智谱）
export ZHIPU_API_KEY=xxx
sage pipeline build \
  --name "中文服务" \
  --embedding-method zhipu \
  --embedding-model embedding-2

何时使用: 中文为主、成本敏感、国内网络

🛠️ API 参考

Python API

创建 Embedder

from sage.common.components.sage_embedding import EmbeddingFactory

# 基本创建
embedder = EmbeddingFactory.create("hash", dimension=384)

# 带参数创建
embedder = EmbeddingFactory.create(
    "openai",
    model="text-embedding-3-small",
    api_key="sk-xxx",
    base_url="https://api.openai.com/v1"
)

生成向量

# 单个文本
vector = embedder.embed("Hello, world!")

# 批量处理
texts = ["文本1", "文本2", "文本3"]
vectors = embedder.embed_batch(texts)

# 获取元数据
dim = embedder.get_dimension()
metadata = embedder.get_metadata()

查看可用方法

from sage.common.components.sage_embedding.registry import EmbeddingRegistry

# 列出所有方法
methods = EmbeddingRegistry.list_methods()
print(methods)  # ['hash', 'mockembedder', 'hf', ...]

# 获取方法元数据
metadata = EmbeddingRegistry.get_metadata("openai")
print(metadata)

CLI 命令

embedding 命令

# 列出方法
sage embedding list [--format table|json|simple]

# 检查可用性
sage embedding check <method> [--verbose]

# 测试方法
sage embedding test <method> \
  [--text "..."] \
  [--show-vector] \
  [--dimension N]

# 性能对比
sage embedding benchmark <method1> <method2> ... \
  [--text "..."] \
  [--count N]

pipeline 命令

# 构建 pipeline
sage pipeline build \
  [--embedding-method METHOD] \
  [--embedding-model MODEL]

# 分析最佳方法
sage pipeline analyze-embedding <query> \
  [--method M1 --method M2 ...] \
  [--top-k K] \
  [--show-vectors]

🧪 测试

运行测试

cd /path/to/SAGE

# 运行所有 embedding 测试
pytest packages/sage-middleware/tests/embedding/ -v

# 运行特定测试
pytest packages/sage-middleware/tests/embedding/test_factory.py -v

# 覆盖率报告
pytest packages/sage-middleware/tests/embedding/ --cov

测试覆盖

  • ✅ 27 个单元测试
  • ✅ 100% 核心代码覆盖
  • ✅ 所有方法验证
  • ✅ 异常情况处理

📊 性能基准

方法对比（500 chunks，查询："如何构建 RAG pipeline"）

方法 耗时 平均得分 维度 内存占用
hash 14 ms 0.5425 384 ~750 KB
mockembedder 6 ms 0.3214 128 ~250 KB
hf (small) 89 ms 0.7234 512 ~1.0 MB
hf (base) 156 ms 0.7891 768 ~1.5 MB
openai 234 ms* 0.8523 1536 ~3.0 MB
zhipu 187 ms* 0.7965 1024 ~2.0 MB

* 包含网络延迟

批量处理性能

文本数量 优化前 优化后 加速比
10 1000 ms 100 ms 10倍
100 10000 ms 100 ms 100倍
1000 100000 ms 100 ms 1000倍

🔧 配置

环境变量

# Pipeline Builder 默认设置
export SAGE_PIPELINE_EMBEDDING_METHOD=openai
export SAGE_PIPELINE_EMBEDDING_MODEL=text-embedding-3-small

# API Keys
export OPENAI_API_KEY=sk-xxx
export ZHIPU_API_KEY=xxx
export COHERE_API_KEY=xxx
export JINA_API_KEY=jina_xxx
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx

# HuggingFace 设置
export HF_HOME=/path/to/cache
export HF_ENDPOINT=https://hf-mirror.com  # 国内镜像

代码配置

# 全局配置（不推荐）
import os
os.environ["OPENAI_API_KEY"] = "sk-xxx"

# 实例配置（推荐）
embedder = EmbeddingFactory.create(
    "openai",
    api_key="sk-xxx",  # 直接传参
    base_url="https://api.openai.com/v1"
)

🤝 贡献

欢迎贡献新的 embedding 方法！

添加新方法

  1. 创建 wrapper 类（继承 BaseEmbedding）
  2. 实现必需方法（embed, embed_batch）
  3. 注册到 registry
  4. 添加单元测试
  5. 更新文档

参考 packages/sage-middleware/src/sage/middleware/utils/embedding/wrappers/ 中的现有实现。

📝 许可证

参考项目根目录的 LICENSE 文件。

🔗 相关链接

  • SAGE 主页: https://github.com/intellistream/SAGE
  • 文档: docs/
  • 问题反馈: GitHub Issues

📞 支持

遇到问题？

  1. 查看 快速参考
  2. 阅读 完整文档
  3. 运行示例代码
  4. 提交 GitHub Issue

SAGE Embedding System v2.0 | 让向量化变得简单 | 2024-10-06