LlamaIndex 怎么安装：3 种方式与验证步骤

LlamaIndex 是连接大语言模型与自有数据的开源框架，适合搭建检索增强生成（RAG）和文档问答应用。

截至 2026 年 11 月抓取时，PyPI 页面显示 llama-index 版本为 0.14.25。这个版本页面同时明确区分了两种 Python 安装思路：需要快速开始时使用包含核心能力和若干集成包的 llama-index；需要控制依赖体积时，先安装 llama-index-core，再按项目需要添加集成包。现在值得重新安装或升级，是因为 LlamaIndex 生态已经进一步分成“核心框架、集成包、云端解析服务”几层，直接照旧教程只执行一条 pip install 命令，容易把不需要的依赖和云服务混在一起。

先选对安装方式

安装前先根据目标选择路径，不要把三个包名当成同一个东西。

目标	安装方式	适合谁	安装后还要做什么
跟着示例快速跑通	pip install llama-index	第一次接触 LlamaIndex、需要读写文件和调用 OpenAI 的学习者	配置模型密钥，或改用其他模型集成
只装核心能力	pip install llama-index-core	已经明确需要哪些模型、向量库或数据读取器的开发者	从 integrations 页面挑选并安装对应包
本地解析文档	npm install @llamaindex/liteparse	不想调用云端文档解析服务的用户	按 LiteParse 仓库说明配置本地解析流程

llama-index 是 starter package（入门包），会带入核心包以及一组常用集成；llama-index-core 只提供核心框架。官方 PyPI 说明，核心包和集成包采用不同的导入路径，因此不能先安装 llama-index-core，再直接照搬集成包的 from llama_index.xxx... 写法。

LlamaParse 是另一条路线：它是独立的文档智能平台，可单独使用，也能接入 LlamaIndex。它需要注册账号并创建 API key，适合需要 OCR、结构化抽取、文档 Agent 或托管式索引流水线的场景。如果只是本机读取文件，优先使用 Python 核心包或 LiteParse；如果要处理复杂扫描件和版面，先评估 LlamaParse。

用虚拟环境安装 starter package

下面三条命令直接来自官方安装文档，适合第一次安装、想先跑通基础流程的用户。命令以官方文档中的写法为准。

1. 创建并激活隔离环境

在项目目录打开终端，执行：

python -m venv .venv
source .venv/bin/activate

Windows PowerShell 不使用上面的 source 行，改为：

..venvScriptsActivate.ps1

如果 Windows 提示脚本执行被禁止，可以只为当前用户调整执行策略：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

随后执行 ..venvScriptsActivate.ps1。这一步的目的不是“让命令更好看”，而是避免 LlamaIndex 的核心包和集成包污染系统 Python，也方便之后删除整个项目环境。

2. 安装 llama-index

在已经激活的虚拟环境中执行官方快速安装命令：

pip install llama-index

llama-index 会安装 llama-index-core，并附带常用集成，例如 OpenAI 的 LLM、embedding、program、question generation、agent，以及文件读取器和多模态 LLM 集成。官方安装文档还列出 llama-index-legacy：它只是暂时包含在 starter package 中，不代表新项目必须主动依赖它。

安装过程中，LlamaIndex 可能会下载并保存 NLTK、Hugging Face 等组件的本地文件。官方文档给出的缓存目录环境变量是：

LLAMA_INDEX_CACHE_DIR

如果你的环境不能写默认缓存目录，或者机器之间需要共享缓存，就在启动应用前显式设置这个变量。

3. 检查包和导入路径

安装完成后，先运行：

pip show llama-index

确认输出中的 Version 与项目预期一致。当前 PyPI 页面显示的是 0.14.25；如果安装结果低于这个版本，不要直接继续创建项目，先执行：

pip install --upgrade llama-index

然后验证核心模块能否导入：

python -c "from llama_index.core.llms import LLM; print('llama-index core import ok')"

出现 llama-index core import ok，只说明核心包和当前 Python 环境已经连通；它还没有证明模型密钥、网络连接或具体数据读取器可用。

只需要核心包时，按需安装

如果你的项目已经确定要使用某个模型、向量数据库或文档读取器，可以采用官方 PyPI 页面所说的 customized（定制化）安装方式。

1. 安装核心包

pip install llama-index-core

核心包页面说明，llama-index-core 预置了 NLTK 和 tiktoken 文件，用来避免运行时下载文件和产生额外网络调用。安装后可验证：

python -c "import llama_index.core; print(llama_index.core.__file__)"

命令应输出一段以 .venv 目录开头的文件路径；如果路径指向系统 Python，通常说明虚拟环境没有激活，或者安装到了另一个解释器。

2. 从 integrations 页面挑包

打开官方集成页：

https://developers.llamaindex.ai/python/framework/community/integrations

先确定三件事：文本生成模型、embedding 模型、数据读取器。找到对应包后，用 pip 安装。例如，官方 PyPI 示例使用了 OpenAI 的 LLM 集成：

pip install llama-index-llms-openai

但不要因为官方示例用了 OpenAI，就把它当成必选项。如果你使用其他模型供应商，应安装该供应商对应的 LlamaIndex integration；如果你暂时只做核心数据结构实验，可以先不装模型集成。

3. 用正确的命名空间导入

核心功能和集成功能使用不同导入路径。官方示例是：

