mcpField
E
embedding-optimization

embedding-optimization

github.com/ancoleman数据与数据库52576 次安装46 周前更新
代码仓库

关于 embedding-optimization

用于优化 RAG 和语义搜索系统中的嵌入流程，涵盖模型选择、分块、缓存、批处理和性能监控，以平衡成本、速度与检索质量。

主要功能

  1. 01嵌入模型选择
  2. 02按内容类型制定分块策略
  3. 03内容寻址缓存
  4. 04批处理优化
  5. 05延迟与成本监控

适用场景

  1. 01优化 RAG 数据摄取流程
  2. 02为搜索处理大型文档集
  3. 03减少重复的嵌入 API 调用
  4. 04比较本地与 API 嵌入模型

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ancoleman/ai-design-components --skill embedding-optimization

安装后在 Claude Code 中输入/embedding-optimization确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

outputs.yaml
examples/
batch_processor.py
benchmark_embeddings.py
local_embedder.py
openai_cached.py
performance_monitor.py
smart_chunker.py
references/
chunking-strategies.md
model-selection-guide.md
performance-monitoring.md

详细介绍

嵌入优化

为 RAG 和语义搜索系统优化嵌入生成的成本、性能和质量。

何时使用此技能

在以下情况下触发此技能：

  • 构建 RAG（检索增强生成）系统
  • 实现语义搜索或相似度检测
  • 优化嵌入 API 成本（降低 70-90%）
  • 通过改进分块提升文档检索质量
  • 处理大型文档语料库（数千至数百万份文档）
  • 在基于 API 的嵌入模型和本地嵌入模型之间进行选择

模型选择框架

根据需求选择最佳嵌入模型：

快速建议：

  • 初创项目/MVP： all-MiniLM-L6-v2（本地，384 维，无 API 成本）
  • 生产环境： text-embedding-3-small（API，1,536 维，质量与成本均衡）
  • 高质量： text-embedding-3-large（API，3,072 维，优质）
  • 多语言： multilingual-e5-base（本地，768 维）或 Cohere embed-multilingual-v3.0

有关详细的决策框架，包括成本比较、质量基准和数据隐私考量，请参阅 references/model-selection-guide.md。

模型比较摘要：

模型类型维度每 100 万个 token 的成本最适用于
all-MiniLM-L6-v2本地384$0（仅计算成本）高用量、预算紧张
BGE-base-en-v1.5本地768$0（仅计算成本）兼顾质量与成本
text-embedding-3-smallAPI1,536$0.02通用生产环境
text-embedding-3-largeAPI3,072$0.13对质量有较高要求
embed-multilingual-v3.0API1,024$0.10支持 100 多种语言

分块策略

根据内容类型和使用场景选择分块策略：

内容类型 → 策略映射：

  • 文档： 递归式（识别标题），800 个字符，重叠 100 个字符
  • 代码： 递归式（按函数分块），1,000 个字符，重叠 100 个字符
  • 问答/常见问题： 固定大小，500 个字符，重叠 50 个字符（精确检索）
  • 法律/技术内容： 语义式（大块），1,500 个字符，重叠 200 个字符（保留上下文）
  • 博客文章： 语义式（按段落），1,000 个字符，重叠 100 个字符
  • 学术论文： 递归式（识别章节），1,200 个字符，重叠 150 个字符

有关详细的分块模式、决策树和实施指南，请参阅 references/chunking-strategies.md。

使用 CLI 快速开始：

python scripts/chunk_document.py \
  --input document.txt \
  --content-type markdown \
  --chunk-size 800 \
  --overlap 100 \
  --output chunks.jsonl

缓存实现

通过基于内容寻址的缓存，将成本降低 80-90%。

按查询量划分的缓存架构：

  • 每月 <10K 次查询： 内存缓存（Python lru_cache）
  • 每月 10K-100K 次查询： Redis（速度快，基于 TTL 过期）
  • 每月 100K-1M 次查询： Redis（热数据）+ PostgreSQL（温数据）
  • 每月 >1M 次查询： 多级缓存（Redis + PostgreSQL + S3）

使用 Redis 实现生产级缓存：

# Embed documents with caching enabled
python scripts/cached_embedder.py \
  --model text-embedding-3-small \
  --input documents.jsonl \
  --output embeddings.npy \
  --cache-backend redis \
  --cache-ttl 2592000  # 30 days

缓存 ROI 示例：

  • 50,000 个文档块
  • 20% 的内容重复
  • 不使用缓存：API 成本 $0.50
  • 使用缓存（命中率 60%）：API 成本 $0.20
  • 节省：60%（$0.30）

维度权衡

平衡存储、搜索速度和质量：

