# 配置参考

## 配置文件位置

index1 使用三层配置合并机制：

```
默认值 → 全局配置 → 项目配置
```

| 层级 | 路径 | 说明 |
|------|------|------|
| 默认值 | 内置 | 所有配置项都有默认值，零配置可用 |
| 全局配置 | `~/.claude-index1/config.yaml` | 用户级设置 |
| 项目配置 | `<项目>/.index1.yaml` | 项目级覆盖 |

项目配置 > 全局配置 > 默认值。

> 数据目录可通过 `INDEX1_HOME` 环境变量覆盖，默认 `~/.claude-index1/`。

---

## 全部配置项

### Embedding 后端

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `embed_backend` | `"onnx"` | 后端类型：`"onnx"` 或 `"ollama"` |
| `onnx_model` | `"BAAI/bge-small-en-v1.5"` | ONNX 模型名（fastembed） |
| `onnx_dim` | `384` | ONNX 模型维度 |
| `embed_api` | `"ollama"` | Ollama 后端 API 模式：`"ollama"` 或 `"openai_compat"` |
| `embedding_model` | `"nomic-embed-text"` | Ollama 模型名 |
| `embedding_dim` | `768` | Ollama 模型维度 |
| `ollama_url` | `"http://localhost:11434"` | Ollama 服务地址 |

**ONNX 是默认后端**，无需外部服务即可向量搜索。切换到 Ollama：

```yaml
# ~/.claude-index1/config.yaml
embed_backend: ollama
embedding_model: nomic-embed-text
embedding_dim: 768
```

或使用交互式配置：

```bash
index1 init --backend ollama
```

### 搜索参数

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `top_k` | `10` | 每次搜索返回结果数 |
| `rrf_k` | `60` | RRF 融合常数 |
| `rerank_enabled` | `false` | 是否启用重排序 |
| `rerank_model` | `"bge-reranker-v2-m3"` | 重排序模型 |

### 代码图

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `graph_enabled` | `true` | 搜索时是否启用代码图增强 |
| `graph_weight_semantic` | `0.6` | 语义相关度权重 |
| `graph_weight_pagerank` | `0.2` | PageRank 权重 |
| `graph_weight_structural` | `0.2` | 结构关联权重 |
| `graph_hop` | `2` | 图扩展跳数 |
| `graph_min_confidence` | `0.5` | 最低置信度阈值 |

### 认知模块

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `cognitive_enabled` | `true` | 是否启用认知记忆 |
| `cognitive_db_path` | `""` | 认知数据库路径（空 = `~/.claude-index1/cognitive.db`） |
| `cognition_model` | `"llama3.2:3b"` | 维护引擎用的 chat 模型 |
| `cognitive_decay_days` | `7` | 衰减周期（天） |
| `cognitive_gc_days` | `90` | 垃圾回收阈值（天） |
| `cognitive_gc_min_confidence` | `0.1` | GC 最低置信度 |
| `decay_beta` | `0.0` | 衰减公式参数：0=对数衰减（默认），>0=幂律衰减 |

### 存储

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `db_path` | `""` | 索引数据库路径（空 = `~/.claude-index1/knowledge.db`） |
| `collection` | `"default"` | 默认集合名 |
| `watch_paths` | `[]` | 监听路径列表（MCP reindex 使用） |

---

## 后端预设

使用 `index1 init --backend <name>` 或 `index1 config --backend <name>` 快捷切换：

| 预设 | embed_api | 默认地址 | 说明 |
|------|-----------|----------|------|
| `ollama` | `ollama` | `localhost:11434` | 推荐，开箱即用 |
| `llama-cpp` | `openai_compat` | `localhost:8080` | 轻量，直接加载 GGUF 模型 |
| `lm-studio` | `openai_compat` | `localhost:1234` | GUI 桌面应用 |

---

## 模型选择

### Ollama 模型档位

| 档位 | 模型 | 维度 | 磁盘 | 内存 | 适用场景 |
|------|------|------|------|------|----------|
| lightweight | `all-minilm` | 384 | ~45 MB | ~250 MB | 英文为主，低配机器 |
| standard | `nomic-embed-text` | 768 | ~270 MB | ~500 MB | 推荐默认，中英通用 |
| high_precision | `nomic-embed-text-v2-moe` | 768 | ~1 GB | ~1 GB | 高精度多语言 |
| chinese | `bge-m3` | 1024 | ~1.2 GB | ~1.2 GB | 中文最优，100+ 语言 |
| multilingual | `paraphrase-multilingual` | 768 | ~1 GB | ~1 GB | 50+ 语言通用 |

自动选择逻辑（按系统内存）：
- < 12 GB → lightweight
- 12–32 GB → standard
- >= 32 GB → high_precision

手动选择：

```bash
index1 init   # 交互式，包含模型选择
```

### ONNX 模型

默认使用 `BAAI/bge-small-en-v1.5`（384 维），由 fastembed 加载。更换模型：

```yaml
onnx_model: "BAAI/bge-base-en-v1.5"
onnx_dim: 768
```

> 更换 embedding 模型后必须重建索引：`index1 index --force <paths>`

---

## 配置示例

### 最简配置（零配置）

什么都不写。index1 使用 ONNX 后端 + 默认参数，开箱即用。

### Ollama 中文优化

```yaml
# ~/.claude-index1/config.yaml
embed_backend: ollama
embedding_model: bge-m3
embedding_dim: 1024
ollama_url: http://localhost:11434
```

### 项目级配置

```yaml
# <项目根>/.index1.yaml
collection: my_project
watch_paths:
  - ./src
  - ./docs
graph_enabled: true
top_k: 15
```

### 纯 BM25（无 embedding）

```yaml
embed_backend: ollama
ollama_url: http://localhost:99999  # 不存在的地址，强制降级
```

或者直接不安装 Ollama 和 fastembed，index1 自动使用 BM25-only 模式。
