Gemini 3.5 Pro实战：LangChain与LlamaIndex框架深度对比与选型指南

1. 项目缘起：当Gemini 3.5 Pro遇上两大编排框架

最近在折腾大模型应用开发，发现一个挺有意思的现象：身边不少朋友，无论是想快速做个RAG问答机器人，还是想构建一个复杂的多智能体工作流，第一反应都是去翻LangChain的文档。这当然没错，LangChain作为这个领域的“开山鼻祖”，生态和社区确实强大。但与此同时，另一个框架LlamaIndex也在快速崛起，尤其在检索增强生成（RAG）这个细分赛道上，口碑相当不错。恰好，Google的Gemini 3.5 Pro模型（尤其是Flash版本）以其出色的性价比和性能，成为了许多开发者在构建生产级应用时的热门选择。

这就引出了一个很实际的问题：当我想用Gemini 3.5 Pro作为核心大模型时，到底该选LangChain还是LlamaIndex来搭建我的应用骨架？这两个框架在接入Gemini时的体验有何不同？是选生态更广的“瑞士军刀”，还是选在特定领域更专精的“手术刀”？为了搞清楚这些，我决定亲手把Gemini 3.5 Pro分别接入这两个框架，从环境配置、基础调用、到高级功能（如RAG、智能体）做一个全面的对比实测。这篇文章就是这次探索的记录和总结，希望能给面临同样选择困境的你，提供一个清晰的参考。

2. 环境准备与初步接入：第一印象的差异

动手之前，先得把台子搭起来。这一步看似简单，但两个框架的设计哲学已经初现端倪。

2.1 依赖安装与API密钥配置

无论是LangChain还是LlamaIndex，使用Gemini的前提都是拥有Google AI Studio的API密钥。获取方式很简单，去Google AI Studio创建一个密钥即可。接下来就是安装各自的Python包。

对于LangChain，你需要安装的是langchain核心包和Google的集成包：

pip install langchain langchain-google-genai

对于LlamaIndex，对应的包是：

pip install llama-index llama-index-llms-google

这里第一个小差异就出现了：包名的命名逻辑。LangChain遵循的是langchain-<provider>的模式，而LlamaIndex（特别是新版本）倾向于使用llama-index-<integration-type>-<provider>的模式，比如llama-index-llms-google表示这是用于LLM集成的Google包。LlamaIndex的命名更强调模块的功能性（llms, embeddings, agents等），对于新手来说，可能更直观一些。

配置API密钥的方式两者类似，都可以通过环境变量设置。我个人的习惯是在代码中显式传入，方便管理不同项目的密钥：

# LangChain 方式 from langchain_google_genai import ChatGoogleGenerativeAI llm_langchain = ChatGoogleGenerativeAI(model="gemini-1.5-flash-latest", google_api_key="YOUR_API_KEY") # LlamaIndex 方式 from llama_index.llms.google import Gemini llm_llama = Gemini(model="models/gemini-1.5-flash-latest", api_key="YOUR_API_KEY")

注意模型名称的细微差别。LangChain的ChatGoogleGenerativeAI通常接受像gemini-1.5-pro-latest或gemini-1.5-flash-latest这样的参数。而LlamaIndex的Gemini类，其model参数需要的是完整的模型资源名，即models/gemini-1.5-flash-latest。如果你直接从Google AI Studio的代码片段复制，它给的就是后一种格式，所以LlamaIndex的写法可能和官方文档更一致。

2.2 首次对话：基础调用体验对比

配置好之后，我们来发起第一次对话，看看基本调用有何不同。

LangChain的方式：

from langchain_core.messages import HumanMessage messages = [HumanMessage(content="你好，请用一句话介绍你自己。")] response = llm_langchain.invoke(messages) print(response.content)

LangChain的消息传递遵循其BaseMessage体系（如HumanMessage,AIMessage,SystemMessage），这在其生态内是统一的。调用使用invoke方法，返回的是一个AIMessage对象，你需要通过.content属性获取文本内容。这种方式结构清晰，但稍微有点“重”。

LlamaIndex的方式：

response = llm_llama.complete("你好，请用一句话介绍你自己。") print(response.text)

