# 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 访问权限。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/rag-yu-xiang-liang-shu-ju-ku/llamaindex.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.