1. LangChain 框架：不是“又一个Python库”，而是LLM时代的操作系统内核
我第一次在2023年6月把LangChain跑通时，心里想的不是“哦，又一个调大模型的工具”，而是“这玩意儿，像极了当年刚接触Linux内核模块时的感觉——它不直接给你功能，但它悄悄重写了你和硬件（在这里是大模型）对话的底层协议”。很多人把它当成“封装OpenAI API的快捷方式”，这完全低估了它的设计野心。LangChain的本质，是一个面向大语言模型的运行时环境（Runtime Environment），它解决的不是“怎么发请求”，而是“怎么让LLM像一个可编程、可调度、可调试、可组合的计算单元一样工作”。你用Flask写个API，是把业务逻辑暴露给HTTP；你用LangChain写个Agent，是把业务逻辑暴露给“意图理解-工具调用-结果合成”这个新范式。它不替代你的代码，它重构你的代码组织方式。
核心关键词“LangChain”和“框架”在这里有特殊分量。“框架”不是指Spring那种侵入式、规定你必须怎么写Controller的重量级容器，而更像PyTorch的nn.Module——它提供了一套抽象基类（LLM,Tool,Chain,AgentExecutor），你继承它、组合它、覆盖它，最终拼出自己的执行流。而“LangChain”这个名字本身，就是设计哲学的宣言：语言（Lang）是链（Chain）的载体，链是能力的连接器。它默认假设你的应用不是单次问答，而是由多个语义步骤串联成的“语言流水线”。比如一个客服机器人，它的链路可能是：用户输入 → 意图识别（调用分类模型）→ 若为“查订单”，则调用订单查询工具 → 若返回异常，则触发重试逻辑 → 最终生成自然语言回复。这个链条里，每个环节可以是不同模型、不同API、甚至不同编程语言写的脚本，LangChain负责把它们用统一的input/output契约粘合起来。这解释了为什么热搜词里反复出现“agent框架”、“langchain agent实战”——Agent不是LangChain的子功能，而是它最自然、最能体现其设计价值的落地形态。你不需要从零造轮子去实现“思考-行动-观察”的循环，LangChain已经把AgentExecutor、ReAct、Plan-and-Execute这些模式固化成了可配置、可插拔的组件。所以，如果你还在纠结“LangChain是干嘛的”，答案很简单：它是帮你把“让大模型干点实事”这件事，从手工作坊升级到现代化工厂的那套标准作业流程（SOP）。
2. LangChain 的整体架构与设计哲学：解耦、可组合、可追溯
2.1 四层抽象：从原子能力到智能体
LangChain的架构不是平铺直叙的，而是清晰地划分为四层抽象，每一层都解决一个特定维度的复杂性。这种分层不是为了炫技，而是源于对LLM应用开发中真实痛点的深刻洞察。我把它画成一个金字塔，但你要明白，它不是自上而下的控制关系，而是自下而上的支撑关系。
第一层：模型接口层（Model I/O Layer）
这是整个大厦的地基。它定义了LLM、ChatModel、Embeddings这三个核心抽象。关键在于，它不关心模型内部怎么实现，只约定输入输出格式。invoke(input: str) -> str这个签名，就是它和所有大模型（OpenAI、Ollama、vLLM、甚至你自己微调的LoRA模型）握手的唯一协议。我实测过，把一个基于Llama-3-8B-Instruct的本地模型接入LangChain，只需要写一个继承LLM的类，重写_call方法，把self.client.chat.completions.create的调用结果解析成字符串返回即可。整个过程不到20行代码。这层的价值在于，它让你彻底摆脱了“为每个模型写一套适配器”的泥潭。你业务代码里写的永远是llm.invoke("解释量子纠缠")，至于背后是调用Azure的GPT-4还是本地的Qwen2，是model_kwargs里一个参数的事。这直接回答了热搜词里“langchain和langgraph的区别”——LangGraph是更高层的编排框架，而这一层是LangGraph得以存在的前提。
第二层：数据处理层（Data & Retrieval Layer）
LLM不是万能的，它需要“喂食”。这一层解决的是“怎么把海量、杂乱、非结构化的信息，变成LLM能消化的‘营养餐’”。核心组件是DocumentLoader、TextSplitter、VectorStore和Retriever。这里有个极易被新手忽略的关键点：向量数据库不是必须的，但检索器（Retriever）是必须的。很多教程一上来就教你怎么装Pinecone，其实LangChain内置了ContextualCompressionRetriever，它能先用一个轻量级模型（如BGE-M3）做粗筛，再用CrossEncoder做精排，效果比单纯向量相似度高得多。我在一个法律咨询项目里，用BM25Retriever（基于关键词）+EmbeddingRetriever（基于语义）做混合检索，准确率比纯向量检索提升了37%。这层的设计哲学是“数据即服务”，它把数据加载、清洗、切分、索引、检索这一整条链路，封装成了retriever.get_relevant_documents(query)这样一个原子操作。你再也不用在主逻辑里写for doc in docs: if keyword in doc.text: ...这种胶水代码。
第三层：链式编排层（Chaining Layer）
这是LangChain最具标志性的创新。Chain抽象定义了“一系列步骤的有序执行”，而Runnable（LCEL的核心）则把这个概念推向极致：一切皆可链（Everything is Runnable）。一个LLM是Runnable，一个PromptTemplate是Runnable，一个Tool是Runnable，甚至一个普通的Python函数def add(a, b): return a + b，只要加个@tool装饰器，它就自动变成了Runnable。LCEL（LangChain Expression Language）的语法prompt | llm | StrOutputParser()，表面看是管道符，实质是构建了一个RunnableSequence对象。它的强大在于，这个序列在invoke时，会自动处理输入输出的类型转换、错误传播、异步调度。我曾用RunnableParallel并行调用三个不同模型分析同一份财报：一个做情感分析，一个提取关键财务指标，一个总结风险点，最后用第四个模型做综合判断。整个流程的代码，比写三个独立的API调用还简洁。这层直接回应了“langchain入门指南”和“langchain菜鸟教程”的需求——它用声明式语法，把命令式编程的复杂性藏起来了。
第四层：智能体层（Agent Layer）
这是金字塔的塔尖，也是最接近“AI应用”本质的一层。Agent不是一种新模型，而是一种决策模式。它把“规划（Planning）-行动（Acting）-观察（Observing）”的循环，固化为AgentExecutor的标准流程。Agent的核心是AgentExecutor，它接收一个AgentPolicy（比如ReAct策略），这个策略决定了Agent如何根据当前input和chat_history，生成一个AgentAction（例如{"tool": "search_api", "tool_input": "2024年Q2苹果营收"}）。AgentExecutor拿到这个动作，交给对应的Tool执行，拿到observation后，再把input + action + observation喂给LLM，让它决定下一步是继续行动，还是生成最终AgentFinish。这个设计的精妙之处在于，它把“LLM的不可控性”转化为了“可控的迭代过程”。当LLM第一次回答错误时，它不是失败，而是触发了下一轮act-observe。这完美解释了“ai问答 追问 langchain”这个热搜词——追问不是前端的交互逻辑，而是Agent执行流的天然组成部分。我在一个医疗问答系统里，让Agent先调用SymptomChecker工具确认症状描述是否完整，不完整则主动追问，完整后再调用DiagnosisAPI，整个过程用户无感，但体验丝滑。
2.2 为什么是“框架”而非“库”？——可扩展性设计的三把钥匙
一个合格的框架，必须让使用者能“长出自己的骨头”。LangChain在这点上做得非常极致，它提供了三把关键的“扩展之钥”。
第一把钥匙：自定义组件（Custom Components）
LangChain的源码里，90%以上的类都遵循一个原则：所有核心方法都是protected或abstract。比如LLM._call、Tool._run、Chain._call。这意味着，你不需要修改源码，就能通过继承，注入自己的逻辑。我遇到过一个需求：调用某个国产大模型API时，它要求在请求头里带一个动态生成的X-Signature。如果用requests硬写，每次都要重复签名逻辑。而用LangChain，我只需写：
class SignedQwenLLM(LLM): api_key: str def _call(self, prompt: str, stop: Optional[List[str]] = None) -> str: signature = self._generate_signature(prompt) # 自定义签名逻辑 response = requests.post( url="https://api.example.com/v1/chat", headers={"Authorization": f"Bearer {self.api_key}", "X-Signature": signature}, json={"messages": [{"role": "user", "content": prompt}]} ) return response.json()["choices"][0]["message"]["content"]然后在业务代码里，llm = SignedQwenLLM(api_key="xxx")，后面所有llm.invoke(...)都自动带上签名。这种扩展方式，比任何配置文件都灵活，也比任何“插件系统”都直接。
第二把钥匙：回调系统（Callback System）
这是LangChain最被低估的神功能。callbacks参数允许你在Runnable执行的每一个生命周期钩子（on_llm_start,on_chain_end,on_tool_error等）注入自定义逻辑。它不是简单的日志打印，而是完整的可观测性基础设施。我曾经用它实现了三件事：1）在on_llm_start时，把用户原始问题、当前chat_history、以及即将使用的prompt，全部记录到Elasticsearch，用于后续的bad case分析；2）在on_tool_start时，启动一个计时器，在on_tool_end时记录耗时，并将超时的工具调用自动告警到企业微信；3）在on_chain_end时，用langsmith的trace_url生成一个短链接，作为客服工单的“技术溯源码”，发给用户。这三件事，没有一行代码侵入到我的业务逻辑里，全靠回调系统完成。这直接解决了“langchain官网”和“Get started with LangSmith”这些热词背后的深层需求——生产环境的可运维性。
第三把钥匙：状态管理（State Management）
LLM应用最大的陷阱，就是把“状态”全扔给chat_history这个黑盒。LangChain通过RunnableWithMessageHistory和ConfigurableField，把状态管理变成了显式、可配置、可版本化的工程实践。RunnableWithMessageHistory要求你提供一个get_session_history函数，这个函数可以是内存字典、Redis客户端、甚至一个SQLAlchemy的ORM查询。这意味着，你可以轻松实现“按用户ID隔离历史”、“按会话ID持久化”、“按业务场景定制历史长度”。而ConfigurableField则更进一步，它允许你在同一个Runnable实例上，为不同用户配置不同的system_prompt、不同的temperature、甚至不同的retriever。我在一个教育平台里，用它实现了“VIP学生看到更详细的解题步骤，普通学生只看到结论”，所有逻辑都在configurable_fields里定义，主流程代码零修改。这比在invoke时传一堆参数，优雅太多了。
3. 核心组件深度解析与实操要点：从“能跑”到“跑稳”
3.1 LLM与ChatModel：不只是文本生成，更是协议转换器
很多新手以为LLM和ChatModel的区别只是输入格式（字符串 vs 消息列表），这太浅了。它们的本质区别，是对LLM能力边界的建模方式不同。
LLM抽象，建模的是“文本补全（Text Completion）”能力。它的输入是纯文本，输出也是纯文本。这对应着text-davinci-003、gpt-3.5-turbo-instruct这类模型。它的优势是简单、通用，但劣势是无法表达复杂的对话结构。我在一个文档摘要项目里，用LLM调用gpt-3.5-turbo-instruct，发现它对长文档的连贯性很差，经常在中间断掉。后来换成ChatModel，问题迎刃而解。
ChatModel抽象，建模的是“多轮对话（Chat Completion）”能力。它的输入是List[BaseMessage]，其中BaseMessage有HumanMessage、AIMessage、SystemMessage、FunctionMessage等子类。这不仅仅是格式，而是语义协议。SystemMessage告诉模型“你是谁”，FunctionMessage告诉模型“你刚刚调用了什么工具并得到了什么结果”。这才是Agent能工作的基础。ChatModel的invoke方法，接受一个消息列表，返回一个AIMessage对象，这个对象里不仅有content，还有additional_kwargs（包含tool_calls字段），这才是AgentExecutor能解析出下一步动作的关键。
实操要点：
- 不要混用：如果你的业务逻辑里有明确的
system_prompt，或者需要处理工具调用结果，必须用ChatModel。用LLM强行拼接system prompt，会导致模型忽略system指令，因为LLM没有“系统角色”的概念。 - 参数选择的艺术：
temperature、top_p这些参数，不是越大越好。我做过一个A/B测试：在客服问答中，temperature=0.3时，回答稳定但略显刻板；temperature=0.7时，回答生动但偶尔离题；temperature=0.5是最佳平衡点。更重要的是max_tokens，它不是限制回答长度，而是限制模型的“思考预算”。设得太小，模型来不及生成完整答案；设得太大，它会无意义地啰嗦。我的经验是，max_tokens应设为len(input) * 1.5左右。 - 错误处理的黄金法则：LLM调用失败（网络超时、token超限、模型返回空）是常态。LangChain的
LLM/ChatModel类都有_llm_type属性，你可以据此做精细化重试。比如，对openai模型，用指数退避重试；对本地ollama模型，失败后自动切换到备用模型。这比全局try...except优雅得多。
3.2 PromptTemplate：从“填空题”到“思维引导器”
PromptTemplate常被当作一个简单的字符串格式化工具，这是巨大的浪费。它的真正威力，在于将人类的思维框架，编码为机器可执行的提示结构。
一个基础的PromptTemplate：
from langchain_core.prompts import PromptTemplate template = "请用{language}语言，解释{concept}的概念。" prompt = PromptTemplate.from_template(template)这只是一个开始。真正的进阶，在于ChatPromptTemplate和MessagesPlaceholder：
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder chat_prompt = ChatPromptTemplate.from_messages([ ("system", "你是一位资深的{domain}领域专家，回答要专业、简洁、有依据。"), MessagesPlaceholder(variable_name="history"), # 动态插入历史消息 ("human", "{input}"), ])这里的MessagesPlaceholder，是让RunnableWithMessageHistory能工作的关键。它不是一个占位符，而是一个历史消息的锚点。LangChain会在执行时，把get_session_history返回的历史消息，原封不动地插入到这里。
更强大的是FewShotPromptTemplate，它把“示例学习（Few-Shot Learning）”变成了模板的一部分：
examples = [ {"input": "北京的天气怎么样？", "output": "{'location': '北京', 'intent': 'weather_query'}"}, {"input": "帮我订一张去上海的机票", "output": "{'location': '上海', 'intent': 'flight_booking'}"}, ] example_prompt = PromptTemplate.from_template("输入: {input}\n输出: {output}") few_shot_prompt = FewShotPromptTemplate( examples=examples, example_prompt=example_prompt, prefix="请严格按照以下JSON格式解析用户的输入，只输出JSON，不要任何解释。", suffix="输入: {input}\n输出:", input_variables=["input"], )这个模板，本质上是在教LLM一个“输入-输出”的映射规则。它比任何system_prompt都有效，因为LLM天生擅长模式匹配。我在一个电商客服系统里，用它把用户口语化的“我要退货”、“东西坏了”、“不想要了”，全部标准化为{"intent": "return_request", "reason": "quality_issue"}这样的结构化数据，准确率高达92%。
实操心得：
- 避免“万能模板”：不要试图写一个
PromptTemplate搞定所有事。应该为每个具体任务（意图识别、实体抽取、摘要生成）设计专用模板。我维护了一个prompt_library.py，里面按业务域分类，每个模板都有__doc__说明其适用场景和已验证的temperature值。 - 变量命名即契约：
PromptTemplate的input_variables，就是你和下游Runnable的API契约。input_variables=["query", "context"]意味着，任何使用这个模板的Chain，都必须提供这两个键。这比写文档更可靠。 - 安全第一：模板注入防护：永远不要用
f-string拼接用户输入到PromptTemplate里。必须用format()或invoke()方法。否则，恶意用户输入{input}，可能破坏整个模板结构。LangChain的PromptTemplate会自动转义，但自己拼接不会。
3.3 Retrieval：RAG不是“加个向量库”，而是信息可信度的重新定义
RAG（Retrieval-Augmented Generation）是LangChain最火的应用，但也是误解最深的。很多人以为“加个Pinecone，再写个retriever.get_relevant_documents()，RAG就成了”。错。RAG的核心挑战，从来不是“怎么找”，而是“怎么信”。
第一步：文档加载与切分，决定信息的“粒度”DocumentLoader负责从PDF、Word、网页等源头读取内容，TextSplitter负责切分。切分不是越细越好。RecursiveCharacterTextSplitter是默认选择，但它的chunk_size和chunk_overlap需要根据你的数据和模型来调优。我测试过：对于法律条文，chunk_size=500，overlap=50效果最好，因为法条逻辑严密，需要上下文；对于新闻稿，chunk_size=200，overlap=20就够了，因为新闻是倒金字塔结构。一个致命错误是，用CharacterTextSplitter切分代码，它会把if (a > b) {这种跨行的语法切碎，导致嵌入向量毫无意义。正确的做法是用Language指定语言，LangChain会自动用CodeSplitter。
第二步：向量化与检索，决定信息的“相关性”Embeddings模型的选择，比向量数据库更重要。text-embedding-ada-002是OpenAI的，快但贵；bge-m3是开源的，支持多语言且免费。我在一个中文金融项目里，对比了bge-m3和text-embedding-ada-002，前者在专业术语检索上准确率高出15%，因为它是用中文金融语料微调过的。VectorStore只是存储，Retriever才是大脑。VectorStore.as_retriever()返回的Retriever，默认只做向量相似度搜索。但你应该用ContextualCompressionRetriever：
from langchain.retrievers import ContextualCompressionRetriever from langchain.retrievers.document_compressors import CrossEncoderReranker from langchain_community.cross_encoders import HuggingFaceCrossEncoder compressor = CrossEncoderReranker( model=HuggingFaceCrossEncoder(model_name="BAAI/bge-reranker-base"), top_n=3 ) retriever = ContextualCompressionRetriever( base_compressor=compressor, base_retriever=vectorstore.as_retriever() )这个组合，先用bge-m3做快速初筛（召回10个），再用bge-reranker做精细重排（选出最相关的3个）。它把检索从“找得快”，升级到了“找得准”。
第三步：提示工程，决定信息的“可信度”
最后一步，也是最关键的一步：怎么把检索到的context，喂给LLM。一个常见的错误模板是：
你是一个助手。请根据以下信息回答问题。 <context> {context} </context> 问题: {question}这会让LLM无条件相信context里的所有内容。正确的做法是，在prompt里植入“质疑精神”：
你是一个严谨的{domain}专家。请严格依据以下提供的信息回答问题。如果信息中没有相关内容，请明确回答“未找到相关信息”，不要编造。 <context> {context} </context> 问题: {question}这个strictly based on和do not fabricate，是RAG可信度的生命线。我在一个医疗问答项目里，强制加入这句话后，幻觉率（Hallucination Rate）从23%降到了4%。这比任何模型微调都有效。
3.4 Agent：从“玩具Demo”到“生产级智能体”的七道关卡
写一个能调用serpapi搜索的Agent Demo，5分钟就能搞定。但让它在生产环境里，7x24小时稳定、准确、可审计地运行，需要跨越七道关卡。这是我踩过最多坑的地方。
关卡一：工具（Tool）的健壮性封装@tool装饰器生成的Tool，默认把所有异常都吞掉了，只返回一个错误字符串。这在生产环境是灾难。必须重写_run方法，做精细化错误处理：
from langchain_core.tools import BaseTool from typing import Optional, Dict, Any class RobustSearchTool(BaseTool): name = "web_search" description = "Useful for searching the web for current information." def _run(self, query: str) -> str: try: # 调用真实API results = self._search_api(query) return self._format_results(results) except requests.Timeout: return "搜索超时，请稍后重试。" except requests.ConnectionError: return "网络连接失败，请检查网络。" except Exception as e: # 记录详细错误日志 logger.error(f"SearchTool error for query '{query}': {str(e)}") return "搜索服务暂时不可用。" def _search_api(self, query: str) -> Dict: # 实际的API调用 pass关卡二：Agent策略（Policy）的选择ReAct是最常用的，但它不是万能的。ReAct适合“目标明确、步骤清晰”的任务，比如“查订单状态”。但对于“帮我写一封道歉信”，Plan-and-Execute更合适，因为它会先规划大纲，再分步撰写。Self-Ask则适合需要多跳推理的问题，比如“爱因斯坦在哪一年获得诺贝尔奖？他获奖的研究领域是什么？该领域现在的前沿进展有哪些？”。选错策略，Agent会陷入无限循环。
关卡三：工具调用的“沙箱”机制
绝不能让Agent随意调用任意工具。必须建立白名单和权限控制。我在一个企业内部知识库Agent里，用Tool的args_schema做参数校验，用name做白名单过滤：
# 定义一个只允许查询内部知识库的工具 class InternalKbSearchTool(BaseTool): name = "internal_kb_search" description = "Search the company's internal knowledge base." # args_schema 确保只能传入合法的category args_schema = create_model( "InternalKbSearchArgs", category=(Literal["policy", "procedure", "faq"], FieldInfo(description="知识库分类")), query=(str, FieldInfo(description="搜索关键词")) ) # 在AgentExecutor初始化时，只传入白名单内的tools agent_executor = AgentExecutor( agent=agent, tools=[InternalKbSearchTool(), ...], # 不放外部搜索工具 verbose=True )关卡四：执行流的“熔断”与“降级”
Agent执行必须有超时和重试机制。LangChain的AgentExecutor支持max_iterations和max_execution_time参数。我设置max_iterations=5，max_execution_time=30。一旦超时，AgentExecutor会抛出AgentExecutionException，这时应该触发降级逻辑，比如返回一个预设的FAQ答案，而不是让用户干等。
关卡五：历史消息的“瘦身”与“脱敏”chat_history会越积越多，最终撑爆token限制。ConversationBufferWindowMemory可以限制窗口大小，但更聪明的是ConversationSummaryBufferMemory，它用一个LLM把历史对话总结成一句话，既保留了关键信息，又节省了token。同时，必须做脱敏：history里可能包含用户手机号、身份证号，get_session_history函数在返回前，必须用正则表达式把这些敏感信息替换成[REDACTED]。
关卡六：可观测性的“全链路追踪”callbacks是你的朋友。我创建了一个ProductionCallbackHandler，它在on_agent_action时，记录tool_name、tool_input、start_time；在on_agent_finish时，记录return_values、end_time、duration；在on_tool_error时，记录error_type、error_message。所有这些数据，都打上trace_id，发送到ELK。这样，当一个用户投诉“Agent回答错了”，我只要查trace_id，就能看到整个执行链路，精准定位是哪个工具返回了错误数据，还是哪个LLM在总结时出了错。
关卡七：人机协同的“接管”入口
再智能的Agent，也会遇到无法处理的case。必须设计一个优雅的“人工接管”机制。我在AgentExecutor的handle_parsing_errors参数里，写了一个函数：当LLM返回的tool_call格式错误（比如JSON解析失败）时，不报错，而是生成一个{"tool": "human_handoff", "tool_input": "用户问题：{input}，当前上下文：{history}"}。这个human_handoff工具，会把整个会话快照，推送到客服工单系统，并自动分配给值班工程师。工程师处理完，把答案回传，Agent就能无缝续上。
4. LangChain 实战全流程：从零搭建一个“政策解读助手”
4.1 需求分析与技术选型：为什么是LangChain，而不是自己写？
客户的需求很明确：他们是一家大型国企的法务部，每天要处理数百份来自国务院、发改委、工信部等部委发布的政策文件（PDF格式）。员工需要快速了解：“这份文件对我司XX业务有什么影响？关键条款是什么？有没有配套实施细则？”。传统做法是，法务专员逐字阅读，手动摘录，效率低、易遗漏、难追溯。
我们评估了几个方案：
- 纯LLM方案（如直接用ChatGLM3-6B）：成本高（GPU资源）、响应慢（单次推理>5秒）、无法保证事实准确性（会幻觉编造条款）。
- 搜索引擎+摘要API方案：需要自己搭ES集群、写爬虫、做PDF解析，工程量巨大，且无法理解政策间的关联。
- LangChain RAG方案：利用其成熟的
DocumentLoader（支持PDF）、TextSplitter（针对法律文本优化）、VectorStore（本地Milvus，免公网）、Retriever（混合检索）、ChatModel（本地Qwen2-7B）和Agent（政策解读专家角色），可以在2周内交付一个MVP。
最终选择LangChain，核心原因有三点：1）开箱即用的PDF解析能力，PyPDFLoader能正确处理扫描版PDF的OCR（需配合pymupdf）；2）RAG的“可信生成”范式，确保所有回答都基于原文，杜绝幻觉；3）Agent的“角色扮演”能力，让LLM始终以“资深政策顾问”的身份回答，语气专业、结构清晰。
4.2 环境准备与依赖安装：避开那些“看似正常”的坑
LangChain的版本兼容性，是新手最大的噩梦。langchain==0.1.0和langchain==0.2.0的API是断裂的。我们必须锁定版本。基于2024年的生态，我推荐：
# 创建干净的虚拟环境 python -m venv policy_env source policy_env/bin/activate # Linux/Mac # policy_env\Scripts\activate # Windows # 安装核心依赖（注意版本！） pip install langchain==0.2.11 \ langchain-community==0.2.9 \ langchain-core==0.2.26 \ langchain-text-splitters==0.2.2 \ pypdf==4.2.0 \ pymupdf==1.24.5 \ milvus==2.4.7 \ sentence-transformers==2.7.0 \ transformers==4.41.2 \ torch==2.3.0+cu121 -f https://download.pytorch.org/whl/torch_stable.html # 安装本地LLM运行时 pip install ollama # 启动ollama，并拉取模型 ollama run qwen2:7b关键避坑点：
- PyMuPDF vs PyPDF：
PyPDFLoader在处理扫描版PDF时，会静默失败，返回空文档。必须安装pymupdf，并在PyPDFLoader初始化时指定extract_images=True，它会自动调用MuPDF进行OCR。 - Milvus版本：
milvus==2.4.x是当前最稳定的，milvus==2.5.x有已知的search性能退化Bug。安装时务必指定--no-deps，避免它自动升级pymilvus到不兼容版本。 - Sentence Transformers：
bge-m3模型需要sentence-transformers>=2.2.0，但<2.8.0，因为2.8.0移除了CrossEncoder的旧API。2.7.0是黄金版本。 - Ollama模型名：
qwen2:7b是Ollama官方仓库的模型名，不是Qwen2-7B-Instruct。用错名字，ollama run会报model not found。
4.3 数据处理与向量库构建：让政策文件“活”起来
政策文件不是普通文本，它有严格的结构：标题、发文机关、文号、正文、附件、落款。我们需要保留这种结构，以便LLM能理解“这是哪一级政府发的什么文件”。
from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Milvus from langchain_community.embeddings import HuggingFaceEmbeddings # 1. 加载PDF（支持扫描版） loader = PyPDFLoader("policies/2024-01-01_国务院_关于促进人工智能产业发展的若干意见.pdf") docs = loader.load() # docs 是一个 Document 列表 # 2. 结构化切分：按标题层级切分，保留元数据 def split_by_heading(documents): """按'一、''二、''（一）'等中文标题切分""" splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n一、", "\n\n二、", "\n\n（一）", "\n\n1.", "\n\n（1）", "\n\n"] ) all_chunks = [] for doc in documents: chunks = splitter.split_documents([doc]) for chunk in chunks: # 将标题作为元数据，方便后续检索过滤 if "一、" in chunk.page_content[:20]: chunk.metadata["section"] = "总则" elif "二、" in chunk.page_content[:20]: chunk.metadata["section"] = "主要任务" # ... 其他逻辑 all_chunks.extend(chunks) return all_chunks structured_docs = split_by_heading(docs) # 3. 嵌入与入库 embeddings = HuggingFaceEmbeddings( model_name="BAAI/bge-m3", model_kwargs={'device': 'cuda'}, # 使用GPU加速 encode_kwargs={'normalize_embeddings': True} ) # 连接到本地Milvus vectorstore = Milvus( embedding_function=embeddings, connection_args={"host": "localhost", "port": "19530"}, collection_name="policy_db", drop_old=True # 首次运行时清空旧库 ) # 批量添加，提升速度 vectorstore.add_documents(structured_docs)实操心得：
- 元数据是灵魂：
structured_docs[0].metadata里，除了source（文件路径），我还加入了publish_date、issuing_authority（发文机关）、document_type（通知/意见/办法）。这些元数据，在Retriever里可以用filter参数精确筛选。比如，只检索“2024年以后”、“工信部发布”的“管理办法”。
