# LlamaIndex

LlamaIndex（原名 GPT Index）是一个 **用于大语言模型应用的数据框架** 拥有超过 **37,000 个 GitHub 星标**。而 LangChain 专注于链式调用 LLM，LlamaIndex 擅长于 **数据摄取、索引和结构化查询** — 当您的应用需要对大型、异构的文档集合进行推理时，它是首选。

LlamaIndex 为复杂数据结构（数据库、API、PDF、Notion 页面、GitHub 仓库）和复杂检索策略提供一流支持。在 Clore.ai GPU 服务器上使用本地 LLM 运行可消除 API 成本并保持数据私有。

主要优势：

* 📊 **数据连接器** — 160+ 集成（PDF、SQL、Notion、Slack、GitHub 等）
* 🗂️ **多种索引类型** — 向量、树、列表、关键词、知识图谱
* 🔍 **高级检索** — 子问题分解、递归检索、混合检索
* 🤖 **查询引擎** — 针对任何数据源的 SQL、结构化和自然语言查询
* 🧩 **多模态** — 在文本之外支持图像、音频和视频
* 💾 **持久化** — 内建对 ChromaDB、Pinecone、Weaviate 等的支持
* ⚡ **以异步为先** — 为生产吞吐量而构建
* 🔗 **兼容 LangChain** — 可同时使用两个框架

