Embedding 批量生成怎样控制输入分片和结果对应
批量生成 Embedding 时,真正容易出错的通常不是把多条文本放进 input,而是请求拆分后失去了对应关系:某个分片重试、返回项顺序被误读,或者同一索引表混入了不同维度的向量。稳妥的做法是把每条文本包装成带业务 ID 的记录,分片只负责控制请求边界,回填时始终依据响应中的 index 和本地映射。
官方地址:https://platform.openai.com/docs/guides/embeddings
本文只讨论批量输入、维度和索引映射。示例使用 Python,代码中的 API 调用是写法示意,不包含真实密钥,也不在本地执行。
先把“批次对应关系”当成资产
我在做离线文档向量化时,最先保留下来的不是向量本身,而是三组元数据:
- 业务 ID:例如文档编号或数据表主键,跨分片、跨重试都不变。
- 批内 index:本次请求中从 0 开始的位置,用于和 Embeddings API 返回项的
index对齐。 - 向量 schema:模型名、输出维度、编码格式和写入目标,避免旧向量与新向量混放。
这三项就是批处理的“对应关系资产”。如果只保存一个按完成顺序追加的浮点数组,后面很难判断某个向量究竟来自哪条文本。

按预算切分输入,不要切断记录身份
批量请求的核心不是“越大越好”,而是每个请求都能被单独记录、重试和回填。切分时可以先按字符数做工程上的粗分片,再接入 tokenizer 估算 token;无论采用哪种策略,都不要把一条业务记录拆成多个没有共同 ID 的字符串。
下面的示例使用一个保守的字符预算演示分片。实际项目还应根据所用模型、请求限制和文本语言分布调整预算。
from dataclasses import dataclass
@dataclass
class Record:
doc_id: str
text: str
def chunk_records(records: list[Record], max_chars: int) -> list[list[Record]]:
# 每个分片只控制请求大小,不改变记录的业务 ID。
chunks: list[list[Record]] = []
current: list[Record] = []
current_chars = 0
for record in records:
size = len(record.text)
# 单条超预算时保留为独立记录,避免静默截断正文。
if current and current_chars + size > max_chars:
chunks.append(current)
current = []
current_chars = 0
current.append(record)
current_chars += size
if current:
chunks.append(current)
return chunks
这个函数的边界很明确:它只决定哪些记录一起发,不负责生成向量,也不把文档内容改写成摘要。若项目必须按 token 控制大小,应将 len(record.text) 替换为项目统一的 tokenizer 计数,并把计数版本写入批次元数据。
模型和 dimensions 要跟索引 schema 一起锁定
官方文档说明,text-embedding-3-small 默认输出 1536 维,text-embedding-3-large 默认输出 3072 维;新模型也支持通过 dimensions 参数缩短向量。这里有两个容易被忽略的风险。
- 同一索引集合中,新旧请求使用了不同模型或不同
dimensions,导致向量长度不一致。 - 只在代码中写死维度,迁移模型时却没有同步更新写入层和查询层。
因此,建议在批次开始时固定一份 schema,例如“模型名 + dimensions + 编码格式”,并让写入函数把它当作前置条件。想缩短维度时优先在 API 请求中设置 dimensions;如果是生成后手工截断,则还需要按官方说明重新归一化,不能把截断后的数组直接当作等价向量。
EMBEDDING_SCHEMA = {
"model": "text-embedding-3-small",
"dimensions": 768,
"encoding_format": "float",
}
def build_request(texts: list[str]) -> dict:
# 请求和索引表共用同一份 schema,避免写入时悄悄换维度。
return {
"model": EMBEDDING_SCHEMA["model"],
"input": texts,
"dimensions": EMBEDDING_SCHEMA["dimensions"],
"encoding_format": EMBEDDING_SCHEMA["encoding_format"],
}
按返回 index 回填,不按完成顺序猜测
一次请求包含多条输入时,本地可以建立“批内 index → 业务 ID”的表。响应中的每个 embedding 项也带有 index,回填时先确认它落在当前分片范围内,再按这个 index 找回业务记录。
这一步看起来比 zip(records, response.data) 麻烦一点,但它把最危险的隐式假设显式化了:只有 index 集合完整、没有重复、向量维度符合 schema,才允许进入写入阶段。
def request_and_map(client, chunk: list[Record]) -> list[dict]:
texts = [record.text for record in chunk]
response = client.embeddings.create(**build_request(texts))
expected = set(range(len(chunk)))
actual = [item.index for item in response.data]
# 先检查索引集合,缺项或重复都不能直接写入。
if set(actual) != expected or len(actual) != len(set(actual)):
raise ValueError("Embedding 返回 index 不完整或重复")
mapped: list[dict] = []
for item in response.data:
vector = item.embedding
# 维度不符说明请求 schema 或目标索引配置发生了漂移。
if len(vector) != EMBEDDING_SCHEMA["dimensions"]:
raise ValueError("Embedding 维度与当前 schema 不一致")
mapped.append({
"doc_id": chunk[item.index].doc_id,
"batch_index": item.index,
"embedding": vector,
"model": EMBEDDING_SCHEMA["model"],
"dimensions": len(vector),
})
return mapped
官方示例也使用返回项的 index 将向量和原始列表重新对应。这里把这个关系扩展成了写入前的显式检查:doc_id 来自本地分片,向量来自响应,二者通过 batch_index 连接。