LlamaIndex的基础LLM调用更直接。complete方法接受一个字符串，直接返回一个CompletionResponse对象，通过.text获取结果。对于简单的补全任务，这种写法更简洁。当然，LlamaIndex也支持消息列表格式，但基础调用门槛更低。

第一印象小结：

• LangChain：感觉更像一个企业级框架，从消息对象到调用方法，都体现着标准化和规范性。它假设你会构建复杂的、有状态的多轮对话链。
• LlamaIndex：在基础调用上显得更轻量、更“Pythonic”。它似乎更倾向于让你快速上手，把精力集中在“检索”和“生成”的核心逻辑上，而不是框架本身的抽象上。

3. 核心能力深入：RAG实现路径的异同

RAG是当前大模型应用最核心的场景之一，也是两个框架重点发力的领域。我们来对比一下用它们构建一个经典“文档问答”系统的流程。

假设我们有一个PDF文档“人工智能发展简史.pdf”，我们想基于它来回答问题。

3.1 LangChain的RAG流水线

在LangChain中，构建一个RAG系统通常意味着组装多个组件，形成一个“链”。其典型流程是：文档加载 -> 文本分割 -> 向量化存储 -> 检索 -> 生成。

from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_google_genai import GoogleGenerativeAIEmbeddings from langchain_chroma import Chroma from langchain.chains import RetrievalQA # 1. 加载与分割文档 loader = PyPDFLoader("人工智能发展简史.pdf") documents = loader.load() text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200) splits = text_splitter.split_documents(documents) # 2. 创建向量存储（使用Gemini的嵌入模型） embeddings = GoogleGenerativeAIEmbeddings(model="models/embedding-001", google_api_key=api_key) vectorstore = Chroma.from_documents(documents=splits, embedding=embeddings) # 3. 创建检索器 retriever = vectorstore.as_retriever(search_kwargs={"k": 4}) # 4. 创建问答链 qa_chain = RetrievalQA.from_chain_type( llm=llm_langchain, chain_type="stuff", # 还有 map_reduce, refine, map_rerank 等 retriever=retriever, return_source_documents=True # 返回参考来源 ) # 5. 提问 result = qa_chain.invoke({"query": "深度学习的三次浪潮分别是什么？"}) print("答案：", result["result"]) print("来源文档：", result["source_documents"])

LangChain RAG特点分析：

1. 模块化与灵活性：每一步都是独立的、可替换的组件。你可以轻松将PyPDFLoader换成UnstructuredFileLoader，将Chroma换成Pinecone，将RecursiveCharacterTextSplitter换成TokenTextSplitter。这种设计赋予了极大的灵活性。
2. “链”的抽象：RetrievalQA是一个预定义的链。它封装了“检索-组合提示-调用LLM”的流程。chain_type参数让你可以选择不同的文档处理策略（如stuff一次性传入，map_reduce先分头总结再汇总），这是LangChain非常强大的一个概念。
3. 配置稍显繁琐：你需要显式地管理文档加载、分割、向量化、存储、检索多个步骤，对于简单应用来说，代码量会多一些。

3.2 LlamaIndex的RAG流水线

LlamaIndex自称是“数据框架”，其设计核心就是围绕数据的索引和检索。它的RAG流程更倾向于“一站式”解决。

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.embeddings.google import GeminiEmbedding from llama_index.core import Settings # 1. 全局设置（注入LLM和Embedding模型） Settings.llm = llm_llama Settings.embed_model = GeminiEmbedding(model_name="models/embedding-001", api_key=api_key) # 2. 加载文档并创建索引（一步到位） documents = SimpleDirectoryReader(input_files=["人工智能发展简史.pdf"]).load_data() index = VectorStoreIndex.from_documents(documents) # 3. 创建查询引擎并提问 query_engine = index.as_query_engine(similarity_top_k=4, response_mode="compact") # compact 对应 LangChain 的 stuff response = query_engine.query("深度学习的三次浪潮分别是什么？") print("答案：", response.response) print("来源节点：", response.source_nodes)

LlamaIndex RAG特点分析：

