06_TiDB LangChain/LlamaIndex 构建 RAG 应用实战标签TiDBLangChainLlamaIndexRAG向量数据库AI应用开发Python关键词TiDB LangChain、TiDBVectorStore、LlamaIndex TiDB、RAG应用、向量存储、嵌入模型、元数据过滤、检索器、相似度搜索、AI应用实战一、为什么在 LangChain/LlamaIndex 中选择 TiDB构建 RAG 系统时向量存储Vector Store的选择直接影响系统复杂度和运维成本。常见选项有 Pinecone、Chroma、Qdrant、Weaviate当然还有 TiDB。我在实际项目中从 Chroma 迁移到 TiDB 的核心原因只有一个不想维护两套系统。Chroma 纯做向量存储很好但业务数据在 TiDB向量数据在 Chroma意味着数据一致性要自己维护删文档时别忘了删向量结构化过滤要先在 TiDB 查 ID再去 Chroma 过滤两次网络请求监控、告警、备份两套系统各搞一遍把向量迁到 TiDB 后这些问题全消失了。LangChain 和 LlamaIndex 都有官方的 TiDB 向量存储集成迁移成本很低。二、TiDB Vector Store 在 LangChain 中的集成2.1 安装依赖pipinstalllangchain langchain-community langchain-openai tidb-vector pymysql2.2 基础连接配置TiDB Cloud 的连接字符串格式# TiDB Cloud Serverless需要 SSLtidb_connection_string(mysqlpymysql://username:passwordgateway01.eu-central-1.prod.aws.tidbcloud.com:4000/your_database?ssl_verify_certtruessl_verify_identitytruessl_ca/path/to/ca.pem)# 本地 TiDB Self-Managed无 SSLtidb_connection_string(mysqlpymysql://root:127.0.0.1:4000/test)2.3 从文档直接创建 Vector Storefromlangchain_community.vectorstoresimportTiDBVectorStorefromlangchain_openaiimportOpenAIEmbeddingsfromlangchain.text_splitterimportRecursiveCharacterTextSplitterfromlangchain_community.document_loadersimportDirectoryLoader,TextLoader# 初始化嵌入模型embedding_modelOpenAIEmbeddings(modeltext-embedding-3-small,openai_api_keysk-your-key)# 加载文档loaderDirectoryLoader(./docs,glob**/*.md,loader_clsTextLoader)documentsloader.load()# 文本分块关键参数chunk_size 和 chunk_overlaptext_splitterRecursiveCharacterTextSplitter(chunk_size800,# 每块约 800 字符chunk_overlap100,# 相邻块重叠 100 字符避免信息截断separators[\n\n,\n,。,,, ]# 中文友好的分隔符)chunkstext_splitter.split_documents(documents)print(f文档总数{len(documents)})print(f分块总数{len(chunks)})# 创建 TiDB Vector Store 并写入向量# TiDB 会自动创建表如果不存在vector_storeTiDBVectorStore.from_documents(documentschunks,embeddingembedding_model,connection_stringtidb_connection_string,table_namelangchain_rag_docs,# TiDB 中的表名distance_strategycosine# 使用余弦距离)print(向量数据写入完成)2.4 向量搜索与相似度搜索# 加载已存在的 Vector Store不重新创建vector_storeTiDBVectorStore(connection_stringtidb_connection_string,table_namelangchain_rag_docs,embedding_functionembedding_model,distance_strategycosine)# 基础相似度搜索docsvector_store.similarity_search(TiDB 向量索引怎么创建,k5)fordocindocs:print(f来源{doc.metadata.get(source,unknown)})print(f内容{doc.page_content[:200]})print()# 带分数的相似度搜索可以设置阈值过滤docs_with_scorevector_store.similarity_search_with_score(分布式事务的实现原理,k10)# 过滤掉相关性太低的结果filtered_docs[(doc,score)fordoc,scoreindocs_with_scoreifscore0.5# 余弦距离小于 0.5相似度大于 0.5]2.5 元数据过滤结构化 向量的复合查询这是 TiDB 在 LangChain 生态中的杀手级特性。向量存储时附带元数据查询时可以结合元数据过滤fromlangchain_community.vectorstoresimportTiDBVectorStore# 写入文档时附带元数据texts[TiDB 支持跨行事务...,向量搜索基于余弦相似度...,TiDB Cloud Serverless 自动扩缩容...]metadatas[{category:事务,version:8.5,difficulty:advanced},{category:向量搜索,version:8.4,difficulty:intermediate},{category:云服务,version:cloud,difficulty:beginner},]vector_store.add_texts(texts,metadatasmetadatas)# 元数据过滤查询# 支持的运算符$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $or, $and# 示例1精确匹配resultsvector_store.similarity_search(数据库事务处理,k5,filter{category:{$eq:事务}}# 只查询事务类别)# 示例2范围过滤resultsvector_store.similarity_search(TiDB 新特性,k5,filter{version:{$in:[8.5,8.4]}}# 只查 8.x 版本文档)# 示例3复合条件ANDresultsvector_store.similarity_search(向量搜索性能优化,k5,filter{$and:[{category:{$eq:向量搜索}},{difficulty:{$in:[intermediate,advanced]}}]})# 示例4复合条件ORresultsvector_store.similarity_search(数据库高可用,k5,filter{$or:[{category:{$eq:架构}},{category:{$eq:运维}}]})2.6 集成到 LangChain RAG Chainfromlangchain_openaiimportChatOpenAIfromlangchain.chainsimportRetrievalQAfromlangchain.promptsimportPromptTemplate# 配置检索器Retrieverretrievervector_store.as_retriever(search_typesimilarity_score_threshold,# 按相似度阈值过滤search_kwargs{score_threshold:0.7,# 相似度低于 0.7 的结果丢弃k:5,# 最多返回 5 个结果filter:{category:{$ne:deprecated}}# 排除废弃文档})# 配置 LLMllmChatOpenAI(modelgpt-4o-mini,temperature0.1,openai_api_keysk-your-key)# 自定义 RAG Promptrag_promptPromptTemplate.from_template( 你是一个专业的技术文档助手。请基于以下参考内容回答用户问题。 参考内容 {context} 用户问题{question} 注意 1. 仅基于提供的参考内容回答不要凭空想象 2. 如果参考内容不足以回答问题请明确说明 3. 回答要具体尽量包含示例代码或配置 )# 构建 RAG Chainrag_chainRetrievalQA.from_chain_type(llmllm,chain_typestuff,# 所有文档合并为一个 context适合小文档retrieverretriever,chain_type_kwargs{prompt:rag_prompt},return_source_documentsTrue)# 执行查询resultrag_chain.invoke({query:TiDB 如何配置向量索引})print(回答,result[result])print(\n参考来源)fordocinresult[source_documents]:print(f -{doc.metadata.get(source,unknown)})三、LlamaIndex 与 TiDB 的集成3.1 安装与配置pipinstallllama-index llama-index-vector-stores-tidbvectorfromllama_index.coreimportVectorStoreIndex,SimpleDirectoryReaderfromllama_index.vector_stores.tidbvectorimportTiDBVectorStoreasLlamaIndexTiDBfromllama_index.coreimportStorageContextfromllama_index.embeddings.openaiimportOpenAIEmbedding# 初始化 TiDB 向量存储tidb_vector_storeLlamaIndexTiDB(connection_stringtidb_connection_string,table_namellamaindex_docs,distance_strategycosine)# 读取文档documentsSimpleDirectoryReader(./knowledge_base).load_data()# 创建存储上下文storage_contextStorageContext.from_defaults(vector_storetidb_vector_store)# 构建索引自动嵌入并存入 TiDBembed_modelOpenAIEmbedding(modeltext-embedding-3-small,api_keysk-your-key)indexVectorStoreIndex.from_documents(documents,storage_contextstorage_context,embed_modelembed_model,show_progressTrue)print(LlamaIndex 索引构建完成)3.2 LlamaIndex 查询引擎fromllama_index.llms.openaiimportOpenAI# 创建查询引擎query_engineindex.as_query_engine(llmOpenAI(modelgpt-4o-mini,api_keysk-your-key),similarity_top_k5,response_modecompact# 精简模式适合生产)# 查询responsequery_engine.query(TiDB 支持哪些向量距离计算函数)print(str(response))# 查看检索到的节点fornodeinresponse.source_nodes:print(f相似度分:{node.score:.4f})print(f内容片段:{node.text[:200]})print()3.3 LlamaIndex 的元数据过滤fromllama_index.core.vector_storesimportMetadataFilter,MetadataFilters# 带元数据过滤的检索retrieverindex.as_retriever(similarity_top_k5,filtersMetadataFilters(filters[MetadataFilter(keycategory,valuetechnical),MetadataFilter(keyversion,value8.5)]))nodesretriever.retrieve(向量搜索性能优化方案)四、嵌入模型最佳选择指南不同的嵌入模型在中文语义表达上差异显著这是实际项目中容易被忽视的坑。4.1 主流嵌入模型对比模型提供商维度中文效果成本适用场景text-embedding-3-smallOpenAI1536良好低通用性价比最高text-embedding-3-largeOpenAI3072优秀高高精度场景jina-embeddings-v3Jina AI1024优秀中多语言、中英混合bge-m3BAAI1024优秀免费开源中英双语bge-base-zhBAAI768极好免费纯中文文档实战建议纯中文知识库优先bge-base-zh本地部署零成本中英混合文档jina-embeddings-v3或bge-m3不想自部署text-embedding-3-small性价比最佳4.2 使用本地开源模型零成本方案fromlangchain_community.embeddingsimportHuggingFaceBgeEmbeddings# 使用 BAAI BGE 中文模型首次运行自动下载embedding_modelHuggingFaceBgeEmbeddings(model_nameBAAI/bge-base-zh-v1.5,model_kwargs{device:cpu},# 有 GPU 改为 cudaencode_kwargs{normalize_embeddings:True# BGE 模型需要归一化})# 直接替换 OpenAIEmbeddings其他代码不变vector_storeTiDBVectorStore.from_documents(documentschunks,embeddingembedding_model,connection_stringtidb_connection_string,table_namebge_rag_docs)五、生产级 RAG 系统架构5.1 完整架构设计生产级 RAG 系统架构 [文档入库流程] 文档源PDF/Word/网页 | 文档加载Loader | 文本清洗去除噪音、格式化 | 语义分块Semantic Chunking | 批量嵌入Batch Embedding -- 嵌入服务OpenAI/本地 | 批量写入 TiDB带元数据 | 构建向量索引ALTER TABLE ... ADD VECTOR INDEX [查询流程] 用户提问 | 查询改写可选HyDE/多查询扩展 | 查询嵌入 | TiDB 混合搜索向量 全文 元数据过滤 | 重排序Cohere Rerank / BGE Reranker可选 | 上下文窗口管理Token 限制内选取最相关内容 | LLM 生成回答 | 来源引用 置信度标注 | 用户回答5.2 查询改写HyDE 技术HyDEHypothetical Document Embeddings是提升 RAG 召回率的有效技巧让 LLM 先生成一个假设的答案文档再用这个文档的向量做相似度搜索而不是直接用原始问题搜索。fromlangchain_openaiimportChatOpenAIdefhyde_search(question:str,vector_store:TiDBVectorStore,k:int5): HyDE 增强检索 1. 让 LLM 生成假设答案 2. 用假设答案的向量做检索 llmChatOpenAI(modelgpt-4o-mini,temperature0)# 生成假设答案hyde_promptf请为以下问题写一个简短的假设答案不需要准确只需要语义合理 问题{question}假设答案100字以内hypothetical_answerllm.predict(hyde_prompt)# 用假设答案搜索比直接用问题搜索效果好 10-20%docsvector_store.similarity_search(hypothetical_answer,# 注意搜索的是假设答案不是原始问题kk)returndocs# 对比效果questionTiDB 怎么处理脑裂问题docs_directvector_store.similarity_search(question,k5)docs_hydehyde_search(question,vector_store,k5)# 通常 HyDE 能找到更相关的文档特别是对于短查询或抽象问题5.3 增量更新策略生产环境的知识库需要定期更新不能每次都全量重建classIncrementalKnowledgeBase:支持增量更新的知识库def__init__(self,vector_store:TiDBVectorStore,conn):self.vsvector_store self.connconndefadd_or_update_document(self,doc_id:str,content:str,metadata:dict):添加或更新文档先删除旧版本再插入新版本# 删除旧版本向量通过元数据 doc_id 过滤withself.conn.cursor()ascursor:cursor.execute(DELETE FROM langchain_rag_docs WHERE JSON_EXTRACT(meta, $.doc_id) %s,(doc_id,))# 插入新版本metadata[doc_id]doc_id self.vs.add_texts(texts[content],metadatas[metadata])print(f文档{doc_id}已更新)defdelete_document(self,doc_id:str):删除文档withself.conn.cursor()ascursor:cursor.execute(DELETE FROM langchain_rag_docs WHERE JSON_EXTRACT(meta, $.doc_id) %s,(doc_id,))print(f文档{doc_id}已删除)六、性能调优与监控6.1 批量嵌入优化importasynciofromopenaiimportAsyncOpenAIasyncdefbatch_embed_async(texts:list,batch_size:int100)-list:异步批量嵌入比同步快 3-5 倍clientAsyncOpenAI()all_embeddings[]foriinrange(0,len(texts),batch_size):batchtexts[i:ibatch_size]responseawaitclient.embeddings.create(modeltext-embedding-3-small,inputbatch)embeddings[item.embeddingforiteminresponse.data]all_embeddings.extend(embeddings)print(f进度{min(ibatch_size,len(texts))}/{len(texts)})returnall_embeddings6.2 查询性能监控importtimeimportloggingdefmonitored_search(vector_store,query,k5,**kwargs):带监控的向量搜索starttime.time()resultsvector_store.similarity_search_with_score(query,kk,**kwargs)elapsed_ms(time.time()-start)*1000# 记录慢查询超过 500ms 告警ifelapsed_ms500:logging.warning(f慢向量查询:{elapsed_ms:.1f}ms | query{query[:50]}| k{k})returnresults七、总结LangChain 和 LlamaIndex 对 TiDB 的官方支持让 RAG 应用开发变得更加顺畅。核心要点TiDBVectorStore是 LangChain 官方集成API 与其他向量存储完全兼容迁移成本低元数据过滤支持完整的逻辑运算符是 TiDB 区别于纯向量数据库的核心优势嵌入模型选择对中文 RAG 效果影响显著中文场景优先考虑 BGE 系列HyDE 查询改写可以显著提升召回率尤其对短查询和抽象问题效果明显增量更新需要通过元数据 doc_id 管理向量的版本避免脏数据污染相关资源TiDB LangChain 集成文档LlamaIndex TiDB 集成BAAI BGE 模型 HuggingFace