我用 LangChain 写了一个带“定速巡航”的向量化工具，发布到 PyPI 了！

批量调用 Embedding API 怕限流？怕断点重算？我写了一个 PyPI 包，帮你自动控制速率、避免重复计算。

前言

作为一名 RAG（检索增强生成）开发者，我每天都在跟"向量化"打交道：把几千篇文档切块，再调用 Embedding 模型转成向量。这个过程看似简单，却藏着三大痛点：

1. 怕限流：调用 OpenAI、阿里云等云端 API 时，速率稍快就报 429，代码中断，还得写一堆重试逻辑。
2. 怕中断：一次性处理几万块，网络一闪断或电脑休眠，所有向量全白算，第二天从头再来。
3. 怕拖垮：batch_size 设大了爆显存，设小了太慢，每次调参全凭感觉。

于是，我利用 LangChain 的底层能力，造了一个专门解决这些问题的轮子------ ratelimited-embedder 。

它就像一个带"定速巡航"和"断点记忆"的向量化司机：你只管给文本，它自动按你设定的速度跑，跑累了自动减速，中途熄火了还能接着上次的位置继续跑。

今天这篇文章，我会把它的设计思路、用法以及如何接入云端大模型（阿里云 Qwen / OpenAI）完整分享出来。

🔗 GitHub：https://github.com/lowers/ratelimited-embedder
📦 PyPI：pip install ratelimited-embedder

---

一、为什么需要专用的向量化控制器？

LangChain 虽然提供了很好的 Embedding 抽象，但它并没有内置"批量速率控制"、"自动降速"、"断点续传"这些能力。开发者仍然需要自己写 while 循环、手动管理缓存、处理重试。

而 ratelimited-embedder 的目标就是：让你写一行代码，就能获得工业级的向量化可靠性。

它的核心特性：

特性	解决的问题
速率控制	设置 batch_size 和 delay，平滑调用
自动降速	单批耗时过长时自动减半 batch 并增加延迟
断点续传	基于 SQLite 的 MD5 缓存，重启后不重复计算
硬件建议	根据内存和 CPU 自动推荐初始 batch_size
LangChain 无侵入适配	wrap_embeddings 一行代码包装现有模型

---

二、快速上手

1. 安装

pip install ratelimited-embedder

如果需要本地 Ollama 嵌入（免费），提前启动 Ollama 并拉取模型：

ollama pull nomic-embed-text   # 或 qwen3-embedding:0.6b

2. 直接使用 RateControlledEmbedder

假设你已经有一个嵌入函数（例如封装了 OpenAI API 调用），你可以直接把它交给 RateControlledEmbedder：

from ratelimited_embedder import RateControlledEmbedder

def my_embed_func(texts: list[str]) -> list[list[float]]:
    # 实际调用 OpenAI / Cohere / 本地模型
    return [[0.1, 0.2, 0.3] for _ in texts]

embedder = RateControlledEmbedder(
    embeddings=my_embed_func,   # 注意参数名是 embeddings
    batch_size=16,
    delay=0.5,
    slow_threshold=2.0,
    cache_dir="./my_cache",     # 断点续传的目录
)

texts = ["三国演义 第一回", "桃园三结义", "温酒斩华雄"]
vectors = embedder.run(texts)   # 返回 list[list[float]]

print(f"生成 {len(vectors)} 个向量")

cache_dir 是实现断点续传的关键：第一次运行会把向量存入 SQLite 文件，第二次运行相同文本时瞬间返回。

3. 包装 LangChain 嵌入模型（无侵入）

如果你已经在用 LangChain 的嵌入对象，比如 OllamaEmbeddings，可以用 wrap_embeddings 包装，完全不影响原有代码：

from langchain_ollama import OllamaEmbeddings
from ratelimited_embedder import wrap_embeddings

original_emb = OllamaEmbeddings(model="nomic-embed-text")
wrapped_emb = wrap_embeddings(
    original_emb,
    batch_size=8,
    delay=0.5,
    cache_dir="./cache",
)