{% hint style="success" %}
所有示例都可以在通过以下方式租用的 GPU 服务器上运行 [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

***

## 服务器要求

| 参数       | 最低要求                   | 推荐配置                    |
| -------- | ---------------------- | ----------------------- |
| GPU      | NVIDIA RTX 3080（10 GB） | NVIDIA RTX 4090（24 GB）  |
| 显存（VRAM） | 8 GB（7B 模型）            | 24 GB（13B–34B 模型）       |
| 内存（RAM）  | 16 GB                  | 32–64 GB                |
| CPU      | 4 个内核                  | 16 核                    |
| 磁盘       | 30 GB                  | 100+ GB（本地模型 + 数据）      |
| 操作系统     | Ubuntu 20.04+          | Ubuntu 22.04            |
| CUDA     | 11.8+                  | 12.1+                   |
| Python   | 3.9+                   | 3.11                    |
| 端口       | 22, 8000               | 22, 8000, 11434（Ollama） |

{% hint style="info" %}
LlamaIndex 是一个 Python 库——GPU 资源由底层的 LLM 和嵌入模型消耗。对于生产部署，将 LlamaIndex 与 Ollama（用于本地推断）和 ChromaDB（用于向量存储）配对，并在您的 Clore.ai GPU 服务器上运行。
{% endhint %}

***

## 在 CLORE.AI 上快速部署

### 1. 找到合适的服务器

前往 [CLORE.AI 市场](https://clore.ai/marketplace) 并根据您的 LLM 大小进行选择：

| 在 Clore.ai 上的预估费用 | GPU             | 说明               |
| ----------------- | --------------- | ---------------- |
| 开发 / 测试           | RTX 3080（10 GB） | 7B 模型，小型文档集      |
| 生产（小型）            | RTX 4090（24 GB） | 13B 模型，中等数据集     |
| 生产（大型）            | A100 40G / 80G  | 34B–70B 模型，大型数据集 |
| 企业级               | H100（80 GB）     | 最大吞吐量            |

### 2. 配置您的部署

**Docker 镜像（基础）：**

```
nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04
```

**端口映射：**

```
22    → SSH 访问
8000  → LlamaIndex API / Gradio UI
11434 → Ollama 推理引擎
```

**启动脚本：**

```bash
#!/bin/bash
# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve &
sleep 5
ollama pull llama3:8b
ollama pull nomic-embed-text

# 安装 LlamaIndex
pip install llama-index llama-index-llms-ollama llama-index-embeddings-ollama
pip install chromadb fastapi uvicorn

python /workspace/app.py
```

### 3. 访问 API

```
http://<your-clore-server-ip>:8000
```

***

## 逐步设置

### 第一步：SSH 登录到您的服务器

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

### 第二步：安装 Ollama

```bash
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve &
sleep 5

# 拉取模型
ollama pull llama3:8b              # 用于生成的 LLM
ollama pull nomic-embed-text       # 嵌入模型

# 验证
ollama list
```

### 第三步：设置 Python 环境

```bash
mkdir -p /workspace/llamaindex-app
cd /workspace/llamaindex-app

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
```

### 第四步：安装 LlamaIndex 包

```bash
# 核心 LlamaIndex
pip install llama-index

# LLM 集成
pip install llama-index-llms-ollama
pip install llama-index-llms-openai     # 可选：OpenAI

# 嵌入集成
pip install llama-index-embeddings-ollama
pip install llama-index-embeddings-huggingface

# 向量存储集成
pip install llama-index-vector-stores-chroma

# 数据加载器
pip install llama-index-readers-file
pip install llama-index-readers-web

# 可选：额外的读取器
pip install pypdf docx2txt
```

### 第五步：配置全局设置

```python
# settings.py
from llama_index.core import Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

# 配置 LLM
Settings.llm = Ollama(
    model="llama3:8b",
    base_url="http://localhost:11434",
    request_timeout=300.0,
    temperature=0.1,
)

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

# 配置分块设置
Settings.chunk_size = 1024
Settings.chunk_overlap = 200
```

### 第六步：构建您的第一个索引

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 从目录加载文档
documents = SimpleDirectoryReader("/workspace/data/docs").load_data()
print(f"Loaded {len(documents)} documents")

# 构建向量索引（自动嵌入并存储）
index = VectorStoreIndex.from_documents(documents)

# 将索引保存到磁盘
index.storage_context.persist("/workspace/index_storage")
print("Index built and saved!")
```

### 第七步：查询索引

```python
from llama_index.core import load_index_from_storage, StorageContext

# 加载现有索引
storage_context = StorageContext.from_defaults(persist_dir="/workspace/index_storage")
index = load_index_from_storage(storage_context)

# 创建查询引擎
query_engine = index.as_query_engine(similarity_top_k=5)

# 提问
response = query_engine.query("What GPU servers are available on Clore.ai?")
print(f"Answer: {response}")
print(f"\nSources: {len(response.source_nodes)} nodes used")
```

***

## 使用示例

### 示例 1：基本文档问答

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding
from pathlib import Path

# 使用本地 Ollama 模型配置 LlamaIndex
Settings.llm = Ollama(model="llama3:8b", base_url="http://localhost:11434")
Settings.embed_model = OllamaEmbedding(
    model_name="nomic-embed-text",
    base_url="http://localhost:11434"
)

# 创建示例文档目录
data_dir = Path("/workspace/data")
data_dir.mkdir(exist_ok=True)

# 创建示例文档
(data_dir / "clore_faq.txt").write_text("""
Clore.ai 常见问题（FAQ）

问：什么是 Clore.ai？
答：Clore.ai 是一个去中心化的 GPU 云市场，将 GPU 所有者与需要计算资源的 AI 研究人员和开发者连接起来。

问：提供哪些 GPU？
答：Clore.ai 提供从 NVIDIA GTX 1080 到最新 H100 80GB 的 GPU。常见选项包括 RTX 4090、A100 40G/80G 和 RTX 3090。

问：定价如何？
答：价格由 GPU 提供者设定，随 GPU 型号、显存和可用性而变化。通常比 AWS/GCP 便宜 30-70%。

问：我可以运行哪些软件？
答：任何 Docker 容器。提供预配置的镜像用于 PyTorch、TensorFlow、ComfyUI、Stable Diffusion 等。
""")

# 构建索引
documents = SimpleDirectoryReader(str(data_dir)).load_data()
index = VectorStoreIndex.from_documents(documents, show_progress=True)

# 查询
query_engine = index.as_query_engine(similarity_top_k=3)

questions = [
    "Clore.ai 提供哪些 GPU？",
    "Clore.ai 的定价如何与 AWS 比较？",
    "我可以运行自定义 Docker 容器吗？",
]

for q in questions:
    print(f"\n❓ {q}")
    response = query_engine.query(q)
    print(f"💬 {response}")
```

***

### 示例 2：使用 ChromaDB 的多文档 RAG

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, StorageContext, Settings
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding
import chromadb

# 配置 LLM 和嵌入
Settings.llm = Ollama(model="llama3:8b", base_url="http://localhost:11434")
Settings.embed_model = OllamaEmbedding(
    model_name="nomic-embed-text",
    base_url="http://localhost:11434"
)

# 连接到 ChromaDB（在同一 Clore.ai 服务器上运行）
chroma_client = chromadb.HttpClient(host="localhost", port=8001)
chroma_collection = chroma_client.get_or_create_collection("llamaindex_docs")

# 为 LlamaIndex 创建 ChromaDB 向量存储
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 从多个来源加载文档
docs_dir = "/workspace/data/docs"
documents = SimpleDirectoryReader(
    docs_dir,
    recursive=True,              # 包含子目录
    required_exts=[".pdf", ".txt", ".md"],  # 仅这些格式
    filename_as_id=True          # 使用文件名作为文档 ID
).load_data()

print(f"Loaded {len(documents)} documents from {docs_dir}")

# 构建索引（存储在 ChromaDB 中）
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
    show_progress=True
)
print("Index built and persisted in ChromaDB!")

# 加载现有索引（后续会话）
# index = VectorStoreIndex.from_vector_store(vector_store)

# 带元数据过滤的高级查询引擎
from llama_index.core.vector_stores import MetadataFilter, MetadataFilters

# 使用元数据过滤进行查询
filtered_engine = index.as_query_engine(
    similarity_top_k=5,
    filters=MetadataFilters(
        filters=[
            MetadataFilter(key="file_type", value=".pdf"),
        ]
    )
)

response = filtered_engine.query("Summarize the key technical concepts in the documents.")
print(f"\nFiltered response: {response}")
```

***

### 示例 3：子问题分解

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.tools import QueryEngineTool, ToolMetadata
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

Settings.llm = Ollama(model="llama3:8b", base_url="http://localhost:11434")
Settings.embed_model = OllamaEmbedding(model_name="nomic-embed-text", base_url="http://localhost:11434")

# 为不同知识域创建独立索引
def build_index(docs_path, index_name):
    docs = SimpleDirectoryReader(docs_path).load_data()
    index = VectorStoreIndex.from_documents(docs)
    return index

# 独立知识库
pricing_index = build_index("/workspace/data/pricing", "pricing")
technical_index = build_index("/workspace/data/technical", "technical")
faq_index = build_index("/workspace/data/faq", "faq")

# 包装为工具
tools = [
    QueryEngineTool(
        query_engine=pricing_index.as_query_engine(),
        metadata=ToolMetadata(
            name="pricing_docs",
            description="包含 Clore.ai 的定价信息、成本比较和计费详情。"
        )
    ),
    QueryEngineTool(
        query_engine=technical_index.as_query_engine(),
        metadata=ToolMetadata(
            name="technical_docs",
            description="包含关于 GPU 规格、Docker 部署和 API 的技术文档。"
        )
    ),
    QueryEngineTool(
        query_engine=faq_index.as_query_engine(),
        metadata=ToolMetadata(
            name="faq_docs",
            description="包含常见问题及其答案。"
        )
    ),
]

# 子问题引擎会分解复杂查询
sub_question_engine = SubQuestionQueryEngine.from_defaults(
    query_engine_tools=tools,
    verbose=True
)

# 复杂的多部分问题
complex_question = """
比较在 Clore.ai 与 AWS 上运行一个 7B 参数 LLM 100 小时的成本，
并解释每种选项所需的技术设置。
"""

print(f"Question: {complex_question}")
response = sub_question_engine.query(complex_question)
print(f"\nComprehensive Answer:\n{response}")
```

***

### 示例 4：知识图谱索引

```python
from llama_index.core import KnowledgeGraphIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

Settings.llm = Ollama(model="llama3:13b", base_url="http://localhost:11434")  # 使用更大的模型以获得更好的抽取效果
Settings.embed_model = OllamaEmbedding(model_name="nomic-embed-text", base_url="http://localhost:11434")

# 加载文档
documents = SimpleDirectoryReader("/workspace/data/docs").load_data()

# 构建知识图谱（抽取实体和关系）
kg_index = KnowledgeGraphIndex.from_documents(
    documents,
    max_triplets_per_chunk=10,   # 每个分块最多抽取 10 个三元组
    include_embeddings=True,
    show_progress=True
)

# 保存图谱
kg_index.storage_context.persist("/workspace/kg_storage")
print(f"Knowledge graph built!")
print(f"Nodes: {len(kg_index.index_struct.table)}")

# 查询知识图谱
kg_query_engine = kg_index.as_query_engine(
    include_text=True,            # 包含源文本
    retriever_mode="keyword",     # 使用基于关键词的检索
    response_mode="tree_summarize"
)

questions = [
    "GPU 型号与使用场景之间有哪些关系？",
    "定价与 GPU 规格之间有何关联？",
    "哪些部署方法连接到哪些服务？",
]

for q in questions:
    print(f"\n🔍 {q}")
    response = kg_query_engine.query(q)
    print(f"📊 {response}")
```

***

### 示例 5：基于数据库的 SQL 查询引擎

```python
from llama_index.core import SQLDatabase, Settings
from llama_index.core.query_engine import NLSQLTableQueryEngine
from llama_index.llms.ollama import Ollama
from sqlalchemy import create_engine, text
import pandas as pd

Settings.llm = Ollama(model="llama3:8b", base_url="http://localhost:11434")

# 使用 GPU 市场数据创建示例数据库
engine = create_engine("sqlite:////workspace/clore_data.db")

# 创建并填充表
with engine.connect() as conn:
    conn.execute(text("""
        如果不存在则创建表 gpu_servers (
            id 整数 主键,
            gpu_model 文本,
            vram_gb 整数,
            price_per_hour 实数,
            location 文本,
            available 整数
        )
    """))

    conn.execute(text("""
        插入或替换到 gpu_servers 的值
        (1, 'RTX 4090', 24, 0.65, 'US-East', 1),
        (2, 'RTX 4090', 24, 0.70, 'EU-West', 1),
        (3, 'A100 80G', 80, 2.50, 'US-West', 1),
        (4, 'H100 80G', 80, 4.20, 'US-East', 0),
        (5, 'RTX 3090', 24, 0.35, 'Asia-Pacific', 1),
        (6, 'RTX 3080', 10, 0.20, 'EU-East', 1),
        (7, 'A100 40G', 40, 1.50, 'US-East', 1)
    """))
    conn.commit()

# 创建 LlamaIndex 的 SQL 数据库包装器
sql_database = SQLDatabase(engine, include_tables=["gpu_servers"])

# 自然语言到 SQL 的查询引擎
query_engine = NLSQLTableQueryEngine(
    sql_database=sql_database,
    tables=["gpu_servers"],
)

# 使用自然语言查询数据库
nl_queries = [
    "目前最便宜的 GPU 服务器是什么？",
    "显示所有显存超过 40GB 的 GPU 服务器",
    "RTX 4090 服务器的平均小时价格是多少？",
    "哪些地点有可用的 GPU 服务器？",
    "按价格列出所有可用的 A100 服务器",
]

for query in nl_queries:
    print(f"\n💬 自然语言： {query}")
    response = query_engine.query(query)
    print(f"📊 回答： {response}")
    if hasattr(response, 'metadata') and 'sql_query' in response.metadata:
        print(f"🔧 SQL: {response.metadata['sql_query']}")
```

***

## invokeai.yaml 配置文件

### Docker Compose（完整 LlamaIndex 堆栈）

```yaml
version: '3.8'

services:
  ollama：
    image: ollama/ollama:latest
    container_name: ollama
    runtime: nvidia
    ports:
      - "11434:11434"
    volumes:
      - ollama_models:/root/.ollama
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    restart: unless-stopped

  chromadb：
    image: chromadb/chroma:latest
    container_name: chromadb
    ports:
      - "8001:8000"
    volumes:
      - chroma_data:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
      - ANONYMIZED_TELEMETRY=FALSE
    restart: unless-stopped

  llamaindex-api：
    build:
      context: .
      dockerfile: Dockerfile
    container_name: llamaindex-api
    ports:
      - "8000:8000"
    volumes:
      - ./data:/workspace/data
      - ./indices:/workspace/indices
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - CHROMA_HOST=chromadb
      - CHROMA_PORT=8000
      - LLM_MODEL=llama3:8b
      - EMBED_MODEL=nomic-embed-text
    depends_on:
      - ollama
      - chromadb
    restart: unless-stopped

volumes:
  ollama_models：
  chroma_data：
```

### 关键配置变量

| 设置                        | 默认             | 描述                  |
| ------------------------- | -------------- | ------------------- |
| `Settings.llm`            | OpenAI GPT-3.5 | 用于生成的 LLM           |
| `Settings.embed_model`    | OpenAI Ada     | 嵌入模型                |
| `Settings.chunk_size`     | 1024           | 文本分块大小（以 token 为单位） |
| `Settings.chunk_overlap`  | 200            | 分块之间的重叠             |
| `Settings.num_output`     | 256            | LLM 响应中的最大 token 数  |
| `Settings.context_window` | 4096           | LLM 上下文窗口大小         |

***

## 1. 使用 SDXL-Turbo 或 SDXL-Lightning 以实现快速生成

### 1. 为吞吐量使用异步查询

```python
import asyncio
from llama_index.core import VectorStoreIndex

query_engine = index.as_query_engine(use_async=True)

async def batch_query(questions):
    tasks = [query_engine.aquery(q) for q in questions]
    return await asyncio.gather(*tasks)

questions = ["Q1?", "Q2?", "Q3?", "Q4?", "Q5?"]
answers = asyncio.run(batch_query(questions))
```

### 2. 混合检索（关键词 + 语义）

```python
from llama_index.core import VectorStoreIndex
from llama_index.core.retrievers import VectorIndexRetriever, KeywordTableSimpleRetriever
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.retrievers import QueryFusionRetriever

# 结合向量检索和关键词检索
retriever = QueryFusionRetriever(
    [
        index.as_retriever(similarity_top_k=5),  # 向量检索
        index.as_retriever(retriever_mode="keyword"),  # 关键词检索
    ],
    similarity_top_k=5,
    num_queries=3,  # 生成多个查询变体
    use_async=True,
    verbose=True,
)

query_engine = RetrieverQueryEngine(retriever=retriever)
```

### 3. 重新排序以提高质量

```python
from llama_index.core.postprocessor import SentenceTransformerRerank

# 在检索后添加重新排序步骤
reranker = SentenceTransformerRerank(
    model="cross-encoder/ms-marco-MiniLM-L-2-v2",
    top_n=3
)

query_engine = index.as_query_engine(
    similarity_top_k=10,  # 检索更多候选项
    node_postprocessors=[reranker]  # 重新排序至前 3
)
```

### 4. 流式以实现响应式 UI

```python
# 在生成时流式输出 token
streaming_engine = index.as_query_engine(streaming=True)
response = streaming_engine.query("Explain how Clore.ai works")

for token in response.response_gen:
    print(token, end="", flush=True)
```

***

## 故障排除

### 问题：嵌入模型无法连接到 Ollama

```bash
# 直接测试 Ollama 嵌入
curl http://localhost:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "test text"
}'
```

### 问题：索引构建速度慢

```bash
# 在嵌入期间监控 GPU 使用情况
watch -n1 nvidia-smi

# 使用较小的批量大小
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(
    文档，
    show_progress=True，
    # 以较小的批次插入
)
```

### 问题：找不到模块错误（ModuleNotFoundError），用于集成

```bash
# LlamaIndex 在 v0.10+ 中使用插件架构
pip install llama-index-llms-ollama
pip install llama-index-embeddings-ollama
pip install llama-index-vector-stores-chroma

# 检查已安装的包
pip list | grep llama
```

### 问题：超出上下文窗口

```python
# 减小分块大小
Settings.chunk_size = 512
Settings.chunk_overlap = 50

# 或使用具有更大上下文的模型
Settings.llm = Ollama(
    model="llama3:8b",
    context_window=8192  # 扩展上下文窗口
)
```

### 问题：查询返回不相关的结果

```python
# 增加相似度 top-k
query_engine = index.as_query_engine(similarity_top_k=10)

# 或使用更好的嵌入模型
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-large-en-v1.5"
)
```

***

## 文档

* **GitHub**: <https://github.com/run-llama/llama_index>
* **官方文档**: <https://docs.llamaindex.ai>
* **PyPI**: <https://pypi.org/project/llama-index>
* **集成**: <https://llamahub.ai>
* **Discord**: <https://discord.gg/dGcwcsnxhU>
* **博客**: <https://www.llamaindex.ai/blog>
* **CLORE.AI 市场**: <https://clore.ai/marketplace>

***

## Clore.ai 的 GPU 建议

| 在 Clore.ai 上的预估费用 | 开发/测试 | RTX 3090（24GB） |
| ----------------- | ----- | -------------- |
| \~$0.12/每 GPU/每小时 | 生产    | RTX 4090（24GB） |
| 生产环境 RAG          | 生产    | RTX 4090（24GB） |
| 高吞吐量嵌入            | 大规模   | A100 80GB      |

> GPU 服务器上。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。 [Clore.ai](https://clore.ai/marketplace) GPU 服务器。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。