# Embedding 后端配置

index1 默认使用 Ollama 生成向量，同时支持任何 OpenAI 兼容的 embedding 服务。

## 支持的后端

| 后端 | 配置值 | 说明 |
|------|--------|------|
| **Ollama**（默认） | `ollama` | 开箱即用，`ollama pull` 管理模型 |
| llama.cpp server | `openai_compat` | 轻量，直接加载 GGUF 模型 |
| LM Studio | `openai_compat` | GUI 桌面应用，适合个人使用 |
| vLLM | `openai_compat` | 高性能，适合服务器部署 |
| 任何 OpenAI 兼容服务 | `openai_compat` | 包括自建 API 网关 |

## 方式一：Ollama（默认，推荐）

无需配置，安装即用：

```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 下载 embedding 模型
ollama pull nomic-embed-text

# index1 开箱即用
index1 search "your query"
```

## 方式二：llama.cpp server

适合不想装 Ollama、想更轻量的用户。

### 步骤 1：安装 llama.cpp

```bash
# macOS
brew install llama.cpp

# Linux（编译安装）
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && cmake -B build && cmake --build build --config Release
```

### 步骤 2：下载 GGUF 模型

```bash
# 推荐：nomic-embed-text（768 维，270MB）
# 从 HuggingFace 下载
huggingface-cli download nomic-ai/nomic-embed-text-v1.5-GGUF \
  nomic-embed-text-v1.5.Q4_K_M.gguf \
  --local-dir ./models

# 或者用 wget
wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf \
  -O ./models/nomic-embed-text-v1.5.Q4_K_M.gguf
```

### 步骤 3：启动 llama.cpp server

```bash
# 启动 embedding server（端口 8080）
llama-server \
  --model ./models/nomic-embed-text-v1.5.Q4_K_M.gguf \
  --port 8080 \
  --embedding \
  --ctx-size 8192

# 验证服务
curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "nomic-embed-text", "input": "hello world"}'
```

应返回类似：
```json
{
  "data": [{"embedding": [0.012, -0.034, ...], "index": 0}],
  "model": "nomic-embed-text",
  "usage": {"prompt_tokens": 2, "total_tokens": 2}
}
```

### 步骤 4：配置 index1

```bash
# 切换到 OpenAI 兼容模式
index1 config embed_api openai_compat
index1 config ollama_url http://localhost:8080
index1 config embedding_model nomic-embed-text
index1 config embedding_dim 768

# 验证
index1 doctor
```

或直接编辑 `~/.claude-index1/config.yaml`：

```yaml
embed_api: openai_compat
ollama_url: http://localhost:8080
embedding_model: nomic-embed-text
embedding_dim: 768
```

### 步骤 5：使用

```bash
# 索引和搜索，用法完全不变
index1 index /path/to/project
index1 search "function definition"
```

## 方式三：LM Studio

### 步骤 1：安装 LM Studio

从 https://lmstudio.ai 下载安装。

### 步骤 2：加载 embedding 模型

1. 在 LM Studio 中搜索 `nomic-embed-text` 或 `bge-m3`
2. 下载模型
3. 进入 "Local Server" 标签
4. 加载模型并点击 "Start Server"
5. 默认端口：`1234`

### 步骤 3：配置 index1

```bash
index1 config embed_api openai_compat
index1 config ollama_url http://localhost:1234
index1 config embedding_model nomic-embed-text-v1.5
index1 config embedding_dim 768
```

## 切换回 Ollama

```bash
index1 config embed_api ollama
index1 config ollama_url http://localhost:11434
```

## 常见问题

### Q: 切换后端后需要重新索引吗？

**需要**，如果模型不同（维度不同），必须重新索引：

```bash
# 删除旧索引
rm ~/.claude-index1/knowledge.db

# 重新索引
index1 index /path/to/project
```

如果新旧模型维度相同（如都是 768），理论上可以混用，但不推荐（不同模型的向量空间不兼容）。

### Q: llama.cpp server 和 Ollama 性能差异？

差异很小（Ollama 底层就是 llama.cpp）。主要区别：
- Ollama：多一层 HTTP 转发，但有模型管理、自动加载
- llama.cpp：少一层，内存占用略低，需手动管理模型

### Q: 能用远程 embedding 服务吗？

可以，只要支持 OpenAI `/v1/embeddings` 接口：

```bash
index1 config embed_api openai_compat
index1 config ollama_url https://your-server.com
```

### Q: 不装任何 embedding 服务能用吗？

能。index1 会自动降级到 BM25 纯文本搜索（无向量搜索）。