# 之后使用 wrapped_emb 与原来的 emb 完全一样
vectors = wrapped_emb.embed_documents(["hello", "world"])

wrap_embeddings 返回的对象仍实现了 embed_documents 和 embed_query，可直接替换 LangChain 链条中的嵌入组件。

4. 获取硬件建议

不知道 batch_size 设多少合适？调用 get_hardware_suggestion() 即可：

from ratelimited_embedder import get_hardware_suggestion

suggestion = get_hardware_suggestion()
print(suggestion)
# 输出示例：{'batch_size': 16, 'delay': 0.5, 'mem_gb': 15.9, 'mem_percent': 45.2, 'cpu_count': 16}

---

三、核心设计：自动降速与断点续传

自动降速

工具内部会监控每一批的处理耗时。如果某批耗时超过 slow_threshold（默认 2 秒），意味着当前批次过大或后端压力大，它会自动执行：

• batch_size = max(1, batch_size // 2)
• delay = min(delay * 1.5, 30.0)

这个策略是指数后退的变体，能快速适应后端负载变化。降速事件会被记录在统计信息中。

断点续传（缓存）

缓存基于文本内容的 MD5 哈希，存储到 SQLite 数据库中。每个文本块独立缓存，即使程序崩溃或电脑休眠，下次启动也会自动跳过已计算的部分。

缓存目录示例：

my_cache/
  └─ vector_cache.db

你可以随时删除该目录来清空缓存。不同项目只要指定不同的 cache_dir，就不会互相干扰。

统计信息

调用 embedder.get_stats() 会返回以下关键指标：

• total_chunks：总处理块数
• cache_hits / cache_misses：缓存命中次数
• batches：总批次数
• degrade_count：降速发生次数
• avg_batch_time：平均每批耗时

这些数据对调优 batch_size 和 delay 非常有帮助。

---

四、接入云端大模型（阿里云 Qwen / OpenAI）

ratelimited-embedder 不仅支持本地模型，也能完美集成云端大模型的 Embedding API。你只需提供符合 LangChain 接口的嵌入对象，工具会自动为其加上速率控制、自动降速和断点续传------这对于调用付费 API 尤其重要，能有效避免限流、节省成本。

1. 安装云端模型对应的依赖

云服务	依赖安装命令
阿里云 DashScope	pip install langchain-community（已包含） 并设置环境变量 DASHSCOPE_API_KEY
OpenAI	pip install langchain-openai 并设置环境变量 OPENAI_API_KEY
其他 OpenAI 兼容服务	同上，只需修改 base_url

2. 示例：使用阿里云 Qwen Embedding 模型

from langchain_community.embeddings import DashScopeEmbeddings
from ratelimited_embedder import RateControlledEmbedder

# 初始化云端嵌入模型（会自动从环境变量读取 API Key）
qwen_emb = DashScopeEmbeddings(model="text-embedding-v3")

controller = RateControlledEmbedder(
    embeddings=qwen_emb,           # 关键：只需替换这里的对象
    batch_size=16,                 # 根据 API 限制调整
    delay=1.0,                     # 控制请求间隔，避免 429
    slow_threshold=2.0,
    cache_dir="./qwen_cache",
)

texts = ["你的文本块1", "文本块2"]
vectors = controller.run(texts)    # 自动批量调用 Qwen API
print(f"生成 {len(vectors)} 个向量")

3. 示例：使用 OpenAI Embedding 模型

from langchain_openai import OpenAIEmbeddings
from ratelimited_embedder import RateControlledEmbedder

openai_emb = OpenAIEmbeddings(model="text-embedding-3-small")

controller = RateControlledEmbedder(
    embeddings=openai_emb,
    batch_size=8,            # OpenAI 建议较小 batch
    delay=0.5,
    cache_dir="./openai_cache",
)

vectors = controller.run(texts)
# 第二次运行相同 texts 时，直接从缓存读取，不再调用 API

4. 配合 wrap_embeddings 无侵入使用

如果你已经在 LangChain 流程中使用了 from_documents 等方法，可以用 wrap_embeddings 包装原有嵌入对象，自动增加速率控制和缓存：

from langchain_community.embeddings import DashScopeEmbeddings
from ratelimited_embedder import wrap_embeddings
from langchain_milvus import Milvus

raw_emb = DashScopeEmbeddings(model="text-embedding-v3")
wrapped_emb = wrap_embeddings(raw_emb, cache_dir="./milvus_cache")

# 直接替换，原有代码无需改动
vector_store = Milvus.from_documents(
    documents, wrapped_emb, connection_args={"uri": "http://localhost:19530"}
)

---

五、与 FAISS / Milvus 集成

ratelimited-embedder 只负责生成向量，不绑定任何存储后端。你可以自由选择向量数据库。

import faiss
import numpy as np
from ratelimited_embedder import RateControlledEmbedder

embedder = RateControlledEmbedder(embeddings, ...)
vectors = embedder.run(texts)

# 构建 FAISS 索引
dim = len(vectors[0])
index = faiss.IndexFlatL2(dim)
index.add(np.array(vectors).astype('float32'))

如果需要生产级向量数据库 Milvus：

from langchain_milvus import Milvus

vector_store = Milvus.from_documents(
    documents, wrapped_emb, connection_args={"uri": "http://localhost:19530"}
)

这种松耦合设计让你可以自由选择存储层，不被工具绑定。

---

六、本地 vs 云端：如何选择？

对比项	本地模型 (Ollama)	云端模型 (Qwen/OpenAI)
成本	免费（电费）	按 token 付费（新用户有免费额度）
速度	受本地 GPU 限制	快，但依赖网络
隐私	数据不出本地	数据上传至云端
适用场景	开发测试、隐私敏感、离线环境	生产环境、高精度、不想维护硬件

你的工具在这两种模式下表现同样出色：使用本地模型时确保资源稳定；使用云端模型时控制成本 & 避免限流。

---

七、发布到 PyPI 后的真实体验

自从我把这个工具发布到 PyPI（版本 0.1.1），我在自己的几个 RAG 项目里全面替换了手写的 while 循环。最直观的感受：

1. 代码量锐减：原来 50+ 行的批量处理逻辑，变成了 5 行。
2. 不再焦虑限流 ：设置了 batch_size=8, delay=0.5 后，OpenAI 的 429 再也没有出现过。
3. 半夜跑数不再害怕：断点续传让我可以放心关掉电脑，第二天接着跑。

社区有朋友用它处理百万级文档，配合 Milvus 取得了很好的效果。

---

八、未来计划

• 异步版本 ：增加 async 支持，适配高性能场景。
• 更多统计指标：可选 token 计数器（针对 OpenAI 等模型）。
• 支持更多缓存后端：Redis（用于分布式场景）。
• 集成到 LangChain 官方生态：争取成为 LangChain 社区推荐的速率控制组件。

欢迎到 GitHub 仓库提 issue 或 PR。

---

九、总结

ratelimited-embedder 是我为解决实际问题而写的一个小工具，它专注做一件事：让向量化过程稳定、可控、可恢复。它把那些重复、繁琐、容易出错的"基础设施"代码封装起来，让业务代码更干净。

如果你也经常被 Embedding API 的速率限制和大规模重复计算困扰，不妨试试这个工具。

一键安装：

pip install ratelimited-embedder

然后像这样使用：

from ratelimited_embedder import RateControlledEmbedder

embedder = RateControlledEmbedder(embeddings, cache_dir="./cache")
vectors = embedder.run(texts)

希望它能给你带来和给我一样的轻松感。更多用法和 API 细节，请参考 GitHub 仓库的 README。

你的 RAG 项目，值得一个"永不抛锚"的向量化引擎。

---

如果这篇文章对你有帮助，欢迎点赞、收藏、转发，也欢迎在评论区交流你的使用心得。

关注我，后续还会分享更多 AI 工程化实战经验。