垦荒学园
  • 中文

      • 安装与环境

      环境要求

      • Python 3.10+（推荐 3.11 / 3.12）
      • pip，或 uv / poetry
      • 至少一个 LLM Provider 的 API Key（本课默认 OpenAI）

      生态是 核心包 + 命名空间集成包。pip install llama-index 会装入门捆绑，其余 Reader / 向量库按需再装。完整列表见 LlamaHub。

      创建虚拟环境

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

      安装核心包

      官方入门：

      pip install llama-index

      捆绑大致包含：

      包作用
      llama-index-core索引、查询、Agent、Workflow
      llama-index-llms-openaifrom llama_index.llms.openai import OpenAI
      llama-index-embeddings-openaiOpenAI Embedding
      llama-index-readers-file本地文件 Reader

      llama-index-core 会预置部分 NLTK / tiktoken 文件，减少运行时下载。

      不用 OpenAI、改走本地模型时，按需安装（示例）：

      pip install llama-index-core llama-index-readers-file \
  llama-index-llms-ollama llama-index-embeddings-huggingface

      向量库（详见 向量库集成）：

      pip install llama-index-vector-stores-chroma
pip install llama-index-vector-stores-postgres
pip install llama-index-vector-stores-qdrant

      验证：

      python -c "from llama_index.core import VectorStoreIndex; print('ok')"

      API Key 配置

      历史默认生成模型是 gpt-3.5-turbo，嵌入是 text-embedding-ada-002。本课示例用 gpt-4o-mini，并以官方当前文档为准。只要走 OpenAI，就需要 OPENAI_API_KEY。

      方式 1：环境变量（推荐）

      export OPENAI_API_KEY="sk-..."

      Windows PowerShell：

      $env:OPENAI_API_KEY = "sk-..."

      方式 2：.env 文件

      pip install python-dotenv
      OPENAI_API_KEY=sk-...
      from dotenv import load_dotenv
load_dotenv()

      安全： 不要把 .env 提交 Git，写入 .gitignore。

      兼容 OpenAI 的网关可用官方文档中的 OpenAILike LLM / Embedding 类，自行设 api_base。

      全局 Settings（建议一开始就写上）

      未传入组件时，LlamaIndex 用全局 Settings。显式指定可避免默认模型变更：

      from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.llm = OpenAI(model="gpt-4o-mini")
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.chunk_size = 512
Settings.chunk_overlap = 50

      本地 Ollama 示例：

      from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings

Settings.llm = Ollama(model="llama3.2", request_timeout=120.0)
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")

      项目结构建议

      my-llamaindex-app/
├── .env
├── .gitignore
├── data/              # 原始文档
├── storage/           # persist 后的默认索引
├── src/
│   ├── ingest.py
│   └── query.py
└── requirements.txt

      常见问题

      OPENAI_API_KEY 报错？
      环境变量未进当前进程；IDE 终端与系统终端可能不是同一套环境。

      第一次查询很慢、一直打 embedding？
      默认索引只在内存里。用 index.storage_context.persist(...) 或外接向量库，见 快速上手 与 向量库集成。

      ModuleNotFoundError: llama_index.vector_stores.chroma？
      核心包不含所有向量库，需安装对应 llama-index-vector-stores-*。

      依赖冲突？
      新 venv 中只装本课需要的包；不要和过旧的 llama-index<0.10 混装（那套 ServiceContext API 已由 Settings 取代）。

      下一步

      评论