test/small-gpu-es9/docs/TEST_ENV_BRANCH_GUIDE.md

# 测试环境分支说明：`test/small-gpu-es9`
本文用于帮助开发同学理解 **测试环境部署分支** `test/small-gpu-es9` 与 `master` 的差异、部署要点，以及未来如何更容易与主干同步。
> 重要原则（目标态）  
> 该分支应尽量做到：**只引入部署配置差异，不引入业务/代码逻辑差异**。  
> 但历史上该分支在 `master` 分离后曾引入过多处代码改动，见下方“分离以来变动汇总”。
---
## 1. 分支定位与分离点
- **分支名**：`test/small-gpu-es9`
- **远程**：`origin/test/small-gpu-es9`
- **相对 `origin/master` 的 merge-base（分离点）**：
```bash
git fetch origin --prune
git merge-base HEAD origin/master
```
在当前仓库状态下，merge-base 为：
- `dc22700d04fd8b40978710b6ca6d3d016a66318b`
> 说明：`origin/master` 已继续向前推进，测试分支需要定期同步主干，否则会长期落后并产生更大合并成本。
---
## 2. 如何一键查看“从分离点以来”的全部差异（推荐命令）
### 2.1 仅看测试分支新增的 commits（不含 master 后续前进）
```bash
BASE=$(git merge-base HEAD origin/master)
git log --oneline ${BASE}..HEAD
```
### 2.2 仅看测试分支相对分离点的文件差异（最关键）
```bash
BASE=$(git merge-base HEAD origin/master)
git diff --name-status ${BASE}..HEAD
```
### 2.3 看 master 已经有、但测试分支还没有的 commits（用于评估落后程度）
```bash
git log --oneline HEAD..origin/master
```
---
## 3. 从分离点以来变动汇总（高层）
### 3.1 分支新增提交（当前共 5 个）
```text
e8d3bbb Add test env TEI GPU overrides examples
b3ffdc7 Sync legacy frontend entrypoint from 0a440fb
89fa3f3 Sync master portability fixes from f07947a
778c299 测试环境redis配置
b423bf4 测试环境配置：关闭reranker，其余的都打开，对接本机es docker内的19200
```
### 3.2 文件层面的差异（按类别归纳）
> 下列列表来自 `git diff --name-status ${BASE}..HEAD` 的结果归类；不在本文粘贴文件内容，避免将本地敏感信息写入文档。
#### A) 测试环境配置 / 示例文件
- `.env.example`（M）：补充 TEI 镜像 tag 选择说明（T4 用 `turing-*`）
- `.env.test.example`（A）：新增“测试环境 override 示例”（不含密钥）
- `config/environments/test.yaml`（A）：新增测试环境覆盖项（ES host/embedding/rerank 开关）
#### B) 翻译服务与本地模型相关
- `translation/`、`api/translator_app.py`、`requirements_translator_service.txt`、若干测试用例等（M/A）
- 这部分属于**代码逻辑差异**，与“仅配置差异”的目标不一致，未来同步主干时需要重点关注与取舍。
#### C) service_ctl / scripts / frontend / indexer 等
- `scripts/service_ctl.sh`（M）
- `scripts/*`（M/A）
- `frontend/static/js/app.js`（M）
- `indexer/product_enrich.py`（M）
- `models`（D）
以上同样属于**代码差异**（历史原因），并非纯部署配置差异。
#### D) `.env` 与备份文件（敏感风险提示）
- `.env`（M）以及 `.env.bak.*` / `.env.backup.*`（A）
这些文件通常会包含敏感配置（如 DB/Redis 密码、token 等）。**原则上不应提交到版本库**。  
如果这些文件当前已经被 git 跟踪，建议后续做一次清理：将其从版本控制中移除，仅保留 `.env.example` / `.env.*.example` 这类无密钥模板。
---
## 4. 测试环境部署要点（与 master 的“常见差异点”）
### 4.1 Elasticsearch：使用本机 Docker 暴露的 19200 端口
测试环境常见配置为：
- `ES_HOST=http://127.0.0.1:19200`
对应文件（示例/覆盖）：
- `.env.test.example`
- `config/environments/test.yaml`（`infrastructure.elasticsearch.host`）
### 4.2 Embedding（6005）后端走 TEI（8080）
链路：
- `embedding` 服务：`http://127.0.0.1:6005`（对外）
- TEI 服务：`http://127.0.0.1:8080`（embedding 的 text backend）
验证命令：
```bash
curl -sSf http://127.0.0.1:8080/health
curl -sSf http://127.0.0.1:6005/health
curl -sSf -X POST http://127.0.0.1:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '{"inputs":["health check"],"normalize":true}' \
  | python -c 'import sys,json; d=json.load(sys.stdin); print(len(d["embeddings"][0]))'
```
预期输出维度：`1024`。
### 4.3 TEI GPU：Tesla T4 需要 `turing-*` 镜像
在 Tesla T4（compute capability 7.5）上，TEI 若误用 `cuda-*` 镜像可能出现类似错误：
- `compute cap 75 is not compatible with compile time compute cap 80`
因此测试环境建议显式 pin：
- `TEI_IMAGE=ghcr.m.daocloud.io/huggingface/text-embeddings-inference:turing-1.9`
- `TEI_DEVICE=cuda`
- `TEI_DTYPE=float16`
这些已在 `.env.test.example` 中给出。
验证是否真的跑在 GPU：
```bash
nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv,noheader
```
应能看到 `text-embeddings-router` 占用显存。
### 4.4 Reranker / Fine-rank：测试环境通常关闭
测试环境覆盖（见 `config/environments/test.yaml`）：
- `rerank.enabled: false`
- `fine_rank.enabled: false`
这可减少 GPU/资源占用，并避免未配置时服务启动失败。
---
## 5. 测试环境部署建议流程（不含密钥）
1) 生成本地 `.env`（不要提交）：
```bash
cp .env.example .env
cat .env.test.example >> .env
```
2) 根据测试机实际情况补齐敏感项（仅本机）：
- `REDIS_PASSWORD` / `DB_PASSWORD` / `ES_PASSWORD` / `DEEPL_AUTH_KEY` 等
3) 拉起服务（按需）：
```bash
./scripts/service_ctl.sh up tei embedding backend indexer frontend eval-web
```
4) 逐项健康检查：
```bash
./scripts/service_ctl.sh status tei embedding backend indexer
```
---
## 6. 与主干同步策略（建议做法）
### 6.1 目标态：创建“干净的测试部署分支”
因为当前 `test/small-gpu-es9` 含有历史代码差异，后续主干同步成本会持续升高。推荐做法：
1. 从最新 `origin/master` 新建分支（例如 `test/deploy-es9-gpu`）。
2. 只 cherry-pick 与测试部署相关的**配置类提交**（例如 `.env.*.example`、`config/environments/test.yaml` 这类）。
3. 严格禁止提交 `.env`、`.env.bak*` 等包含敏感信息/本机路径的文件。
### 6.2 若继续使用当前分支：同步主干的基本步骤
```bash
git fetch origin --prune
git checkout test/small-gpu-es9
git merge origin/master
```
合并时重点关注冲突/回归风险区域：
- `translation/`（本地模型/依赖/服务行为）
- `scripts/`、`scripts/service_ctl.sh`
- `frontend/`、`indexer/`
---
## 7. 附：常用对照表（端口与服务）
| 服务 | 端口 | 说明 |
|------|-----:|------|
| Elasticsearch（测试 docker） | 19200 | `ES_HOST=http://127.0.0.1:19200` |
| TEI（text embeddings backend） | 8080 | `TEI_BASE_URL=http://127.0.0.1:8080` |
| embedding（text） | 6005 | `/embed/text`，后端转发 TEI |
| backend | 6002 | 搜索 API |
| indexer | 6004 | 索引 API |
| frontend | 6003 | 调试 UI |
| eval-web | 6010 | 评估 UI |