LlamaIndex 安装完整教程3 种方式、5 个高频坑10 分钟跑通第一个 RAG【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexLlamaIndex 是一个面向大语言模型应用开发的开源数据框架负责把 PDF、SQL、网页等各类数据接进来ingest切分并建成索引再通过检索增强问答RAG把私有知识喂给 LLM。对新手来说装什么、怎么装、装完怎么确认能用是三件最常卡住的事。本文按选型 → 落地 → 排坑 → 运维的顺序讲清楚全程只给必须运行的最小命令。怎么选安装方式3 条决策路径仓库里的包分两类角色llama-index-core是纯核心框架其余 300 多个llama-index-xxx包是各类集成LLM、Embedding、向量库、数据读取器等集中在 llama-index-integrations/ 目录下。选型只看一个问题你要用哪些外部组件。安装方式典型命令适合谁代价起步包llama-indexpip install llama-index先跑通 demo、不想挑依赖会带入一批默认集成体积偏大核心 按需集成llama-index-corepip install llama-index-core 所需集成包生产环境、明确知道要接什么需要自己判断装哪些包源码安装git clone后本地安装要改框架代码、跟主线开发版本维护成本高经验法则学习和验证用起步包最快一旦要进生产环境切换到核心 按需集成只装真正用到的 LLM / Embedding / 向量库能显著减少依赖冲突和安装体积。导入语句的命名空间能帮你快速定位依赖带core的llama_index.core.xxx来自核心包不带core的llama_index.llms.ollama来自对应集成包。看到报错时先按这个规则判断缺的是哪个包。LlamaIndex 一键安装命令先确认 Python 版本仓库要求3.10,4.0见 llama-index-core/pyproject.toml。低于 3.10 会在安装阶段直接报版本不满足。强烈建议用虚拟环境隔离。直接pip install到全局环境很容易和项目里其他包的依赖打架之后排查非常费时间。python -m venv llama_env source llama_env/bin/activate # Windows 用 llama_env\Scripts\activate pip install llama-index如果走核心 按需集成路线只装你要用的部分即可pip install llama-index-core pip install llama-index-llms-ollama llama-index-embeddings-huggingface 源码安装开发者路径git clone https://gitcode.com/GitHub_Trending/ll/llama_index cd llama_index/llama-index-core pip install -e .每个集成包都是独立工程自带pyproject.toml和uv.lock需要哪个就进哪个目录做同样的可编辑安装。核心框架源码在 llama-index-core/项目总览见 README.md。依赖与缓存目录怎么配LlamaIndex 运行时会下载并缓存一些资源nltk 语料、tiktoken 词表等默认落在用户级缓存目录Linux 下是~/.cache/llama_index。想自定义位置设置环境变量即可实现见llama-index-core/llama_index/core/utils.py的get_cache_direxport LLAMA_INDEX_CACHE_DIR/your/custom/path⚠️ 两个容易踩的点权限这个目录必须可写容器或受限账户里最容易在这里报PermissionError换个有权限的路径通常就解决。受限磁盘环境llama-index-core内置了_static目录预先打包了 nltk / tiktoken 缓存离线或只读环境下也能跑官方用构建溯源attest-build-provenance保证这些文件与仓库一致详见 README.md 末尾说明。模型怎么接云端、本地与混合装完框架后模型不是一步到位装好的而是按集成包单独安装、按Settings统一配置。三种常见姿势场景推荐方案一句话理由云端 APIllama-index-llms-openai默认示例即用 OpenAI配好 key 即可本地部署llama-index-llms-ollama 本地 Embedding数据不出机器隐私与成本可控混合架构同时装多个 LLM 集成包按任务路由简单任务走本地关键任务走云端本地 Ollama 的最小配置完整示例可参考 README.md 中 Ollama 一节from llama_index.core import Settings from llama_index.llms.ollama import Ollama Settings.llm Ollama(modelllama-3.1:latest)⚠️ 本地方案注意模型权重下载同样受网络和磁盘限制GPU 用户需先确认 Ollama 与驱动版本的兼容性否则 CPU 推理慢到看起来像卡死。密钥管理只有一条铁律不要把 API key 写进代码用环境变量如OPENAI_API_KEY注入代码里只读取不硬编码。LlamaIndex 安装验证最小 RAG 脚本用 5 行代码确认整条链路读文件 → 建索引 → 问答是通的。默认使用 OpenAI需先设好OPENAI_API_KEY走本地模型则参考上一节先配Settings.llm。from llama_index.core import VectorStoreIndex, SimpleDirectoryReader docs SimpleDirectoryReader(./data).load_data() index VectorStoreIndex.from_documents(docs) print(index.as_query_engine().query(你的问题))能打印出带上下文的回答安装就算真正完成。如果之后要重启加载索引用下面两行持久化 / 恢复默认数据只在内存中index.storage_context.persist() # 写入 ./storage # 重启后 # index load_index_from_storage(StorageContext.from_defaults(persist_dir./storage))常见 LlamaIndex 安装坑排查表现象常见原因处理办法安装时报requires Python 3.10系统 Python 版本过旧升级到 3.10或用pyenv/容器切版本ImportError: cannot import name ...装了核心但缺对应集成包按带 core / 不带 core规则定位补装相应llama-index-xxx依赖版本冲突、包被反复降级多个项目共用全局环境回到虚拟环境按选型表只装必要集成模型/语料下载超时网络或代理问题配置代理后重试受限环境依赖内置_static缓存缓存目录写入失败目录无权限改LLAMA_INDEX_CACHE_DIR指向可写路径GPU 推理报错或极慢CUDA / 驱动 / 框架版本不匹配核对 Ollama、PyTorch 与驱动版本组合多数装不上最后都回到两个原点Python 版本和缺集成包。先把这两点排除再查网络与权限。安全与性能建议密钥环境变量注入配合最小权限原则容器里不给多余的系统权限。版本固定生产环境锁定llama-index-core及关键集成的版本号升级走变更流程避免今天能跑明天崩。缓存治理定期清理LLAMA_INDEX_CACHE_DIR下的过期内容防止磁盘悄悄涨满。容器化服务化部署推荐 Docker 封装把 Python 版本、依赖、缓存路径一次固化。LlamaIndex 维护与升级建议装完不是结束日常维护主要盯三件事依赖更新跟进llama-index-core的安全与功能更新升级前先在虚拟环境里回归核心链路。可观测性框架提供多个监控回调集成Langfuse、Phoenix、LangSmith 等见 llama-index-integrations/callbacks/生产环境建议接入出问题时有据可查。资源监控关注索引构建耗时、内存占用与 API 调用成本混合架构下尤其注意本地模型的吞吐瓶颈。延伸阅读项目总览README.md核心框架源码llama-index-core/集成包全集llama-index-integrations/示例与教程docs/【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考