失败时只重试缺失分片
批量任务最怕“整批重跑”。假设 10 个分片中只有第 7 个请求超时,重新发送全部分片会制造重复成本,还可能把已经成功写入的记录覆盖成另一批结果。更安全的做法是为每个分片保存状态:
| 字段 | 用途 |
|---|---|
| batch_id | 标识本次批次,便于审计和恢复 |
| chunk_id | 标识分片,失败时只重试该分片 |
| input_ids | 保存业务 ID 顺序,不重新从正文推断 |
| schema | 记录模型和 dimensions,拒绝漂移 |
| status | 区分 pending、succeeded 和 failed |
重试前先读取原分片快照,不能按照当前数据库查询结果重新分页;数据在两次尝试之间发生增删时,重新分页会改变 index 和业务 ID 的对应关系。
把批处理风险分成三层
按安全威胁建模的方式看,这类问题主要有三层:
- 身份层:分片或重试后,向量找不到原来的业务 ID。控制措施是保存不可变 ID 和输入快照。
- 结构层:模型或 dimensions 漂移,查询向量与库内向量不兼容。控制措施是 schema 绑定和维度检查。
- 记录层:失败重试覆盖成功结果,却没有留下过程。控制措施是 batch_id、chunk_id 和状态日志。
这不是为了把普通脚本写得复杂,而是把“错位”从事后排查变成写入前可以拒绝的条件。对小数据量脚本,至少保留 doc_id、batch_index 和 dimensions;对长期离线任务,再增加分片状态与请求记录。
批量 Embedding 的最小检查清单
- 每条输入是否有跨分片不变的业务 ID?
- 分片是否保存了原始记录顺序,而不是只保存文本数组?
- 请求中的模型和
dimensions是否与写入 schema 一致? - 是否按响应
index回填,而不是按返回顺序盲目zip? - 是否在写入前检查 index 完整性、重复项和向量长度?
- 失败时能否只重试原分片,并保留同一个输入快照?
如果这六项都能回答“是”,批量 Embedding 的关键风险就已经从“结果看起来像成功”变成了可追踪的映射关系。分片大小可以继续优化,但业务 ID、批内 index 和向量 schema 不应随着优化一起变化。
相关问题
Embedding 的 dimensions 可以在不同批次随意改变吗?
不建议对同一个向量集合随意改变。改变后应建立清晰的 schema 版本,并让查询侧使用同样的模型和维度;否则即使数组能写入,也无法保证比较结果有意义。
为什么不直接按 response.data 的顺序回填?
因为顺序是一个隐式假设。使用返回项的 index 可以把对应关系写成明确规则,并在缺项、重复项或重试场景下及时拒绝错误结果。
单条文本超过分片预算怎么办?
不要静默截断。可以单独记录超限项,再依据业务语义做分段,并让多个片段共享父级业务 ID;这已经超出本文的单条记录映射范围,应另行设计片段级主键。
结构化输出怎样约束模型返回 JSON Schema
- 上一篇
- 结构化输出怎样约束模型返回 JSON Schema
- 下一篇
- Hugging Face Datasets DatasetDict 跨 train 与 validation 的 map 处理方案
-
- 科技周边 · 人工智能 | 10分钟前 | 多模态输入 Gemini API Files API MIME 类型
- Gemini API 怎样把文件输入和文本提示放在同一请求
- 164浏览 收藏
-
- 科技周边 · 人工智能 | 10分钟前 | 人工智能 · padding Transformers tokenizer attention_mask input_ids truncation
- Transformers tokenizer 怎样让 padding 与 truncation 对齐批量输入
- 416浏览 收藏
-
- 科技周边 · 人工智能 | 11分钟前 |
- Hugging Face Datasets DatasetDict 跨 train 与 validation 的 map 处理方案
- 267浏览 收藏
-
- 科技周边 · 人工智能 | 16分钟前 | 人工智能 · 结构化输出 · JSON Schema Responses API Structured Outputs strict refusal
- 结构化输出怎样约束模型返回 JSON Schema
- 328浏览 收藏
-
- 科技周边 · 人工智能 | 21分钟前 | 人工智能 · openai · 工具调用 Responses API function_call_output call_id
- Responses API 怎样处理工具调用后的继续响应
- 156浏览 收藏
-
- 科技周边 · 人工智能 | 21分钟前 | 人工智能 · openai · 多轮对话 Responses API conversation state OpenAI API previous_response_id
- Responses API 怎样用上一轮响应继续多轮对话
- 121浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 |
- GPT-Live双工语音会话接入后端
- 470浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 | 人工智能 · 文本生成 Transformers 重复片段 no_repeat_ngram_size GenerationConfig
- Transformers 怎样用 no_repeat_ngram_size 减少重复片段
- 493浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 | python · 人工智能 · OpenAI session Agents SDK SQLiteSession conversation_id
- OpenAI Agents API保存持久会话
- 414浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 |
- Transformers在vLLM中部署生成模型
- 122浏览 收藏
-
- 科技周边 · 人工智能 | 1天前 |
- Transformers datasets流式读取训练数据
- 275浏览 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 485次学习
-
- PubMedQA
- 深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
- 1054次使用
-
- H2O EvalGPT
- H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
- 1054次使用
-
- LMArena
- LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
- 1219次使用
-
- HELM
- 深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
- 1161次使用
-
- MMBench
- MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
- 1004次使用
-
- CodeGeeX for Jetbrains IDEs正式上线!
- 2023-01-17 284浏览
-
- 技术阿里云实现ocr批量图片和pdf文件表格图片转换excel文档/支持票据图片提取/普通图片文字提取处理
- 2023-01-18 387浏览
-
- 直播预告|FeatureStore Meetup V2
- 2023-01-10 328浏览
-
- 深入浅出特征工程 – 基于 OpenMLDB 的实践指南(上)
- 2023-02-25 426浏览
-
- 开源机器学习数据库OpenMLDB v0.4.0产品介绍
- 2023-01-10 147浏览

