LlamaIndex 安装教程：3 步搭好 LLM 应用开发环境（含本地模型方案）

LlamaIndex 安装教程：3 步搭好 LLM 应用开发环境（含本地模型方案）

【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

如果你的私有文档、数据库和 API 问不倒大模型，LlamaIndex 就是补齐这块的数据框架：它负责把数据读进来、切成索引、在提问时检索相关片段再喂给模型。整个 LlamaIndex 安装与配置流程并不长，核心只有三件事：装核心包、接模型服务、按命名规律加装组件。下面按"先选型、再动手、后验收"的顺序带你走完。

1️⃣ 动手前先选型：云端 API、本地模型还是源码

安装路线决定了你后面要装哪些包。先对照下表确定自己的路线：

• 云端 API（最常见）：模型走 OpenAI、Azure、Anthropic 等托管服务。只需一个 API 密钥，机器无 GPU 也能跑，适合绝大多数场景起步。
• 本地模型：模型跑在自己机器上（Ollama 或 HuggingFace 托管），数据不出内网。需要能装下目标模型的显存或内存。
• 源码：要改框架内部行为、参与贡献，或者想读docs/examples/里的上百个示例再决定。只读需求的话，clone 下来浏览即可：

git clone https://gitcode.com/GitHub_Trending/ll/llama_index

不确定就先走云端 API。路线随时可切换——核心包不变，换的只是模型和嵌入组件包。

2️⃣ 最小可用环境：一条命令装出核心能力

先建一个干净环境，避免和项目已有依赖互相污染：

python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate

然后装 starter 包：

pip install llama-index

这个包 =llama-index-core+ 一组常用集成（默认 OpenAI 模型与嵌入），装完就能跑通"读文档 → 建索引 → 提问"的最小闭环。如果走本地模型路线，装llama-index-core再自己挑组件即可，见第 4 节。

LlamaIndex 运行时会缓存 tokenizer、下载的文件等资源。默认放在系统用户缓存目录下，多项目共用容易混乱；建议用环境变量LLAMA_INDEX_CACHE_DIR把缓存收进项目目录，卸载或迁移项目时一并处理：

export LLAMA_INDEX_CACHE_DIR=/path/to/your/project/.llama_cache

3️⃣ 接入模型服务：LlamaIndex 配置 OpenAI 密钥的正确姿势

走云端 API 时，唯一必需的配置是密钥。把密钥写进环境变量，不要硬编码进代码——一旦提交到版本库或分享代码，泄露只是时间问题：

export OPENAI_API_KEY='sk-xxxx'

代码里默认读取该变量，一般无需再写。要显式指定模型参数（例如换模型、调温度、加额外字段），在初始化前配置Settings：

from llama_index.core import Settings Settings.llm = OpenAI(model="gpt-4o", temperature=0.2)

接入 Azure OpenAI、Groq、本地 Ollama 等其他服务时，模式完全一样：先装对应组件包，再把Settings.llm（以及Settings.embed_model）指过去。Ollama 示例见 llama-index-llms-ollama 的说明。

4️⃣ 按需求加装组件：看懂命名规律就不用记清单

LlamaIndex 把 300 多个集成拆成了独立小包，包名就是说明书，规律是：

llama-index-<组件类别>-<具体服务>

按"组件类别"选包，类别与导入子模块对应：

举例：想用 Ollama 提供嵌入，就选llama-index-embeddings-ollama；想接 Chroma 向量库，就选llama-index-vector-stores-chroma。仓库llama-index-integrations/目录按类别分了文件夹，可当组件目录直接翻。

两条配套规则：

• 核心模块的导入都带.core（如from llama_index.core import ...）；不带.core的导入一定来自某个集成包。导入报错时先确认对应包装没装。
• 同一组件类别装多个包不冲突，但建议给每个项目只留一套模型 + 一套嵌入，避免不同嵌入维度混用。

5️⃣ 跑通验收：一个最小示例判断安装是否成功

准备两三个文本文件放在任意目录，然后运行下面这段脚本（默认嵌入是本地 HuggingFace 模型，首次运行会自动下载；若已按第 3 节配置好 OpenAI，可直接跳过Settings.embed_model两行，省一次下载）：

from llama_index.core import ( Settings, SimpleDirectoryReader, VectorStoreIndex, ) from llama_index.embeddings.huggingface import HuggingFaceEmbedding Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5") docs = SimpleDirectoryReader("data/").load_data() index = VectorStoreIndex.from_documents(docs) answer = index.as_query_engine().query("这份资料讲的是什么？") print(answer)

判断标准很直接：脚本正常跑完、打印出一段基于你文件内容的回答，说明安装成功。若卡住，按报错定位——嵌入下载慢就检查网络与代理；ImportError就回到第 4 节核对包名；OpenAI 相关报错优先检查OPENAI_API_KEY是否已导出且格式正确。

6️⃣ 踩坑与排障：依赖、网络与导入三类高频问题

• 依赖冲突：LlamaIndex 的组件包会各自拉依赖，最容易撞车的是openai客户端和transformers的版本。解法是把项目锁在独立虚拟环境里，装完后pip freeze > requirements.txt固定下来，新机器用这份清单复现。
• 网络问题：嵌入模型和 tokenizer 首次运行要下载。国内网络建议给 pip 配镜像源，并检查代理环境变量（HTTP_PROXY/HTTPS_PROXY）是否已导出；下载中断后重跑即可，文件会缓存在LLAMA_INDEX_CACHE_DIR指向的目录里，补传不会全量重来。
• Ollama 响应超时：本地模型首帧生成慢，默认超时容易不够。构造时把超时调大，例如Ollama(model="llama3.1", request_timeout=120.0)。
• 导入报ModuleNotFoundError：基本是包没装或包名选错。看报错里llama_index.<类别>.<服务>那段，反推包名llama-index-<类别>-<服务>补装。
• 缓存目录写满：长期开发后缓存目录会越来越大，确认项目不依赖这些缓存文件后可整个目录清掉，下次运行会重新下载。

7️⃣ 生产化建议：从能跑到跑得稳

• 固定版本：用pip freeze或 lockfile 锁住llama-index-core和全部组件包版本，升级时整体验证，不要单包跳版本。
• 容器化：把 Python 环境、Ollama（如用本地模型）、缓存目录一起打进镜像，保证开发与线上环境一致。
• 可观测性：仓库自带可观测性集成（Langfuse、Arize Phoenix、MLflow 等，见 llama-index-integrations/callbacks/），接上后能看到每次查询的耗时、token 消耗和报错位置，排障成本直接下降。
• 吞吐优化：大批量文档入库用IngestionPipeline走批量处理而不是逐条add；高并发查询用异步 API（await query_engine.aquery(...)）；重复提问多时利用缓存避免重复检索。

8️⃣ 下一步：从示例到第一个 RAG

按这个顺序走，每一步都有现成代码可抄：

1. 浏览 docs/examples/ 下的 Notebook，重点看 basic_rag 入门示例 对应的 向量库索引示例 和 llm 集成示例。
2. 把示例数据换成你自己的文档，跑通第一个能回答业务问题的 RAG。
3. 按数据类型加读取器（数据库、网页、邮件），按检索质量加重排器。
4. 想深入再看 llama-index-core/ 的源码和 CONTRIBUTING.md，参与贡献。

先让最小示例跑起来，再谈扩展——组件包的命名规律你已经会读了，后面每一步都只是选包、装包、改Settings三件事。

【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index