From b512857629ffd1ac5e446315392319c1f7369401 Mon Sep 17 00:00:00 2001 From: ssurui Date: Sat, 22 Aug 2026 23:52:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=BB=A5=E5=8F=8D=E6=98=A0=20er=5Fbackend=20=E4=BB=A3=E7=90=86?= =?UTF-8?q?=E9=87=8D=E6=9E=84=E3=80=81arm64=20=E6=89=93=E5=8C=85=E8=84=9A?= =?UTF-8?q?=E6=9C=AC=E4=B8=8E=E5=9B=BE=E6=A0=87=E4=BF=AE=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 49 ++++++++++++++++++++++++++++++------------------- README.md | 22 +++++++++++++--------- 2 files changed, 43 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b64191a..7d7fd53 100644 --- a/CLAUDE.md +++ b/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/x/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，见上文"打包"条目） ``` ## 同步来源 diff --git a/README.md b/README.md index 5032ef7..7835b19 100644 --- a/README.md +++ b/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/` | ## 许可证