1. 高集成度与简洁性：VectorStoreIndex.from_documents这一行代码背后，默认帮你完成了文本分割、向量化、存储索引的所有工作。对于标准流程，代码极其简洁。
2. 全局设置模式：通过Settings类全局配置LLM和Embedding模型，避免了在链的每个环节传递参数，让代码更干净。
3. “索引”和“查询引擎”为核心抽象：Index是你的知识库核心，QueryEngine是检索和生成的执行器。这种抽象非常直观，符合“提问-答案”的心智模型。
4. 默认配置合理：它内置了合理的文本分割器、默认使用内存向量存储（可轻松切换），开箱即用体验很好。但高级定制可能需要深入其节点、后处理器等概念。

3.3 RAG对比与选型思考

通过上面的代码，可以清晰地感受到两者的风格差异：

• LangChain像乐高积木。它给你提供了最全、最标准的零件（组件），并教你如何用“链”把它们拼装起来。你想拼成城堡还是飞船，有很高的自由度，但需要自己设计组装图。适合需要高度定制化、或流程非常复杂的场景。
• LlamaIndex像一套高级家具组装包。它针对“把文档变成问答系统”这个具体任务，已经把大部分板件和连接件预装好了，你只需要按照说明书（简单API）拧上最后几颗螺丝。它追求的是在特定场景下的最高效率和最佳实践。适合快速构建标准RAG应用。

一个重要的细节对比：检索结果的处理。在LangChain中，检索器返回的是Document对象列表。在LlamaIndex中，查询引擎返回的是Response对象，其中包含source_nodes。Node是LlamaIndex的核心数据单元，它包含了文本内容、元数据、嵌入向量以及与其他节点的关系。LlamaIndex对检索结果有更丰富的原生封装，比如节点评分、节点关系等，这对于实现高级RAG功能（如重排序、图检索）可能更有优势。

4. 智能体（Agent）开发：思维链与执行力的较量

智能体是大模型应用的另一个前沿。我们看看两者如何用Gemini 3.5 Pro创建一个能使用搜索工具和计算器的智能体。

4.1 LangChain智能体：清晰的思维链与工具使用

LangChain的智能体框架非常成熟，基于其AgentExecutor和Tool的抽象。

from langchain.agents import AgentExecutor, create_react_agent from langchain import hub from langchain.tools import Tool from langchain_community.utilities import SerpAPIWrapper from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper import math # 1. 定义工具 def calculator(input_str: str) -> str: """执行数学计算。输入是一个数学表达式字符串。""" try: # 安全评估，生产环境应用更严格的限制 return str(eval(input_str, {"__builtins__": None}, {"math": math})) except Exception as e: return f"计算错误：{e}" search = SerpAPIWrapper(serpapi_api_key="your_serpapi_key") # 需要注册SerpAPI wikipedia = WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()) tools = [ Tool(name="Search", func=search.run, description="当需要回答关于实时或最新事件的问题时使用此工具。"), Tool(name="Wikipedia", func=wikipedia.run, description="当需要查询广泛认可的事实性或历史性知识时使用此工具。"), Tool(name="Calculator", func=calculator, description="用于执行数学计算。输入应为一个清晰的数学表达式，如 '3 * 5 + 2'。"), ] # 2. 获取提示模板并创建智能体 prompt = hub.pull("hwchase17/react") # 使用经典的ReAct提示模板 agent = create_react_agent(llm_langchain, tools, prompt) # 3. 创建执行器并运行 agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True) result = agent_executor.invoke({"input": "截至2023年，世界上最高的建筑是什么？它的高度是多少米？用计算器把这个高度换算成英尺。"}) print(result["output"])

LangChain智能体特点：

1. 强大的提示工程支持：通过hub.pull可以直接使用社区共享的、经过优化的智能体提示模板（如ReAct）。你也可以轻松自定义。
2. 清晰的执行过程：设置verbose=True后，控制台会打印出完整的“思考-行动-观察”循环，这对于调试智能体的推理过程至关重要。
3. 丰富的工具生态：LangChain社区有海量的预构建工具（langchain-community），从搜索、数据库操作到代码执行，几乎涵盖所有场景。
4. AgentExecutor负责生命周期：它管理着智能体的迭代运行、错误处理、工具输出解析等复杂逻辑，开发者无需关注这些底层细节。

4.2 LlamaIndex智能体：更面向函数调用

LlamaIndex的智能体体系在新版本中有了很大变化，更紧密地与大模型的原生函数调用能力结合。

