# 快速开始

## 1. 安装 index1

```bash
pipx install index1
```

> 也可以用 `pip install index1`，但推荐 pipx（隔离环境，不污染系统 Python）。

## 2. 选择 Embedding 后端

index1 支持多种 embedding 后端。运行交互式向导：

```bash
index1 init
```

```
选择 embedding 后端:

  [0] Ollama（推荐，开箱即用）
  [1] llama.cpp server
  [2] LM Studio
  [3] 其他 OpenAI 兼容服务
  [4] 跳过（纯 BM25 文本搜索，不需要 embedding）
```

### 方式 A：Ollama（推荐）

最简单，安装即用：

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

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

# 配置 index1（默认就是 Ollama，可跳过）
index1 init --backend ollama
```

### 方式 B：llama.cpp server

更轻量，不需要 Ollama：

```bash
# 安装
brew install llama.cpp     # macOS
# Linux: 从源码编译，见 https://github.com/ggerganov/llama.cpp

# 下载 GGUF 模型
mkdir -p ~/models
curl -L -o ~/models/nomic-embed-text-v1.5.Q4_K_M.gguf \
  "https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf"

# 启动 embedding server
llama-server \
  --model ~/models/nomic-embed-text-v1.5.Q4_K_M.gguf \
  --port 8080 --embedding --ctx-size 8192

# 配置 index1
index1 init --backend llama-cpp
```

### 方式 C：LM Studio

GUI 桌面应用，适合个人使用：

```bash
# 安装
brew install --cask lm-studio   # macOS
# 或从 https://lmstudio.ai 下载
```

1. 打开 LM Studio → 搜索 `nomic-embed-text` → 下载 `nomic-embed-text-v1.5-GGUF`（选 Q4_K_M，约 84MB）
2. 进入 **Developer** → **Local Server** → 按 `⌘L` 加载模型
3. 打开 **Status** 开关启动 Server（端口 1234）

```bash
# 配置 index1
index1 init --backend lm-studio
```

### 方式 D：跳过（纯文本搜索）

不安装任何 embedding 服务也能用。index1 自动降级到 BM25 纯文本搜索：

```bash
index1 init   # 选择 "跳过"
```

> 纯 BM25 模式没有语义搜索能力（中文搜英文代码等），但关键词搜索仍然可用。

## 3. 索引项目

```bash
cd your-project
index1 index ./src ./docs
```

输出示例：
```
索引完成: 42 已索引, 0 已跳过, 0 失败 (共 42 文件)
```

## 4. 搜索

```bash
index1 search "认证怎么实现的"
```

## 5. 验证环境

```bash
index1 doctor    # 一键诊断
index1 status    # 查看索引状态
```

## 快捷切换后端

随时切换，无需重新安装：

```bash
index1 init --backend ollama      # 切到 Ollama
index1 init --backend llama-cpp   # 切到 llama.cpp
index1 init --backend lm-studio   # 切到 LM Studio
```

或一条命令快捷切换（不选模型）：

```bash
index1 config --backend ollama
```

> 切换后端后如果模型维度不同，需要重建索引：`index1 index ./src --force`

## 下一步

安装完成后，将 index1 接入你的 AI 工具：

- [Claude Code 集成指南](integration-claude-code.md)
- [Cursor 集成指南](integration-cursor.md)
- [其他 AI Agent 集成指南](integration-other-agents.md)
- [Embedding 后端详细配置](embedding-backends.md)