from llama_index.core.llms import LLM
from llama_index.llms.openai import OpenAI

判断规则很简单：模块路径里有 .core，导入的是核心子模块；没有 .core，导入的是集成包。安装 llama-index-core 后，直接导入 llama_index.llms.openai 失败，通常不是核心包坏了，而是尚未安装对应的 OpenAI 集成。

配置模型密钥并跑一次最小验证

安装完成不等于已经能调用模型。官方安装文档把模型配置列为单独步骤：如果使用 OpenAI，需要设置 OPENAI_API_KEY；如果不使用 OpenAI，则应改用对应集成，并准备该服务的认证配置。

macOS 或 Linux 可以在当前终端临时设置：

export OPENAI_API_KEY="你的密钥"

Windows PowerShell 使用：

$env:OPENAI_API_KEY="你的密钥"

不要把真实密钥写进 Git 仓库的代码文件、截图或公开 issue。设置后新建终端进程时，需要重新设置环境变量；想长期保存，再把它加入用户级 shell 配置或系统环境变量。

最小验证可以分两层。先检查环境变量是否存在：

python -c "import os; print('OPENAI_API_KEY' in os.environ)"

应输出 True。再导入要使用的模型类：

python -c "from llama_index.llms.openai import OpenAI; print('OpenAI integration import ok')"

应输出 OpenAI integration import ok。最后才是发起一次真实请求。真实请求会消耗模型额度，也可能因密钥无效、账户权限或网络问题失败；因此“导入成功”和“调用成功”必须分开看。

官方文档还提醒，旧教程常见的默认模型名称可能已经过时。新项目应显式选择 embedding 模型，而不是依赖历史默认值。具体模型名和参数以你选择的官方集成文档为准。

三类安装方案怎么选

方案	优点	代价	不适合的情况
pip install llama-index	一次得到核心包和常用集成，适合快速试跑	依赖较多，项目镜像会更大	只做单一集成、严格控制依赖体积
pip install llama-index-core 加按需集成	依赖清晰，方便锁定模型和向量库	开始前必须先列集成清单	尚未了解项目要接哪些服务的用户
LiteParse	本地、免费、无需云端 LLM token	不是完整 LlamaIndex Python 应用栈	需要直接获得 LlamaParse 的托管 OCR 能力

这是根据官方包说明和 LiteParse 项目定位做的选择对照，不是官方给出的固定推荐顺序。最实用的判断是：先用 llama-index 验证项目链路，再根据锁文件中的实际依赖拆成 llama-index-core 加显式集成包；这样既不会一开始漏装依赖，也不会长期携带完全用不到的组件。

常见卡点与对应处理

包已经安装，但导入路径报错

先确认实际安装位置：

python -m pip show llama-index
python -m pip show llama-index-core

使用 python -m pip 可以确保 pip 与当前 Python 解释器一致。如果两条命令显示的路径不同，说明系统中存在多套 Python 环境。重新激活项目虚拟环境，再执行对应的安装命令。

from llama_index.xxx 导入失败

如果导入路径位于 llama_index.core，检查核心包是否安装；如果位于 llama_index.llms.openai、llama_index.embeddings... 等集成命名空间，则安装对应 integration。不要通过修改 import 语句把集成路径硬改成 core 路径，因为两者不是同一套类。

安装成功，但调用模型失败

先执行：

python -c "import os; print('OPENAI_API_KEY' in os.environ)"

输出 False 时，按前面的环境变量命令重新设置。输出 True 仍失败时，再核对密钥是否过期、账户是否能使用所选模型，以及服务是否可访问。不要在教程或 issue 中粘贴完整密钥，只需提供环境变量名、错误类型和脱敏后的请求信息。

缓存文件写入失败

把缓存指向项目内可写目录，再启动应用：

export LLAMA_INDEX_CACHE_DIR="$PWD/.llama_index_cache"

这是根据官方提供的 LLAMA_INDEX_CACHE_DIR 环境变量做的可执行处理。若项目使用容器，还要把该目录挂载为持久卷，否则容器重建后缓存会消失。

怎么算安装成功

最小成功标志包括四项：虚拟环境中能执行 pip show llama-index；核心导入命令输出 llama-index core import ok；需要的 integration 能单独导入；模型调用的密钥检查返回 True。如果使用 LlamaParse，还应能在官方开发者页面创建账号并取得 API key；如果使用 LiteParse，则应能在本机读取其仓库说明支持的文档格式。

官方首页目前将 LlamaParse、LiteParse、Extract、Index 和 Agents 分开呈现，这种产品边界变化正是现在需要重新选择安装路径的原因：LlamaIndex OSS 仍是可用工具包，但官方当前的主要投入已经转向文档解析与抽取能力。

官方入口与延伸阅读

• LlamaIndex 官方首页：查看产品边界、LlamaParse 与 LiteParse 入口。
• LlamaIndex PyPI：查看当前版本、starter package 内容和官方 Python 示例。
• 官方安装与设置文档：核对虚拟环境、starter package、缓存目录和模型配置。
• 官方 integrations 页面：按模型、embedding、向量库和读取器查找安装包。
• LlamaIndex 官方仓库：查看源码、示例和项目变更。
• LiteParse 官方仓库：查看本地文档解析器的安装、格式支持和用法。