from llama_index.core.agent import FunctionCallingAgentWorker from llama_index.core.tools import FunctionTool from llama_index.tools.google import GoogleSearchToolSpec import requests # 1. 定义工具函数（以计算器为例，搜索工具用现成的） def calculator_tool(expression: str) -> str: """执行数学计算并返回结果。""" try: # 同样，生产环境需要更安全的方式 result = eval(expression, {"__builtins__": None}, {"math": math}) return f"计算结果为：{result}" except Exception as e: return f"计算失败：{e}" # 将函数包装成LlamaIndex的Tool calc_tool = FunctionTool.from_defaults(fn=calculator_tool) # 使用社区工具包（需要安装 llama-index-tools-google） search_tool_spec = GoogleSearchToolSpec(api_key="your_google_search_api_key", engine_id="your_engine_id") search_tools = search_tool_spec.to_tool_list() # 组合所有工具 all_tools = [calc_tool] + search_tools # 2. 创建智能体工作者并运行 agent_worker = FunctionCallingAgentWorker.from_tools( tools=all_tools, llm=llm_llama, verbose=True ) agent = agent_worker.as_agent() response = agent.chat("截至2023年，世界上最高的建筑是什么？它的高度是多少米？用计算器把这个高度换算成英尺。") print(str(response))

LlamaIndex智能体特点：

1. 拥抱函数调用：其FunctionCallingAgentWorker是围绕LLM的函数调用能力设计的。工具的定义直接是FunctionTool，与OpenAI的function calling格式类似，这可能让利用Gemini等模型的原生函数调用特性更直接。
2. 工具包（ToolSpec）：LlamaIndex提供了ToolSpec概念，将一组相关工具打包（如GoogleSearchToolSpec），可以方便地to_tool_list()转换成工具列表，管理起来更模块化。
3. 更简洁的API：agent.chat()的接口非常直观。执行过程的详细程度取决于verbose参数。
4. 生态在发展中：相比LangChain，LlamaIndex的预置工具生态目前规模小一些，但核心工具和与流行服务的集成正在快速完善。

智能体对比小结：

• LangChain的智能体体系更像一个通用的、与模型无关的规划与执行引擎。它的ReAct模式不依赖于模型必须有函数调用能力，适用性更广。其调试信息和社区资源是无价之宝。
• LlamaIndex的智能体（特别是新版）更倾向于利用现代LLM的原生函数调用能力，设计上可能更“现代”和高效。如果你的模型（如Gemini 1.5 Pro）支持良好的函数调用，这种集成方式可能更流畅。

5. 高级特性与实战避坑指南

经过基础功能的对比，我们再来看看一些高级特性和实际开发中必然会遇到的“坑”。

5.1 流式输出与异步支持

对于需要实时反馈的应用，流式输出至关重要。两者都提供了良好支持。

LangChain流式输出：

for chunk in llm_langchain.stream(messages): if chunk.content is not None: print(chunk.content, end="", flush=True)

LangChain的stream方法返回一个迭代器，每次产出的是一个ChatGenerationChunk或AIMessageChunk，需要判断.content属性。

LlamaIndex流式输出：

response_gen = llm_llama.stream_complete("讲一个简短的故事") for chunk in response_gen: if chunk.delta: print(chunk.delta, end="", flush=True)

LlamaIndex的stream_complete返回一个生成器，每个chunk有.delta属性直接是文本增量，使用起来更直接一些。

异步调用两者也都支持（ainvoke/astream,acomplete/astream_complete），在构建Web服务时非常有用。

5.2 参数调优与模型特性适配

Gemini模型有一些特定的参数和要求，两个框架的封装方式不同。

• 安全设置：Gemini API有安全等级设置（HARM_CATEGORY_*）。在LangChain中，可以在初始化ChatGoogleGenerativeAI时通过safety_settings参数传递一个字典。在LlamaIndex的Gemini类中，同样有safety_settings参数。建议在生产中根据场景调整，默认设置有时会过于严格，导致正常内容被拦截。
• 生成配置：如temperature,top_p,max_output_tokens等，两者都支持在调用时传入。
• 多模态处理：Gemini 1.5 Pro支持超长上下文和多模态。LangChain通过ChatGoogleGenerativeAI直接支持多模态消息列表。LlamaIndex则通过其MultiModalLLM抽象和专门的MultiModalEmbedding来处理图像等非文本数据，需要查看对应版本的文档来集成。

