aha/docs/getting-started.zh-CN.md

# 快速入门

欢迎使用 AHA！本指南将帮助您快速上手。

## 快速开始（5 分钟）

### 1. 查看可用模型

```bash
aha list
```

### 2. 下载第一个模型

```bash
# 从下载一个小型文本模型开始
aha download -m qwen3-0.6b
```

### 3. 启动服务

```bash
# 启动 HTTP API 服务器
aha cli -m qwen3-0.6b
```

服务将在 `http://127.0.0.1:10100` 上启动

### 4. 发起第一个 API 调用

在新终端中：

```bash
curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-0.6b",
    "messages": [
      {"role": "user", "content": "你好，AHA！"}
    ],
    "stream": false
  }'
```

## 基本概念

### 什么是 AHA？

AHA 是一个本地 AI 推理引擎，具有以下特点：
- 在您的机器上运行模型（无需云 API）
- 支持多种模型类型（文本、视觉、音频、OCR、ASR）
- 提供 OpenAI 兼容的 API
- 模型下载后可离线工作

### 模型类别

| 类别 | 描述 | 示例模型 |
|------|------|----------|
| **文本** | 文本生成和对话 | Qwen3、MiniCPM4 |
| **视觉** | 图像理解 | Qwen2.5VL、Qwen3VL |
| **OCR** | 从图像中提取文本 | DeepSeek-OCR、Hunyuan-OCR |
| **ASR** | 语音转文本 | GLM-ASR、Fun-ASR、Qwen3-ASR |
| **音频** | 文本转语音 | VoxCPM、VoxCPM1.5 |
| **图像** | 图像处理 | RMBG2.0（背景移除） |

### CLI 命令

| 命令 | 用途 |
|------|------|
| `aha cli` | 下载模型并启动服务 |
| `aha serv` | 使用现有模型启动服务 |
| `aha download` | 仅下载模型 |
| `aha run` | 直接推理，无需服务器 |
| `aha list` | 列出可用模型 |

## 常见工作流程

### 文本生成

```bash
# 启动服务
aha cli -m qwen3-0.6b

# 在另一个终端中，发起请求
curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-0.6b",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手。"},
      {"role": "user", "content": "用简单的术语解释量子计算。"}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'
```

### 视觉理解

```bash
# 启动视觉模型
aha cli -m qwen3vl-2b

# 分析图像
curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3vl-2b",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "详细描述这张图片。"},
          {"type": "image", "image_url": {"url": "file:///path/to/image.jpg"}}
        ]
      }
    ],
    "stream": false
  }'
```

### OCR（文本提取）

```bash
# 启动 OCR 模型
aha cli -m deepseek-ocr

# 从图像中提取文本
curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ocr",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "提取这张图片中的所有文本。"},
          {"type": "image", "image_url": {"url": "file:///path/to/document.jpg"}}
        ]
      }
    ]
  }'
```

### 语音识别（ASR）

```bash
# 启动 ASR 模型
aha cli -m glm-asr-nano-2512

# 转写音频
curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-asr-nano-2512",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "转写这段音频。"},
          {"type": "audio", "audio_url": {"url": "file:///path/to/audio.wav"}}
        ]
      }
    ]
  }'
```

### 文本转语音

```bash
# 启动 TTS 模型
aha cli -m voxcpm1.5

# 生成语音
curl http://127.0.0.1:10100/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voxcpm1.5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "你好，这是 AHA 在说话。"},
          {"type": "audio", "audio_url": {"url": "https://package-release.coderbox.cn/aiway/test/other/%E5%93%AA%E5%90%92.wav"}}
        ]
      }
    ]
  }'
```

### 背景移除

```bash
# 启动 RMBG2.0 模型
aha cli -m rmbg2.0

# 移除图像背景
curl http://127.0.0.1:10100/images/remove_background \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rmbg2.0",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "image", "image_url": {"url": "file:///path/to/document.jpg"}}
        ]
      }
    ]
  }'
```

### 直接推理（无需服务器）

