LlamaIndex开发注意事项-马育民老师

# 介绍

**为了代码稳定、兼容、少踩坑：
LlamaIndex 只用来做它最强的事，其他全部绕开，直接用原生库！**

# 为什么 LlamaIndex API 不能大面积用？

- LlamaIndex **版本迭代极快**，v0 → v1 大量API直接废弃
- 你今天写的代码，下个月可能就报错
- 封装太多，**调试极难**
- 你想换模型、换向量库，会被它的API绑死

**桌面应用最怕：打包好的exe，过两个月不能用！**

---

# 最稳架构：LlamaIndex 只做最小必要功能

1. **文档读取 + 智能分块**
2. **高级检索（混合检索/重排/路由）**

其他所有东西 **全部不用 LlamaIndex API**

- 向量模型 → **直接用 sentence-transformers / OpenAI 原生**
- 向量库 → **直接用 Chroma / FAISS 原生**
- LLM调用 → **直接用 OpenAI / 通义千问 原生**
- 智能体 → **只用 LangChain**
- 记忆 → **只用 LangChain**

---

# 真正应该用的结构

### 1. 向量化（绝对不要走 LlamaIndex API）
```python
# 稳到爆的写法（原生）
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")
embedding = model.encode(text)
```

**不要写成：**

```python
# 不稳定，LlamaIndex随时改API
from llama_index.embeddings import HuggingFaceEmbedding
```

---

### 2. 向量库（绝对不要走 LlamaIndex API）
```python
# 稳
import chromadb
client = chromadb.Client()
```

**不要用 LlamaIndex 包装的向量库**

---

### 3. LLM 调用（不要走 LlamaIndex API）
```python
# 稳
from openai import OpenAI
client = OpenAI()
```

---

### 4. 只在这一处用 LlamaIndex（最稳定）
```python
# 只用它做：文档加载 + 高级检索
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex

# 读取文件（它最强）
documents = SimpleDirectoryReader("./docs").load_data()

# 把你自己的 原生embedding 传进去！！
index = VectorStoreIndex.from_documents(
    documents,
    embed_model=你的原生向量模型,  # 关键！不使用它的API
    vector_store=你的原生向量库    # 关键！完全自己控制
)

# 检索（它最强）
retriever = index.as_retriever()
```

### 关键点：
**LlamaIndex 只做“文档读取 + 检索”
向量模型、向量库、LLM 全是你自己控制的原生对象！**

这样：
- LlamaIndex 升级不影响你
- 你想换模型随时换
- 代码兼容 100% 稳定
- 桌面应用打包永远不会崩

---

# 最终最稳方案

### 只使用 LlamaIndex 3 个东西

1. `SimpleDirectoryReader`（读文件）
2. `VectorStoreIndex`（建索引）
3. `Retriever`（做检索）

### 其他全部绕开 LlamaIndex

- 向量 → 原生
- 向量库 → 原生
- LLM → 原生
- 智能体 → LangChain
- 记忆 → LangChain

原文出处：http://malaoshi.top/show_1GW3LlASqgvw.html