Embedding 向量化实战：从单批次到批量处理的深度解析
本文基于 OpenAI 兼容接口的 Embedding 服务，拆解
get_embeddings与get_embeddings_batch的设计逻辑与实战要点。
一、背景：为什么需要两个函数？
在使用 OpenAI 或兼容接口（如阿里通义）的 Embedding 服务时，各平台对单次请求的文本条数有明确限制：
| 平台/模型 | 单次上限 | 超限后果 |
|---|---|---|
| 不同厂商 | 10条、100条、2048条不等 | 返回400 Bad Request |
| 同一厂商不同模型 | 限制可能不同 | 调用失败，业务中断 |
核心矛盾：业务端传入的文本量不确定（可能是 5 条用户查询，也可能是 5000 条文档切片），但 API 有硬性约束。
解决方案：
get_embeddings：封装单次 API 调用（能力层）get_embeddings_batch：封装拆分-循环-合并策略（策略层）
二、函数源码拆解
2.1 基础向量化：get_embeddings
defget_embeddings(self,texts,model=ALI_TONGYI_EMBEDDING_V4,dimensions=64):'''封装 OpenAI 的 Embedding 模型接口'''# 一次性传入全部文本，直接调用 APIdata=self.client.embeddings.create(input=texts,# 字符串列表model=model,# 模型标识dimensions=dimensions# 输出维度：64维)# 提取向量：遍历返回对象，取出 embedding 数组return[x.embeddingforxindata]执行流程：
texts[57条] ──→ [API一次请求] ──→ 返回57个64维向量关键特征：
- 简单直接，无额外逻辑开销
- 要求
len(texts)必须在平台单次限制内 - 返回
list[list[float]]，shape =(len(texts), 64)
2.2 批量向量化：get_embeddings_batch
defget_embeddings_batch(self,texts,model=ALI_TONGYI_EMBEDDING_V4,batch_size=10,dimensions=...):all_embeddings=[]# 累积容器# 按 batch_size 步长生成分片索引# 例：57条文本，batch_size=10 → i 取 0,10,20,30,40,50foriinrange(0,len(texts),batch_size):# 切片取当前批次（Python 切片越界自动截断，不报错）# i=0 → texts[0:10] (10条)# i=50 → texts[50:60] → 实际 texts[50:57] (7条)batch_text=texts[i:i+batch_size]# 当前批次调用 API（与 get_embeddings 完全一致）data=self.client.embeddings.create(input=batch_text,model=model,dimensions=dimensions)# extend() 平铺合并，保证结果是一维列表all_embeddings.extend([x.embeddingforxindata])returnall_embeddings执行流程：
texts[57条] ──→ 切片器 ──┬─→ texts[0:10] ──→ [API请求①] ──→ 10个向量 ─┐ ├─→ texts[10:20] ──→ [API请求②] ──→ 10个向量 ─┤ ├─→ texts[20:30] ──→ [API请求③] ──→ 10个向量 ─┤ ├─→ texts[30:40] ──→ [API请求④] ──→ 10个向量 ─┼─→ extend合并 ├─→ texts[40:50] ──→ [API请求⑤] ──→ 10个向量 ─┤ ↓ └─→ texts[50:57] ──→ [API请求⑥] ──→ 7个向量 ─┘ 57个向量三、核心问题解答
Q1：两个函数的输出结果一样吗？
完全一样。
| 对比维度 | get_embeddings | get_embeddings_batch |
|---|---|---|
| 返回类型 | list[list[float]] | list[list[float]] |
| 向量顺序 | 与texts严格一一对应 | 与texts严格一一对应 |
| 向量维度 | 由dimensions参数决定 | 由dimensions参数决定 |
| 数值精度 | 相同输入，相同输出 | 相同输入，相同输出 |
类比理解：
get_embeddings= 一辆出租车（限载4人）get_embeddings_batch= 智能调度系统（来20人自动派5辆车，最终20人全部送达，顺序不变）
Q2：texts的数据格式是什么？
类型：list[str]— 字符串列表
# 典型示例texts=["如何学习Python编程",# 用户查询"Python入门教程推荐",# 相关文档标题"零基础学Python需要多久",# FAQ问题"Python与Java的区别",# 知识库内容]数据来源：
| 场景 | 获取方式 |
|---|---|
| 文档知识库 | PDF/Word → 清洗 → 按段落/长度切片 |
| 数据库 | SELECT title, content FROM articles |
| 用户输入 | 搜索框、聊天消息、表单提交 |
| 网页爬虫 | 新闻正文、商品详情、论坛帖子 |
| 日志记录 | 客服对话、用户行为文本 |
预处理要点：
- 清洗：去 HTML 标签、特殊字符、多余空格
- 拼接：多字段组合（如
标题\n正文）保证语义完整 - 切分：超长文本截断或滑动窗口，避免超出 token 限制
- 过滤：去空值、过短、无意义文本
Q3：data的返回结构长什么样？
API 标准响应格式（OpenAI 兼容）：
{"object":"list","data":[{"object":"embedding","embedding":[0.0023,-0.0011,...,0.0087],// 64维浮点数组"index":0,// 对应 texts[0]"model":"text-embedding-xxx"},{"object":"embedding","embedding":[0.0056,-0.0034,...,0.0012],// 对应 texts[1]"index":1,...}],"usage":{"prompt_tokens":150,"total_tokens":150}}代码中的提取逻辑：
[x.embeddingforxindata]# ↑ ↑# 向量数组 遍历 data.data 中的每个 embedding 对象四、设计意图与使用建议
4.1 为什么要这样设计？
| 设计分层 | 职责 | 价值 |
|---|---|---|
get_embeddings（能力层） | 封装单次 API 调用 | 代码复用，逻辑清晰 |
get_embeddings_batch（策略层） | 处理任意规模输入 | 生产环境健壮性 |
不合并为一个函数的原因：
- 小数据量时，循环拆分有额外开销（创建迭代器、多次函数调用）
- 大数据量时，全量直接调用必然失败
- 分层设计让调用方根据场景显式选择策略，代码意图明确
4.2 实战使用建议
# 场景1：确定数据量小（如用户实时输入 1-5 条）vectors=get_embeddings(texts)# 场景2：数据量不确定或一定很大（如批量处理文档库）vectors=get_embeddings_batch(texts,batch_size=10)# 场景3：更完善的封装——内部自动判断（推荐）defget_embeddings_auto(self,texts,batch_size=10):iflen(texts)<=batch_size:returnself.get_embeddings(texts)returnself.get_embeddings_batch(texts,batch_size)参数调优：
batch_size根据平台限制调整（阿里通义可能 10 条，OpenAI 可能 2048 条）dimensions=64是主动降维，节省存储和计算，适用于对精度要求不极端的场景
五、关键细节总结
| 细节 | 说明 |
|---|---|
range(0, len(texts), batch_size) | 步长切片，第三个参数是步长而非结束位置 |
texts[i : i+batch_size] | Python 切片越界自动截断，[50:60]在长度57时取[50:57] |
extend()vsappend() | extend平铺合并，最终是[[v1], [v2]]而非[[[v1]], [[v2]]] |
| 顺序保证 | 切片按索引顺序处理，extend按顺序追加，输入输出严格对齐 |
| 异常风险 | 中间批次失败会整体抛异常，已成功的不会回滚（无事务机制） |
六、结语
get_embeddings与get_embeddings_batch的关系，本质是能力与策略的分离：
- 前者回答 “如何调用一次 Embedding API”
- 后者回答 “如何安全地处理任意规模的文本向量化”
在生产环境中，优先使用get_embeddings_batch或在其上封装自动判断逻辑，是保障服务稳定性的最佳实践。
本文基于 OpenAI 兼容接口及阿里通义 Embedding V4 模型分析，各平台具体限制请以官方文档为准。
