# 新增一个领域 QA — 一键部署指南

> 当前已部署：maritime (8080)、finance (8082)、travel (8081，是 API 不是 demo)

## 前置条件 (1 次性, 已就绪)

- vLLM Qwen2.5-32B 在 `127.0.0.1:8000` ✅
- bge-m3 embedding server 在 `127.0.0.1:11435` ✅
- `lambdagentpaas:latest` docker 镜像 ✅
- 统一的 `/home/67/qademo/app.py` (config-driven) ✅
- `/home/67/qademo/deploy_domain.sh` ✅
- `/home/67/qademo/instance.yml.template` ✅

## 添加新领域 (例: customs 海关)

### Step 1 — 准备知识库目录

```bash
mkdir -p /home/67/knowledge/customs/{raw,processed,wiki}

# 把原始文档放进 raw/
cp -r /path/to/customs_pdfs/* /home/67/knowledge/customs/raw/
```

### Step 2 — 复制 search/config 模块

```bash
# 直接从 maritime 复制 (代码完全相同, 仅 config.py 路径解析)
cp /home/67/knowledge/maritime/{search_engine.py,search_engine_v2.py,search_unified.py,graph_engine.py,config.py} \
   /home/67/knowledge/customs/
```

### Step 3 — 用 maritime 的索引脚本生成索引

```bash
cd /home/67/knowledge/customs
# 生成 BM25 + vector 索引 (复用 maritime 的 build 脚本)
python3 /home/67/knowledge/maritime/build_index.py   # 或对应的索引构建命令
```

应产生：
- `rag_index.json`               (BM25)
- `rag_index.keywords.json`
- `rag_vectors_v2.npy`           (vector)
- `rag_vectors_meta_v2.pkl`

### Step 4 — 写 instance.yml

```bash
cp /home/67/qademo/instance.yml.template \
   /home/67/knowledge/customs/instance.yml

# 把所有 {{DOMAIN}} 替换成 customs, {{PORT}} 替换成新端口 (如 8083)
sed -i 's/{{DOMAIN}}/customs/g; s/{{PORT}}/8083/g' \
   /home/67/knowledge/customs/instance.yml

# 编辑 systemPrompt + 5 个 examples + tagline (TODO 标记处)
vi /home/67/knowledge/customs/instance.yml
```

### Step 5 — 一键部署

```bash
/home/67/qademo/deploy_domain.sh customs
```

输出：
```
[1/6] Validating /home/67/knowledge/customs ...
[2/6] Parsing /home/67/knowledge/customs/instance.yml ...
       agent template: qaagent67lambda
       port:           8083
[3/6] Checking port 8083 availability ...
[4/6] No existing customs-qa — fresh deploy
[5/6] Starting customs-qa on port 8083 ...
[6/6] Waiting for http://127.0.0.1:8083/ to become ready ...

✅ customs-qa ready
   URL: http://qa.lambdagent.cn:8083/
```

### Step 6 — 访问

浏览器打开 `http://qa.lambdagent.cn:8083/` 即可。

---

## 常用维护命令

```bash
# 重启某个领域
/home/67/qademo/deploy_domain.sh customs --rebuild

# 查日志
docker logs -f customs-qa

# 改 demo 文案/示例 → 改 instance.yml → 直接重启容器即可 (无需 rebuild)
vi /home/67/knowledge/customs/instance.yml
docker restart customs-qa

# 列出所有 QA 实例
docker ps --filter name=-qa --format 'table {{.Names}}\t{{.Status}}'
```

## 一切配置都集中在 instance.yml

| 想改 | 改这里 |
|---|---|
| 网页标题/副标题/输入框提示 | `demo.title / demo.tagline / demo.placeholder` |
| 默认 5 个示例问题 | `demo.examples[]` |
| 端口 | `demo.port` |
| LLM 模型 | `model.name` |
| 检索权重 | `retrieval.weights.*` |
| RAG 系统提示词 | `systemPrompt` + `prompts.*` |
| 知识库路径 | `knowledge.baseDir` (其余自动派生) |

无需碰 `app.py`、`Dockerfile`、`docker run` 命令。