维度存储空间（100 万个向量）搜索速度（p95）质量使用场景
3841.5 GB10ms良好大规模搜索
7683 GB15ms高通用 RAG
1,5366 GB25ms很高高质量检索
3,07212 GB40ms最高高端应用

关键见解： 对于大多数 RAG 应用，768 维（本地 BGE-base-en-v1.5 或同类模型）在质量、成本和速度之间实现了最佳平衡。

批处理优化

最大限度提升大规模数据摄取的吞吐量：

OpenAI API：

  • 每个请求最多批量处理 2,048 个输入
  • 实施速率限制（取决于套餐等级：500-5,000 RPM）
  • 使用并行请求，并在触发速率限制时进行退避

本地模型（sentence-transformers）：

  • GPU 加速（CUDA、Apple Silicon 的 MPS）
  • 调整批次大小（根据 GPU 内存设置为 32-128）
  • 支持多 GPU，以实现最大吞吐量

预期吞吐量：

  • OpenAI API：每分钟 1,000-5,000 条文本（取决于速率限制）
  • 本地 GPU（RTX 3090）：每分钟 5,000-10,000 条文本
  • 本地 CPU：每分钟 100-500 条文本

性能监控

跟踪关键指标以进行优化：

关键指标：

  • 延迟： 嵌入生成时间（p50、p95、p99）
  • 吞吐量： 每秒/分钟生成的嵌入数量
  • 成本： API 使用情况跟踪（每 1K/1M 个令牌的美元费用）
  • 缓存效率： 命中率百分比

有关详细的监控设置、指标收集模式和仪表板配置，请参阅 references/performance-monitoring.md。

使用封装器进行监控：

from scripts.performance_monitor import MonitoredEmbedder

monitored = MonitoredEmbedder(
    embedder=your_embedder,
    cost_per_1k_tokens=0.00002  # OpenAI pricing
)

embeddings = monitored.embed_batch(texts)
metrics = monitored.get_metrics()
print(f"Cache hit rate: {metrics['cache_hit_rate_pct']}%")
print(f"Total cost: ${metrics['total_cost_usd']}")

可运行示例

完整实现请参阅 examples/ 目录：

Python 示例：

  • examples/openai_cached.py - 使用 Redis 缓存的 OpenAI 嵌入
  • examples/local_embedder.py - 使用 sentence-transformers 进行本地嵌入
  • examples/smart_chunker.py - 具备内容感知能力的递归分块
  • examples/performance_monitor.py - 跟踪流水线性能
  • examples/batch_processor.py - 大规模文档处理

所有示例均包含：

  • 完整且可运行的代码
  • 依赖项安装说明
  • 错误处理和重试逻辑
  • 配置选项

集成点

上游（本技能提供给）：

  • 向量数据库： 嵌入数据流向 Pinecone、Weaviate、Qdrant、pgvector
  • RAG 系统： 为检索流水线优化的嵌入
  • 语义搜索： 用于相似度搜索的查询和文档嵌入

下游（本技能使用）：

  • 文档处理： 在生成嵌入前对文档进行分块
  • 数据摄取： 处理来自各种来源的文档

相关技能：

  • 有关 RAG 架构，请参阅 building-ai-chat 技能
  • 有关向量数据库操作，请参阅 databases-vector 技能
  • 有关数据摄取流水线，请参阅 ingesting-data 技能

常见模式

模式 1：RAG 流水线

Document → Chunk → Embed → Store (vector DB) → Retrieve

模式 2：语义搜索

Query → Embed → Search (vector DB) → Rank → Display

模式 3：多阶段检索（成本优化）

Query → Cheap Embedding (384d) → Initial Search →
Expensive Embedding (1,536d) → Rerank Top-K → Return

成本节省： 与使用昂贵嵌入的单阶段方案相比，成本降低 70%

快速参考清单

模型选择：

  • 已明确数据隐私要求（本地或 API）
  • 已计算预期查询量
  • 已确定质量要求（良好/高/最高）
  • 已检查多语言支持需求

分块：

  • 已分析内容类型（代码、文档、法律文本等）
  • 已选择合适的分块大小（500-1,500 个字符）
  • 已设置重叠长度以避免上下文丢失（50-200 个字符）
  • 已验证分块保留了语义边界

缓存：

  • 已实现内容寻址哈希
  • 已选择缓存后端（Redis、PostgreSQL）
  • 已根据内容变化频率设置 TTL
  • 正在监控缓存命中率（目标：>60%）

性能：

  • 正在跟踪延迟（嵌入生成时间）
  • 正在测量吞吐量（每秒生成的嵌入数）
  • 正在监控成本（API 调用的美元支出）
  • 正在优化批次大小以达到最高效率

评论

支持 Markdown