```bash
# 直接运行推理，无需启动 HTTP 服务器
aha run -m qwen3-0.6b \
  -i "写一首关于AI的俳句" \
  --weight-path ~/.aha/Qwen/Qwen3-0.6B
```

## 配置选项

### 更改端口

```bash
# 使用端口 8080 而不是默认的 10100
aha cli -m qwen3-0.6b -p 8080
```

### 绑定到所有接口

```bash
# 允许外部访问（请谨慎使用）
aha cli -m qwen3-0.6b -a 0.0.0.0 -p 8080
```

### 使用本地模型

```bash
# 跳过下载，使用现有模型
aha serv -m qwen3-0.6b \
  --weight-path /path/to/model \
  -p 8080
```

### 自定义保存目录

```bash
# 将模型下载到特定目录
aha download -m qwen3vl-2b -s /data/models
```

## 流式响应

对于chat/completions，无"stream"字段或"stream": true时使用流式传输，"stream": false为非流式：

```bash
curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-0.6b",
    "messages": [
      {"role": "user", "content": "给我讲个故事"}
    ],
    "stream": false
  }'
```

## 模型选择指南

### 文本生成
- **qwen3-0.6b**：快速、轻量级（~1.2 GB）
- **minicpm4-0.5b**：小型、高效（~1 GB）

### 视觉任务
- **qwen3vl-2b**：平衡性能（~4 GB）
- **qwen3vl-8b**：更高质量（~16 GB）

### OCR
- **deepseek-ocr**：通用
- **hunyuan-ocr**：适合中文文本
- **paddleocr-vl**：轻量级选项

### 语音识别
- **glm-asr-nano-2512**：快速、准确
- **fun-asr-nano-2512**：适合中文
- **qwen3asr-0.6b**：轻量级

### 文本转语音
- **voxcpm1.5**：高质量中文

### 背景移除
- **rmbg2.0**：最先进的结果

## 提示与最佳实践

### 1. 从小开始

从小型模型开始了解工作流程：
```bash
aha download -m qwen3-0.6b
```

### 2. 使用 GPU 加速

使用 GPU 支持构建以获得更好的性能：
```bash
# NVIDIA GPU
cargo build --release --features cuda

# Apple Silicon
cargo build --release --features metal
```

### 3. 预先下载模型

在网络良好时下载模型：
```bash
aha download -m qwen3vl-2b
```

稍后在没有网络的情况下使用：
```bash
aha serv -m qwen3vl-2b --weight-path ~/.aha/Qwen/Qwen3-VL-2B-Instruct
```

### 4. 管理磁盘空间

模型默认存储在 `~/.aha/` 中。如需要，清理：
```bash
# 检查磁盘使用情况
du -sh ~/.aha/*

# 删除旧模型
rm -rf ~/.aha/old-model-name
```

### 5. 监控资源

对于大型模型，监控您的资源：
```bash
# Linux
htop
nvidia-smi  # 对于 NVIDIA GPU

# macOS
活动监视器
```

## 故障排除

### 端口已被占用

```bash
# 使用不同的端口
aha cli -m qwen3-0.6b -p 8080
```

### 模型下载失败

```bash
# 重试更多次数
aha download -m qwen3vl-2b --download-retries 5
```

### 内存不足

```bash
# 使用更小的模型
aha cli -m qwen3-0.6b
```

## 后续步骤

1. 探索 [API 参考](./api.zh-CN.md) 了解详细的端点文档
2. 阅读 [CLI 参考](./cli.zh-CN.md) 了解所有命令选项
3. 查看 [架构与设计](./concepts.zh-CN.md) 了解 AHA 的工作原理
4. 如果您想贡献，请参阅 [开发指南](./development.zh-CN.md)

## 示例仓库

更多示例，请查看仓库中的 [tests](../tests/) 目录。

## 另见

- [API 参考](./api.zh-CN.md) - 完整的 API 文档
- [CLI 参考](./cli.zh-CN.md) - 命令行参考
- [安装指南](./installation.zh-CN.md) - 安装说明
- [开发指南](./development.zh-CN.md) - 贡献指南