docs: 更新文档以反映 er_backend 代理重构、arm64 打包脚本与图标修复
- applyPlatformOverrides 章节改为描述统一走 er_backend 代理的现状， 删除已废弃的按 cardType 推导端口的旧逻辑说明 - AppConfig 里 voice 字段结构更新为实际的 asr/tts 嵌套结构 - 新增"应用图标打包踩坑"：files 数组遗漏 resources/icon.png、 桌面菜单图标需要装全常规尺寸这两个真实踩过的坑 - 版本号管理章节补充三处版本号解析保持一致的说明 - 打包命令统一指向验证过的 package:kylin:arm64:deb（真机 fpm bug 的 绕行方案），标注旧 package:kylin:arm64 在真机上会失败 - README 数据存储路径修正为实际的 ~/.config/elec_rag_ui/（原文档 写的 simple-rag-app 是错的，真机验证过实际路径） Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ssurui
parent
1cb953eeb3
commit
b512857629
49
CLAUDE.md
49
CLAUDE.md
@ -18,7 +18,7 @@
|
||||
- **向量数据库**：LanceDB（`@lancedb/lancedb`，嵌入式）
|
||||
- **本地向量化**：`@huggingface/transformers`（底层 `onnxruntime-node`）
|
||||
- **Markdown 渲染**：`marked`
|
||||
- **打包**：electron-builder（Linux AppImage + deb）
|
||||
- **打包**：electron-builder（Linux AppImage + deb）。**arm64 deb 在真机 Kylin 上走 electron-builder 自带的 fpm 路径必现 `tar failed (exit code 2)`**，实际可用的是 `scripts/package-kylin-arm64-deb.sh`（`npm run package:kylin:arm64:deb`），改用 `electron-builder --linux dir --arm64` 产出 unpacked 目录后手工 `dpkg-deb` 打包，已在真机验证
|
||||
|
||||
## 文件说明
|
||||
|
||||
@ -77,28 +77,31 @@ interface AppConfig {
|
||||
hardware: { cardType: 'er160' | 'er25' }
|
||||
batchQuestions: string[]
|
||||
batchWaitSeconds: number
|
||||
voice: { enabled: boolean; ttsRate: number; inputGain: number; [key: string]: unknown }
|
||||
voice: {
|
||||
asr: {
|
||||
enabled: boolean; executablePath: string; modelDir: string; numThreads: number
|
||||
vadSilenceTimeoutMs: number; vadEnergyThreshold: number; inputGain: number
|
||||
punctuationModelDir: string
|
||||
}
|
||||
tts: { enabled: boolean; voiceURI: string; pitch: number; rate: number; volume: number }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：本项目无 `chat` 字段（生成固定走 llamacppServer），无 `embed.baseUrl` / `embed.model` 用户配置。
|
||||
**注意**：本项目无 `chat` 字段（生成固定走 llamacppServer）。`embed.baseUrl` 字段存在但不对用户暴露，由 `applyPlatformOverrides` 固定推导。
|
||||
|
||||
## applyPlatformOverrides 逻辑
|
||||
|
||||
`getConfig()` 末尾调用，按计算卡型号覆盖关键配置：
|
||||
`getConfig()` 末尾调用。**自 `836d25c` 起，推理请求（生成 + 嵌入）统一走 er_backend 代理**（`ER_BACKEND_URL = 'http://127.0.0.1:17700'`），不再由前端按 cardType 自己推导 llama-server/embed-server 端口——服务实际监听哪个端口完全由 er_backend 后端配置决定，前端只认这一个代理入口：
|
||||
|
||||
**ER160（揽月 M50）**：
|
||||
- `chat.provider = 'llamacpp'`（内部字段）
|
||||
- `embed.provider` 若为 `ollama` 改为 `llamacpp`，`local` 保持不变
|
||||
- `llamacppServer.port = 8081`
|
||||
- `llamacppEmbed.port = 17701`
|
||||
- `embed.baseUrl = 'http://127.0.0.1:17701'`（内部推导）
|
||||
- `extraArgs` 为空时自动补默认值
|
||||
- `config.embed.baseUrl` 恒等于 `ER_BACKEND_URL`，与 cardType 无关
|
||||
- `generator.ts`、`statusHandler.ts` 的 `chat-test`、`erBackendHandler.ts` 全部请求 `ER_BACKEND_URL/v1/*`
|
||||
|
||||
**ER25（芯动力 RPP）**：
|
||||
- `embed.provider = 'local'`（强制，本地 CPU）
|
||||
- `llamacppServer.port = 8080`
|
||||
- `extraArgs` 为空时补 `'--ctk bf16 --ctv bf16 --no-warmup -ub 128'`
|
||||
`applyPlatformOverrides` 现在只负责按计算卡型号补默认启动参数（`extraArgs` 为空时才生效）：
|
||||
|
||||
**ER160（揽月 M50）**：`embed.provider` 若不是 `local` 则改为 `llamacpp`；`llamacppServer.extraArgs` 默认 `'--port 8081 --presence_penalty 1.5'`；`llamacppEmbed.extraArgs` 默认走 `DEFAULT_CONFIG` 里的值
|
||||
|
||||
**ER25（芯动力 RPP）**：`embed.provider = 'local'`（强制，本地 CPU）；`llamacppServer.extraArgs` 默认 `'--port 8080 --ctk bf16 --ctv bf16 --no-warmup -ub 128'`
|
||||
|
||||
## SettingsModal.vue 结构（精简后）
|
||||
|
||||
@ -167,7 +170,14 @@ asarUnpack: ['node_modules/@lancedb/**', 'node_modules/apache-arrow/**', 'node_m
|
||||
|
||||
### 版本号管理
|
||||
|
||||
版本号取自最近 git tag（`git describe --tags --abbrev=0`），无 git 环境时读 `.app-version` 文件（已加入 `.gitignore`，构建前生成）。
|
||||
版本号解析在三处保持一致：`electron-builder.config.ts`、`electron.vite.config.ts`、`scripts/package-kylin-arm64-deb.sh`。逻辑都是：`git describe --tags --abbrev=0`（去掉 `v` 前缀）→ 失败读项目根目录 `.app-version` 文件（同样去掉 `v` 前缀，已加入 `.gitignore`，PAD 部署等无 `.git` 环境下手动生成）→ 再失败分别 fallback 到 `'0.0.0'` / `'dev'` / `package.json` 版本号。**`.app-version` 缺失是 PAD 上界面显示版本号变成 `dev` 的常见原因**——rsync 部署到 PAD 时要记得同步这个文件。
|
||||
|
||||
### 应用图标打包踩坑
|
||||
|
||||
`resources/icon.png` 是图标源文件（1024×1024），`resources/icons/{16,24,32,48,64,128,256,512}x{同}.png` 是预生成的常规尺寸（`sips`/ImageMagick 生成，随图标一起更新）。两处坑：
|
||||
|
||||
1. **主进程窗口图标**：`src/main/index.ts` 用 `join(__dirname, '../../resources/icon.png')` 相对路径定位，`electron-builder.config.ts` 的 `files` 必须显式包含 `'resources/icon.png'`（默认只有 `out/**/*`，不会自动带上）。
|
||||
2. **桌面菜单图标只装 1024×1024 不够**：不少桌面环境（如 UKUI）按常规小尺寸（48×48 等）查找图标，找不到就直接回退成缺省图标，不会从 1024 自动缩放。`scripts/package-kylin-arm64-deb.sh` 把 9 个尺寸全部装进 `hicolor/<size>x<size>/apps/`，另外在 `/usr/share/pixmaps/` 放一份兼容不认图标主题的老式菜单。装完新图标后需要**注销重登或重启**桌面 shell 才会刷新（图标缓存 `~/.cache/icon-cache.kcache`、`~/.cache/ksycoca5_*` 不会主动感知内容变化）。
|
||||
|
||||
## NPU 状态监控
|
||||
|
||||
@ -204,9 +214,10 @@ git push origin main
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev:linux # 开发模式（--no-sandbox）
|
||||
npm run package:kylin # 打包 x64（AppImage + deb）
|
||||
npm run package:kylin:arm64 # 打包 arm64（须在 ARM64 机器上，先安装系统 fpm）
|
||||
npm run dev:linux # 开发模式（--no-sandbox）
|
||||
npm run package:kylin # 打包 x64（AppImage + deb）
|
||||
npm run package:kylin:arm64 # 打包 arm64（须在 ARM64 机器上；真机 Kylin 上 deb 目标会因 fpm bug 失败）
|
||||
npm run package:kylin:arm64:deb # 打包 arm64 deb（推荐，已在真机验证；绕开 fpm bug，见上文"打包"条目）
|
||||
```
|
||||
|
||||
## 同步来源
|
||||
|
||||
22
README.md
22
README.md
@ -16,10 +16,12 @@
|
||||
|
||||
## 支持硬件
|
||||
|
||||
| 计算卡 | 嵌入方式 | 生成方式 | 生成端口 |
|
||||
|--------|---------|---------|---------|
|
||||
| **ER160**（揽月 M50 NPU） | llamacpp NPU（默认）或本地 CPU | llamacpp | 8081 |
|
||||
| **ER25**（芯动力 RPP） | 本地 CPU（固定） | llamacpp | 8080 |
|
||||
| 计算卡 | 嵌入方式 | 生成方式 |
|
||||
|--------|---------|---------|
|
||||
| **ER160**（揽月 M50 NPU） | llamacpp NPU（默认）或本地 CPU | llamacpp |
|
||||
| **ER25**（芯动力 RPP） | 本地 CPU（固定） | llamacpp |
|
||||
|
||||
推理请求（生成 + 嵌入）统一经 er_backend 代理转发（`http://127.0.0.1:17700`），实际 llama-server 监听哪个端口由 er_backend 后端配置决定，前端不感知、也不需要按计算卡型号推导端口。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@ -93,17 +95,19 @@ npm run dev:linux # Linux（--no-sandbox，开发专用）
|
||||
## 打包
|
||||
|
||||
```bash
|
||||
npm run package:kylin # Linux x64，产出 AppImage + .deb
|
||||
npm run package:kylin:arm64 # Linux ARM64（在 ARM64 机器上执行）
|
||||
# 须先安装系统 fpm：sudo gem install fpm
|
||||
npm run package:kylin # Linux x64，产出 AppImage + .deb
|
||||
npm run package:kylin:arm64:deb # Linux ARM64 deb（推荐，须在 ARM64 机器/真机上执行，已验证可行）
|
||||
npm run package:kylin:arm64 # Linux ARM64（AppImage + deb），真机 Kylin 上 deb 目标
|
||||
# 走 electron-builder 自带 fpm 必现 tar failed，
|
||||
# 用 package:kylin:arm64:deb 代替
|
||||
```
|
||||
|
||||
## 数据存储
|
||||
|
||||
| 内容 | 路径 |
|
||||
|------|------|
|
||||
| 配置文件 | `~/.config/simple-rag-app/config.json` |
|
||||
| 向量数据库 | `~/.config/simple-rag-app/lancedb/` |
|
||||
| 配置文件 | `~/.config/elec_rag_ui/config.json` |
|
||||
| 向量数据库 | `~/.config/elec_rag_ui/lancedb/` |
|
||||
|
||||
## 许可证
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user