LlamaIndex 已经成为用 Python 构建检索增强生成（RAG）管道的事实标准框架。但它的文档和示例几乎总是假设你在用 OpenAI。如果你想换上一个更具成本效益的模型——比如智谱 AI 的 GLM 5.2（模型名：glm-4-plus）——前路并不明朗。
这篇教程精确展示如何把 GLM 5.2 接入 LlamaIndex：从基础文档问答一路到带工具调用的 ReAct 智能体。你会写出真实的 Python 代码、理解每段代码的作用，并最终得到一个运行成本显著低于等效 GPT-4o 方案的可工作 RAG 管道。
痛点：LlamaIndex 文档假设你用 OpenAI
如果你尝试过在 LlamaIndex 里用非 OpenAI 模型，你懂那种摩擦。文档里是 OpenAI()，示例里是 OpenAI()，连报错信息都引用 OpenAI 的 key。不熟悉 GLM API 的开发者会以为它需要特殊的集成包或自定义 LLM 包装器。
并不需要。GLM 5.2 在 https://open.bigmodel.cn/api/paas/v4/ 暴露了 OpenAI 兼容的 REST API。这意味着你可以直接使用 llama-index-llms-openai——与 GPT-4o 用的是同一个包——只需把它指向智谱的端点。没有新抽象、没有猴子补丁、没有自定义 provider 类。
为什么 RAG 管道要选 GLM 5.2
在深入代码之前，先说说为什么 GLM 5.2 值得为生产级 RAG 负载考虑。
成本。 以每百万输入 token $1.40、每百万输出 token $4.40（撰写本文时的智谱 API 定价），同样的 LlamaIndex 管道上 GLM 5.2 比 GPT-4o 便宜 3–4 倍。如果你的管道每天处理数千份文档，这个差距会快速复利。
上下文窗口。 GLM 5.2 支持 1,048,576 token 的上下文——整整一百万 token。对 RAG 来说这很重要：你可以把整个代码库、法律文件或论文集塞进单个上下文直接查询，不必采用可能丢失相关段落的激进分块策略。
基准质量。 GLM 5.2 在 GPQA Diamond 上得分 89%、SWE-bench Pro 上 62.1%，稳居推理和编码任务的第一梯队。它的 Artificial Analysis Quality Index 为 51，基准硬件上每秒跑 158 token——对交互式问答足够快。
MIT 许可。 权重以 MIT 许可发布在 HuggingFace 上，这对那些对专有模型 API 有限制的组织很重要。需要时你可以在自己的基础设施上运行模型，或者图省事用智谱 API。
智谱还提供配套模型来凑齐整条管道：embedding-3（2048 维嵌入）和 embedding-2（1024 维）用于向量索引，GLM-4-Long 针对长文档任务优化，GLM-4-Air 用于轻量/高吞吐负载。你可以按自己的延迟和成本约束自由搭配。
如果想在写代码前先探索 GLM 5.2 的能力，glm5.app 提供了 playground 和模型概览，方便你熟悉模型行为。
前置条件
安装所需包：
pip install llama-index-core llama-index-llms-openai llama-index-embeddings-openai
把你的智谱 API key 设置为环境变量：
export ZHIPU_API_KEY="your-zhipu-api-key-here"
你可以在 open.bigmodel.cn 获取智谱 API key。快速了解 GLM 5.2 的 API 参数与可用端点，请看 GLM 5.2 API 指南。
第 1 步：把 GLM 5.2 配置为你的 LlamaIndex LLM
关键洞察是：llama-index-llms-openai 的 OpenAI 类接受 api_base 和 api_key 覆盖参数。把它们指向智谱的端点就完事了：
import os
from llama_index.llms.openai import OpenAI
llm = OpenAI(
model="glm-4-plus",
api_base="https://open.bigmodel.cn/api/paas/v4/",
api_key=os.environ["ZHIPU_API_KEY"],
temperature=0.1,
max_tokens=2048,
)
# Quick sanity check
response = llm.complete("What is retrieval-augmented generation in one sentence?")
print(response.text)
如果响应正常打印出来，你的连接就通了。从这里开始，每个接受 llm 参数的 LlamaIndex 组件都会使用 GLM 5.2。
第 2 步：配置 GLM 嵌入
完整 RAG 管道还需要嵌入。智谱的 embedding-3 模型（2048 维）是质量最高的选项；embedding-2（1024 维）更快更便宜。两者都通过同一个 OpenAI 兼容端点访问：
from llama_index.embeddings.openai import OpenAIEmbedding
embed_model = OpenAIEmbedding(
model="embedding-3",
api_base="https://open.bigmodel.cn/api/paas/v4/",
api_key=os.environ["ZHIPU_API_KEY"],
embed_batch_size=10,
)
把这些设为全局默认值，让每个 LlamaIndex 组件自动使用：
from llama_index.core import Settings
Settings.llm = llm
Settings.embed_model = embed_model
第 3 步：构建文档问答管道
现在加载文档、构建向量索引并运行查询。创建一个叫 ./docs 的文件夹，把你想查询的任何 PDF、.txt 或 Markdown 文件放进去。
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
# Load documents from a local folder
documents = SimpleDirectoryReader("./docs").load_data()
print(f"Loaded {len(documents)} document chunks")
# Build a vector index (embeddings are computed here)
index = VectorStoreIndex.from_documents(documents)
# Create a query engine
query_engine = index.as_query_engine(
similarity_top_k=5, # retrieve top-5 chunks
response_mode="tree_summarize",
)
# Ask a question
response = query_engine.query(
"What are the main conclusions of the research?"
)
print(response.response)
print("\nSources:")
for node in response.source_nodes:
print(f" - {node.metadata.get('file_name', 'unknown')} (score: {node.score:.3f})")
SimpleDirectoryReader 负责 PDF 解析、文本切分和元数据提取。VectorStoreIndex 默认把嵌入存在内存里——生产环境请换成 Chroma 或 Weaviate 等持久化向量库，使用它们各自的 LlamaIndex 集成。
第 4 步：持久化索引
为大型文档集计算嵌入既慢又花钱。把索引持久化到磁盘，后续运行直接加载：
from llama_index.core import StorageContext, load_index_from_storage
# Save
index.storage_context.persist(persist_dir="./index_store")
# Load on next run
storage_context = StorageContext.from_defaults(persist_dir="./index_store")
index = load_index_from_storage(storage_context)
query_engine = index.as_query_engine(similarity_top_k=5)
第 5 步：复杂问题的子问题查询引擎
当一个问题跨越多个主题时，单次检索往往错过相关上下文。LlamaIndex 的 SubQuestionQueryEngine 把问题拆成子问题、为每个子问题检索上下文、再综合出最终答案——全部使用你配置的 LLM（本例中即 GLM 5.2）：
from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.tools import QueryEngineTool, ToolMetadata
# Wrap the base query engine as a tool
tools = [
QueryEngineTool(
query_engine=query_engine,
metadata=ToolMetadata(
name="research_docs",
description="Answers questions about the research documents",
),
)
]
sub_question_engine = SubQuestionQueryEngine.from_defaults(
query_engine_tools=tools,
use_async=True,
)
response = sub_question_engine.query(
"Compare the methodology and conclusions across the different papers"
)
print(response.response)
GLM 5.2 的 1M token 上下文意味着它可以在多个检索块之间综合答案而不会触顶长度限制——对比上下文窗口更小的模型，这是实打实的优势。
第 6 步：带工具调用的 ReAct 智能体
GLM 5.2 支持函数调用，所以 LlamaIndex 的 ReActAgent 开箱即用。下面这个智能体既能查询你的文档索引，也能执行网络搜索（或任何你添加的其他工具）：
from llama_index.core.agent import ReActAgent
from llama_index.core.tools import FunctionTool
def get_current_date() -> str:
"""Returns today's date."""
from datetime import date
return str(date.today())
date_tool = FunctionTool.from_defaults(fn=get_current_date)
doc_tool = QueryEngineTool(
query_engine=query_engine,
metadata=ToolMetadata(
name="document_search",
description=(
"Search the loaded research documents for factual information. "
"Input should be a natural language question."
),
),
)
agent = ReActAgent.from_tools(
tools=[doc_tool, date_tool],
llm=llm,
verbose=True,
max_iterations=10,
)
response = agent.chat(
"What does the research say about long-term outcomes, "
"and how recent is this information relative to today?"
)
print(response.response)
verbose=True 标志会打印每一步推理，让你观察 GLM 5.2 如何决定调用哪个工具、何时调用。GLM 5.2 的工具使用准确度足够强，很少误调工具或做无谓循环。
想先把 GLM 5.2 直接试一遍再接入管道？在 glm5.app 上探索这个模型——它可以让你测试提示词、对比输出，在投入集成工作之前摸清模型行为。
为每个管道环节选择正确的 GLM 模型
智谱提供多个可以混入 LlamaIndex 方案的模型。这里是一份实用映射：
| 环节 | 推荐模型 | 备注 |
|---|---|---|
| 问答（主 LLM） | glm-4-plus（GLM 5.2） | 质量最佳，1M 上下文 |
| 文档嵌入 | embedding-3 | 2048 维，准确度最高 |
| 快速嵌入 | embedding-2 | 1024 维，成本更低 |
| 长文档总结 | GLM-4-Long | 针对长输入优化 |
| 高吞吐任务 | GLM-4-Air | $0.0001/1K tokens |
对大多数 RAG 管道，推荐用 glm-4-plus 做综合、embedding-3 做检索作为起点。
流式响应
对交互式应用，开启流式让界面逐 token 更新：
streaming_engine = index.as_query_engine(streaming=True)
response = streaming_engine.query("Summarize the key findings")
response.print_response_stream()
GLM 5.2 的 API 原生支持流式，OpenAI 兼容适配器会透明地处理 SSE 解析。
故障排查
AuthenticationError： 仔细确认 ZHIPU_API_KEY 已设置，并且你把它作为 api_key= 传入（不要依赖 OPENAI_API_KEY）。api_base 必须是 https://open.bigmodel.cn/api/paas/v4/。
嵌入维度不匹配： 如果你在 embedding-2（1024 维）和 embedding-3（2048 维）之间切换，删除已持久化的索引并重建——存储的向量必须与当前模型的维度一致。
首次查询慢： 第一次查询会触发所有已加载文档的嵌入计算。之后对持久化索引的查询都很快。
model not found 错误： 确认模型名精确为 glm-4-plus。GLM 5.2 是营销名；API 模型标识符是 glm-4-plus。
总结
把 GLM 5.2 接入 LlamaIndex 不需要自定义 LLM 类或特殊 provider 包。https://open.bigmodel.cn/api/paas/v4/ 的 OpenAI 兼容端点让你直接使用 llama-index-llms-openai，model="glm-4-plus" 是唯一的模型相关设置。从那里开始，LlamaIndex 的全套功能——向量索引、子问题引擎、ReAct 智能体、流式——无需修改即可工作。
实际回报：用 GLM 5.2 的 RAG 管道比等效 GPT-4o 方案便宜 3–4 倍，提供 1M token 上下文窗口容纳大型文档集，并且基准质量足以支撑生产负载。
Sources
- Zhipu AI GLM-4-Plus API documentation: https://open.bigmodel.cn/dev/api
- LlamaIndex OpenAI LLM integration: https://docs.llamaindex.ai/en/stable/examples/llm/openai/
- LlamaIndex embeddings: https://docs.llamaindex.ai/en/stable/module_guides/models/embeddings/
- LlamaIndex ReActAgent: https://docs.llamaindex.ai/en/stable/examples/agent/react_agent/
- Artificial Analysis GLM-4-Plus benchmark: https://artificialanalysis.ai/models/glm-4-plus
- GLM-4-Plus on HuggingFace (MIT license): https://huggingface.co/THUDM/glm-4
