安装与配置 #

环境要求 #

系统要求 #

text 
┌─────────────────────────────────────────────────────────────┐
│                    系统要求                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Python 版本：                                              │
│  ✅ Python 3.8+                                             │
│  ✅ 推荐 Python 3.10 或 3.11                                │
│                                                             │
│  操作系统：                                                  │
│  ✅ macOS                                                   │
│  ✅ Linux                                                   │
│  ✅ Windows                                                 │
│                                                             │
│  内存要求：                                                  │
│  ⚠️ 至少 4GB RAM（本地模型需要更多）                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

推荐配置 #

bash 
Python 3.10+
pip 或 poetry 或 uv
虚拟环境（推荐）

安装 LlamaIndex #

基础安装 #

bash 
pip install llama-index

安装特定组件 #

LlamaIndex 采用模块化设计，可以按需安装：

bash 
pip install llama-index-core

pip install llama-index-llms-openai

pip install llama-index-embeddings-openai

pip install llama-index-vector-stores-chroma

pip install llama-index-readers-file

常用集成包 #

bash 
pip install "llama-index[embeddings]"

pip install "llama-index[vector_stores]"

pip install "llama-index[llms]"

pip install "llama-index[all]"

配置 LLM #

OpenAI 配置 #

python 
import os
from llama_index.llms.openai import OpenAI

os.environ["OPENAI_API_KEY"] = "sk-your-api-key"

llm = OpenAI(model="gpt-4o")

response = llm.complete("你好，世界！")
print(response.text)

使用 .env 文件 #

bash 
OPENAI_API_KEY=sk-your-api-key
OPENAI_API_BASE=https://api.openai.com/v1
python 
from dotenv import load_dotenv
from llama_index.llms.openai import OpenAI
from llama_index.core import Settings

load_dotenv()

Settings.llm = OpenAI(model="gpt-4o")

其他 LLM 提供商 #

Azure OpenAI #

python 
from llama_index.llms.azure_openai import AzureOpenAI

llm = AzureOpenAI(
    engine="my-deployment",
    model="gpt-4",
    api_key="your-azure-key",
    azure_endpoint="https://your-resource.openai.azure.com",
    api_version="2024-02-15-preview",
)

Anthropic Claude #

python 
from llama_index.llms.anthropic import Anthropic

llm = Anthropic(model="claude-3-opus-20240229")

本地模型（Ollama） #

python 
from llama_index.llms.ollama import Ollama

llm = Ollama(model="llama3", request_timeout=120.0)

本地模型（Hugging Face） #

python 
from llama_index.llms.huggingface import HuggingFaceLLM

llm = HuggingFaceLLM(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    tokenizer_name="meta-llama/Llama-2-7b-chat-hf",
)

配置 Embedding 模型 #

OpenAI Embeddings #

python 
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core import Settings

Settings.embed_model = OpenAIEmbedding(
    model="text-embedding-3-small"
)

本地 Embeddings #

python 
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-en-v1.5"
)

Ollama Embeddings #

python 
from llama_index.embeddings.ollama import OllamaEmbedding

Settings.embed_model = OllamaEmbedding(
    model_name="nomic-embed-text",
    base_url="http://localhost:11434",
)

全局配置 #

使用 Settings #

python 
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")
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.chunk_size = 512
Settings.chunk_overlap = 50

配置选项 #

python 
from llama_index.core import Settings

Settings.llm = OpenAI(model="gpt-4o")

Settings.embed_model = OpenAIEmbedding()

Settings.chunk_size = 1024

Settings.chunk_overlap = 20

Settings.num_output = 512

Settings.context_window = 4096

向量存储配置 #

使用 Chroma #

bash 
pip install llama-index-vector-stores-chroma chromadb
python 
import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core import StorageContext

db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("my_collection")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context
)

使用 Pinecone #

bash 
pip install llama-index-vector-stores-pinecone pinecone-client
python 
from pinecone import Pinecone
from llama_index.vector_stores.pinecone import PineconeVectorStore

pc = Pinecone(api_key="your-api-key")
pinecone_index = pc.Index("my-index")
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)

使用 Qdrant #

bash 
pip install llama-index-vector-stores-qdrant qdrant-client
python 
from qdrant_client import QdrantClient
from llama_index.vector_stores.qdrant import QdrantVectorStore

client = QdrantClient(url="http://localhost:6333")
vector_store = QdrantVectorStore(client=client, collection_name="my_collection")

完整配置示例 #

最小配置 #

python 
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI

os.environ["OPENAI_API_KEY"] = "sk-your-key"

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine()
response = query_engine.query("你的问题")
print(response)

生产配置 #

python 
import os
from dotenv import load_dotenv
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext
import chromadb

load_dotenv()

Settings.llm = OpenAI(
    model="gpt-4o",
    temperature=0.1,
    max_tokens=1024,
)
Settings.embed_model = OpenAIEmbedding(
    model="text-embedding-3-small"
)
Settings.chunk_size = 512
Settings.chunk_overlap = 50

db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("knowledge_base")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
    show_progress=True,
)

index.storage_context.persist(persist_dir="./storage")

常见问题 #

1. API Key 问题 #

text 
问题：OpenAI API key not found

解决方案：
1. 确保设置了环境变量
2. 检查 .env 文件是否正确加载
3. 验证 API Key 是否有效
python 
import os
print(os.environ.get("OPENAI_API_KEY"))

2. 内存问题 #

text 
问题：处理大文件时内存不足

解决方案：
1. 减小 chunk_size
2. 分批处理文档
3. 使用流式处理
python 
Settings.chunk_size = 256

from llama_index.core import SimpleDirectoryReader
reader = SimpleDirectoryReader(
    input_dir="./data",
    recursive=True,
    exclude=["*.tmp"],
)
documents = reader.load_data(num_files=10)

3. 网络问题 #

text 
问题：连接超时

解决方案：
1. 设置代理
2. 增加超时时间
3. 使用本地模型
python 
import os
os.environ["HTTP_PROXY"] = "http://proxy:port"
os.environ["HTTPS_PROXY"] = "http://proxy:port"

llm = OpenAI(timeout=120)

4. 版本兼容 #

bash 
pip install --upgrade llama-index

pip list | grep llama

验证安装 #

python 
from llama_index.core import VectorStoreIndex, Document
from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini")
response = llm.complete("Hello, LlamaIndex!")
print(response.text)

doc = Document(text="LlamaIndex 是一个数据框架。")
index = VectorStoreIndex.from_documents([doc])
query_engine = index.as_query_engine()
response = query_engine.query("LlamaIndex 是什么？")
print(response)

下一步 #

环境配置完成后，接下来学习 快速开始 构建你的第一个 RAG 应用！

最后更新：2026-03-30