在使用阿里云 DashScope 向量模型如text-embedding-v2进行向量化时你是否遇到过batch size is invalid, it should not be larger than 20的报错本文从源码层面剖析问题根因并提供一套完整的分批处理方案让你的 embedding 流程稳如磐石。问题现象当你在项目中调用 DashScope Embedding API 时突然收到如下报错status_code: 400 code: InvalidParameter message: 400 InternalError.Algo.InvalidParameter: Value error, batch size is invalid, it should not be larger than 20.: input.contents关键信息batch size is invalid, it should not be larger than 20这意味着 DashScope Embedding API 对单次请求的文本数量有硬性限制最多 20 条。根因分析为什么会触发这个报错在典型的 RAG 项目或知识库构建场景中我们通常会这样写代码fromlangchain.embeddingsimportDashScopeEmbeddingsfromlangchain.vectorstoresimportMilvus# 1. 初始化 embedding 模型embeddingsDashScopeEmbeddings(modeltext-embedding-v2,dashscope_api_keysk-xxxx)# 2. 文档切分后得到大量 chunkdoc_list[...]# 假设有 100 个子块content_list[doc.page_contentfordocindoc_list]# 3. 一次性调用 embedding → 报错vectorsembeddings.embed_documents(content_list)# 超过 20 条就炸# 4. 一次性写入 Milvus → 同样可能炸vector_store.add_documents(doc_list)# 内部也会调 embedding两处高危调用位置调用方式触发场景embedding 计算embeddings.embed_documents(content_list)手动批量向量化向量库存储vector_store.add_documents(doc_list)框架自动调 embedding只要content_list或doc_list的长度超过 20就会触发400 InvalidParameter。解决方案分批处理Step 1写一个通用的分批工具函数fromtypingimportList,Generatordefbatch_split(lst:list,batch_size:int20)-Generator[List,None,None]: 将列表切分为多个小批次 Args: lst: 待切分的原始列表 batch_size: 每批最大数量默认 20适配 DashScope 限制 Yields: 每批子列表 Example: items list(range(45)) for batch in batch_split(items, 20): ... print(f本批 {len(batch)} 条) ... 本批 20 条 本批 20 条 本批 5 条 foriinrange(0,len(lst),batch_size):yieldlst[i:ibatch_size]设计要点使用Generator惰性产出不占用额外内存默认batch_size20与 DashScope 限制对齐最后一批不足 20 条时自动兜底Step 2分批调用 Embeddingfromlangchain.embeddingsimportDashScopeEmbeddingsdefbatch_embed_documents(embeddings:DashScopeEmbeddings,texts:List[str],batch_size:int20)-List[List[float]]: 分批向量化文本规避 DashScope 单批 20 条限制 Args: embeddings: DashScope Embedding 实例 texts: 待向量化的文本列表 batch_size: 每批数量默认 20 Returns: 所有文本的向量结果顺序与输入一致 all_vectors[]foridx,batchinenumerate(batch_split(texts,batch_size)):print(f正在处理第{idx1}批共{len(batch)}条...)# 分批调用每次最多 20 条batch_vectorsembeddings.embed_documents(batch)all_vectors.extend(batch_vectors)# 可选添加短暂延时避免 QPS 超限# time.sleep(0.1)returnall_vectors# 使用示例texts[doc.page_contentfordocindoc_list]# 假设有 100 条vectorsbatch_embed_documents(embeddings,texts)print(f共生成{len(vectors)}个向量维度{len(vectors[0])})关键点使用batch_split将文本切成 ≤20 的小批每批调用embed_documents()结果用extend()合并顺序与输入完全一致不影响后续检索匹配Step 3分批写入向量库Milvus / Chroma / FAISS方案 A手动分批写入 Milvusfromlangchain.schemaimportDocumentfromlangchain.vectorstoresimportMilvusdefbatch_add_documents(vector_store:Milvus,documents:List[Document],batch_size:int20)-None: 分批将文档写入 Milvus规避 DashScope embedding 限制 Args: vector_store: Milvus 向量库实例 documents: 待写入的 Document 列表 batch_size: 每批数量默认 20 foridx,batchinenumerate(batch_split(documents,batch_size)):print(f正在写入第{idx1}批共{len(batch)}条...)# 分批写入框架内部会自动调 embeddingvector_store.add_documents(batch)# 使用示例batch_add_documents(vector_store,doc_list)方案 B如果你手动计算了向量直接分批插入defbatch_insert_with_vectors(vector_store:Milvus,documents:List[Document],vectors:List[List[float]],batch_size:int20)-None: 已知向量直接分批插入 Milvus # 确保文档和向量一一对应assertlen(documents)len(vectors)foridx,(doc_batch,vec_batch)inenumerate(zip(batch_split(documents,batch_size),batch_split(vectors,batch_size))):print(f正在插入第{idx1}批共{len(doc_batch)}条...)# Milvus 的 from_texts 或 add_texts 可以直接传入向量vector_store.add_texts(texts[d.page_contentfordindoc_batch],metadatas[d.metadatafordindoc_batch],embeddingsvec_batch)完整实战代码将上述方案整合为一个完整的工具类 DashScope Embedding 分批处理工具 解决 batch size 20 导致的 400 报错 fromtypingimportList,Generator,Optionalimporttimefromlangchain.embeddings.baseimportEmbeddingsfromlangchain.schemaimportDocumentfromlangchain.vectorstores.baseimportVectorStoreclassBatchEmbeddingProcessor:DashScope Embedding 分批处理器def__init__(self,embeddings:Embeddings,batch_size:int20,sleep_interval:Optional[float]None): Args: embeddings: Embedding 模型实例如 DashScopeEmbeddings batch_size: 每批最大数量默认 20 sleep_interval: 每批处理后的休眠秒数防 QPS 超限 self.embeddingsembeddings self.batch_sizebatch_size self.sleep_intervalsleep_intervalstaticmethoddefbatch_split(lst:list,batch_size:int20)-Generator[List,None,None]:切分列表为多个小批次foriinrange(0,len(lst),batch_size):yieldlst[i:ibatch_size]defembed_texts(self,texts:List[str])-List[List[float]]: 分批向量化文本 Args: texts: 待向量化的文本列表 Returns: 向量列表顺序与输入一致 all_vectors[]totallen(texts)foridx,batchinenumerate(self.batch_split(texts,self.batch_size)):print(f[Embedding] 批次{idx1}/{(total-1)//self.batch_size1}f本批{len(batch)}条)batch_vectorsself.embeddings.embed_documents(batch)all_vectors.extend(batch_vectors)ifself.sleep_interval:time.sleep(self.sleep_interval)returnall_vectorsdefadd_to_vector_store(self,vector_store:VectorStore,documents:List[Document])-None: 分批将文档写入向量库 Args: vector_store: 向量库实例Milvus / Chroma / FAISS documents: 待写入的 Document 列表 totallen(documents)foridx,batchinenumerate(self.batch_split(documents,self.batch_size)):print(f[VectorStore] 批次{idx1}/{(total-1)//self.batch_size1}f本批{len(batch)}条)vector_store.add_documents(batch)ifself.sleep_interval:time.sleep(self.sleep_interval)defprocess_documents(self,vector_store:VectorStore,documents:List[Document])-List[List[float]]: 一站式处理向量化 写入向量库 Args: vector_store: 目标向量库 documents: 待处理的文档列表 Returns: 所有向量 texts[doc.page_contentfordocindocuments]# Step 1: 分批向量化vectorsself.embed_texts(texts)# Step 2: 分批写入如果向量库支持直接传向量# 否则让 vector_store.add_documents 内部自行计算self.add_to_vector_store(vector_store,documents)returnvectors# 使用示例 if__name____main__:fromlangchain.embeddingsimportDashScopeEmbeddingsfromlangchain.vectorstoresimportMilvus# 初始化embeddingsDashScopeEmbeddings(modeltext-embedding-v2,dashscope_api_keysk-xxxx)vector_storeMilvus(embedding_functionembeddings,connection_args{host:localhost,port:19530},collection_namemy_docs)# 假设 doc_list 是从文件/网页切分出来的 100 个子块doc_list[...]# List[Document]# 使用分批处理器processorBatchEmbeddingProcessor(embeddingsembeddings,batch_size20,# DashScope 限制sleep_interval0.1# 防 QPS 超限可选)# 一站式处理vectorsprocessor.process_documents(vector_store,doc_list)print(f完成共处理{len(vectors)}条文档)方案对比方案优点缺点适用场景手动分批可控性强能看到进度代码稍多大规模文档处理BatchEmbeddingProcessor封装完整复用方便需额外封装团队项目、长期维护直接调 add_documents代码最少无法控制分批逻辑文档数量 20换用其他 Embedding 模型无分批限制需更换模型对 DashScope 有依赖时不可用进阶兼容其他模型如果你的项目需要同时支持多个 Embedding 模型可以进一步封装classUnifiedEmbeddingProcessor:统一的分批处理器兼容多种 Embedding 模型# 各模型的批量限制BATCH_LIMITS{dashscope:20,openai:2048,# OpenAI text-embedding-3 支持大批量qwen:25,# 通义千问bge:32,# BGE 模型}def__init__(self,embeddings:Embeddings,model_type:strdashscope):self.embeddingsembeddings self.batch_sizeself.BATCH_LIMITS.get(model_type,20)这样无论后端用哪个模型都能自动适配对应的 batch limit。常见坑点总结❌ 坑点 1忘了给add_documents分批# 错误内部会调 embedding同样触发 20 条限制vector_store.add_documents(doc_list)# doc_list 有 100 条 → ✅ 正确手动分批或自定义 VectorStore 子类forbatchinbatch_split(doc_list,20):vector_store.add_documents(batch)❌ 坑点 2只分批了 embedding没分批写入# 错误向量化分批了但写入还是一次性vectorsbatch_embed_documents(embeddings,texts)# ✅ 分批了vector_store.add_documents(doc_list)# ❌ 这里又炸了✅ 正确两个步骤都分批processorBatchEmbeddingProcessor(embeddings,batch_size20)processor.process_documents(vector_store,doc_list)# ✅ 全程分批❌ 坑点 3并发请求导致 QPS 超限# 错误如果用了多线程/异步可能 QPS 超限# DashScope 免费版通常限制 20 QPS✅ 正确添加延时或使用限速器processorBatchEmbeddingProcessor(embeddingsembeddings,batch_size20,sleep_interval0.1# 每批间隔 100ms控制 QPS 10)一句话总结DashScope Embedding 单批最多 20 条超过必报 400。写一个batch_split工具函数在向量化embed_documents和写入add_documents两个环节都分批处理即可彻底解决。如果这篇文章对你有帮助欢迎点赞、收藏、关注有问题可以在评论区留言讨论。