5.3 实战避坑经验分享

1. 版本兼容性地狱：这是最大的坑！langchain、langchain-google-genai、llama-index及其集成包的版本更新非常快，且常有破坏性变更。强烈建议使用虚拟环境，并在requirements.txt或pyproject.toml中严格锁定版本号。特别是LlamaIndex，其v0.10.x版本相比v0.9.x有巨大变化，API几乎完全不同。
2. API密钥与配额管理：Gemini API虽然免费额度慷慨，但频繁调用也可能触发限流。两个框架在错误处理上各有不同，建议在代码中主动添加重试逻辑和友好的错误提示。可以考虑使用tenacity库实现带指数退避的重试。
3. LangChain的“抽象泄漏”：LangChain的强大抽象有时会让你忘记底层发生了什么。例如，不同的chain_type在提示词构造和token消耗上差异巨大。使用map_reduce处理长文档时，务必注意它可能产生多次LLM调用，成本激增。始终要清楚你选择的组件和参数背后的实际行为。
4. LlamaIndex的默认配置陷阱：LlamaIndex的简洁性意味着它隐藏了许多默认选择。例如，默认的文本分割器（SentenceSplitter）的分块大小和重叠可能不适合你的文档类型。创建索引时默认使用的向量存储是内存式的，数据无法持久化。在投入生产前，务必逐一检查这些默认配置。
5. 错误信息模糊：两个框架在遇到底层API错误（如Gemini API返回429或500）时，抛出的错误信息有时层层包裹，难以直接定位。学会查看完整的错误堆栈，并尝试直接调用最底层的SDK（如google.generativeai）来隔离问题，是高效的调试手段。

6. 总结与个人选择建议

经过这一番深入的对比和实测，我对这两个框架在接入Gemini 3.5 Pro时的表现有了更立体的认识。它们不是简单的谁好谁坏，而是面向不同需求和阶段的工具。

如果你或你的团队属于以下情况，LangChain可能是更稳妥的选择：

• 项目复杂度高：你需要构建的不是简单的RAG，而是涉及多步骤工作流、复杂状态管理、多种工具协调的智能体系统。
• 需要最大程度的灵活性和控制力：你希望精细控制数据处理流水线的每一个环节，或者预计未来需要频繁更换底层组件（如向量数据库、嵌入模型）。
• 依赖强大的社区和生态：你希望使用大量现成的、经过社区验证的工具、链和集成方案，遇到问题时能快速找到答案和案例。
• 已有LangChain技术积累：团队已经熟悉了LangChain的抽象和模式，迁移成本高。

在以下场景中，LlamaIndex可能会让你感觉更顺手：

• 核心需求是快速构建高质量的RAG应用：你的首要目标是以最小代价，把一个文档问答系统跑起来并达到不错的效果。LlamaIndex在RAG上的“开箱即用”体验确实出色。
• 追求代码的简洁和可读性：你希望代码库更干净，抽象更直观（索引、查询引擎），让团队新人也能快速理解。
• 看重检索过程的高级功能：你对检索结果的重排序（re-ranking）、混合检索（Hybrid Search）、知识图谱检索等高级RAG特性有需求，LlamaIndex对这些功能的原生支持可能更直接。
• 项目处于原型验证或早期阶段：你需要快速验证想法，LlamaIndex能让你用更少的代码看到结果。

就我个人近期的项目而言，我发现自己正在采用一种“混合”或“按需选取”的策略。对于一个以复杂工作流和智能体为核心的项目，我选择了LangChain，因为它那套成熟的AgentExecutor和丰富的工具生态无可替代。而对于几个内部的知识库问答系统，我则转向了LlamaIndex，因为它让我在几分钟内就能搭建一个可用的原型，并且其默认的检索效果就相当不错，大大提升了开发效率。

最后，无论选择哪个框架，深入理解其核心抽象（LangChain的Chain/Agent，LlamaIndex的Index/QueryEngine），并密切关注其官方文档和版本更新，都是成功的关键。这两个框架都在飞速进化，今天的对比结论可能在几个月后就有变化。但把握住它们各自的设计哲学和优势场景，就能在面对具体问题时，做出最合适的技术选型。