LlamaIndex 安装指南：4 步从安装到跑通第一个 RAG 查询

LlamaIndex 安装指南4 步从安装到跑通第一个 RAG 查询【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexLlamaIndex 是一个用 Python 编写的开源数据框架负责把你的私有文档、数据库、API 数据接入大语言模型完成索引构建、向量检索和带上下文的答案生成。本文覆盖环境准备、最小安装、云端与本地模型两种配置方式、验证代码和常见报错处理目标是在十几分钟内让一个可查询的 RAG 示例跑起来。一句话定位它解决什么问题LlamaIndex 把 LLM 应用开发中最耗时的部分封装成了标准组件数据连接器负责读取 PDF、网页、SQL 表等任意格式的数据索引和检索层负责让这些数据可被模型引用查询引擎负责把检索到的上下文喂给 LLM 生成答案。它适合两类人一是想快速搭 RAG 或文档问答系统的开发者高层 API 几行代码就能完成读文档—建索引—提问的闭环二是需要深度定制检索、分块、重排逻辑的进阶用户底层组件都可以替换。整个生态是核心包 数百个集成包的组合方式核心逻辑在llama-index-core第三方模型和存储以llama-index-llms-*、llama-index-vector-stores-*这样的独立包形式按需安装。环境检查与前置准备系统层面要求不高Python 版本需 3.10 及以上llama-index-core的requires-python声明为3.10,4.0可用python --version确认包管理器用 pip 即可建议先建一个虚拟环境隔离依赖python -m venv .venv source .venv/bin/activate网络需要能访问 PyPI如果你打算本地推理还需提前装好 Ollama 并ollama pull一个模型API Key 方面分两种情况。走云端 OpenAI 路线需要提前在 OpenAI 平台创建 API Key之后用环境变量注入即可走本地模型路线则不需要任何外部 Key。后文会按这两个场景分别展开受限网络环境的处理方式也会单列一节。最小安装一条命令跑通最快的路径是安装 starter 包pip install llama-index # 自动带上 core、OpenAI LLM/嵌入、文件读取器四件套这个包等于llama-index-corellama-index-llms-openaillama-index-embeddings-openaillama-index-readers-file对先用默认配置跑起来的场景刚好够用。安装完立即验证导入是否成功python -c from llama_index.core import VectorStoreIndex, Settings; print(ok)打印ok就说明核心组件加载正常。这里不装任何可选依赖避免版本冲突。按场景配置模型与存储包名和导入路径是一一对应的记牢这一点后面选集成包会省很多事pip install llama-index-llms-ollama对应的就是from llama_index.llms.ollama import Ollama。场景一调用 OpenAI 云端 API适合没有 GPU、想最快看到效果的情况。starter 包已经包含 OpenAI 集成只需设置密钥export OPENAI_API_KEY你的密钥 # Linux/macOSWindows 用 set OPENAI_API_KEY代码里不需要显式实例化 LLMSettings会用默认的 OpenAI 模型。注意新项目中嵌入模型建议显式指定较新的text-embedding-3-small默认的text-embedding-ada-002已被官方标记为旧选择。场景二使用 Ollama 本地模型适合数据不能出内网、或不想按 token 付费的情况。先安装并拉取模型pip install llama-index-llms-ollama llama-index-embeddings-huggingface ollama pull llama3.1然后在代码里通过Settings全局指定三个组件from llama_index.core import Settings from llama_index.llms.ollama import Ollama from llama_index.embeddings.huggingface import HuggingFaceEmbedding Settings.llm Ollama(modelllama3.1, request_timeout360.0, context_window8000) Settings.embed_model HuggingFaceEmbedding(model_nameBAAI/bge-base-en-v1.5)适用判断本地路线要求机器至少 32GB 内存跑 8B 级模型request_timeout要给到 360 秒首次推理会明显慢于云端 API如果你没有大内存机器且只是验证思路直接选场景一。场景三企业内网与受限网络LlamaIndex 有一个对离线环境很友好的设计llama-index-core内置了 NLTK 词库和 tiktoken 编码文件的缓存位于包内_static目录首次运行分词时不会再去下载语料这在磁盘权限受限或无外网的机器上能少踩一个大坑。依赖安装阶段如果走不了官方源可以配置 pip 内部镜像pip install llama-index --index-url 内部镜像地址验证与首次调用下面这段代码是完整的最小 RAG读目录、建向量索引、发一次查询共 6 行核心逻辑from llama_index.core import VectorStoreIndex, SimpleDirectoryReader documents SimpleDirectoryReader(./data).load_data() index VectorStoreIndex.from_documents(documents) query_engine index.as_query_engine() print(query_engine.query(文档的核心主题是什么))./data里放几份纯文本或 Markdown 文件即可。预期行为构建索引时终端会显示分块和嵌入的进度条随后query返回一段基于文档内容的自然语言回答。云端 API 场景下首次查询通常 5 到 15 秒本地模型首次调用要等模型加载等待一两分钟属于正常。如果返回内容明显脱离文档优先检查./data是否真的有可解析的文本。踩坑清单报OPENAI_API_KEY is not set或 401 错误。原因是环境变量没注入到运行 Python 的 shell 里。用echo $OPENAI_API_KEY确认注意从 GUI 或 IDE 启动的进程不会继承终端的export。分词阶段报网络下载失败。如果你装的是旧版本 core 且网络不通NLTK 语料拉取会失败。升级到新版 core 即可它已内置_static缓存无需联网。本地模型首次调用超时或卡住。8B 模型首 token 延迟高Ollama客户端默认的超时会先于模型返回触发报错。把request_timeout调到 360并用context_window手动限制上下文长度以控制内存。重新加载持久化索引后检索质量突然变差。原因是加载时使用的嵌入模型和建索引时不一致向量空间对不上。文档里对此有明确警告load_index_from_storage时必须传回同一个embed_model。pip 安装时出现依赖版本冲突。通常是项目里已有的openai或其他科学计算库版本与集成包要求打架。把 LlamaIndex 的依赖隔离到独立虚拟环境并用pip freeze固定通过测试的版本组合。上生产前的检查项锁定依赖版本用pip freeze或uv.lock固化环境core 与集成包同属一个生态混用不同大版本容易出兼容问题容器化部署把 venv 打进 Docker 镜像镜像内预置_static缓存目录避免运行时再触发热路径写入持久化索引用index.storage_context.persist(storage)落盘服务重启时通过load_index_from_storage恢复省去重复建索引密钥管理API Key 只走环境变量或密钥管理服务定期轮换代码仓库里不留明文加可观测性接入集成包中的 callback 体系如仓库llama-index-integrations/callbacks/下的 Arize Phoenix、Langfuse 等把每次检索的召回片段和生成耗时记录下来限制资源本地推理务必设置context_window并为query的并发做限流防止显存/内存被打满后续学习路径想理解索引类型、检索器和查询引擎之间的关系从仓库docs/src/content/docs/framework/understanding/目录读起它按组件拆开讲各种配置改法换分块、换向量库、换响应模式、流式输出参考docs/src/content/docs/framework/getting_started/faq.mdx按问题场景组织查起来比教程快可运行的完整示例在docs/examples/下其中llm/、vector_stores/、agent/三个子目录覆盖了模型替换、存储后端和多智能体三类最常见的进阶需求组件级 API 文档见docs/api_reference/写自定义集成前建议先读一遍对应子模块的接口定义跑通第一个查询只是入口真正拉开差距的是分块策略和检索质量这两个方向都值得花一个下午去翻对应的 module guide。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考