needle2-chinese-finetuning

HexaLegato Needle 2 v1 — Raspberry Pi 5部署包

这是当前冻结最佳正式候选。它只生成Tool Call，不会执行Tool，也不会连接机器人API。

固定链路

外部Head v4 Top-1 → 强意图路由保护 → 中文数值归一化 → Decoder v3.5 W4 → 数值校正 → 参数省略保护 → 强命令漏调用补全

版本：cactus-needle 2.0.5、Native Engine 2.0.2、Head v4、Decoder v3.5、Schema v2.0、W4 scale1.0。

Pi 5安装

cd ~/hexalegato_needle2_v1
bash scripts/install_pi.sh

安装脚本面向Ubuntu 24.04 aarch64，使用系统版SentencePiece等依赖、离线ARM wheelhouse， 并安装包内冻结的官方Native Engine 2.0.2 ARM64库。默认wheelhouse路径为 ~/deployments/needle_pi_wheelhouse，可用NEEDLE_WHEELHOUSE=/路径覆盖。

离线wheelhouse随部署包另存为needle_pi_wheelhouse.tar；首次安装前执行：

mkdir -p ~/deployments/needle_pi_wheelhouse
tar -xf ~/deployments/needle_pi_wheelhouse.tar -C ~/deployments/needle_pi_wheelhouse

校验：

.venv/bin/python verify_install.py

单条命令：

.venv/bin/python infer.py --query "往前走半米"

准确率与性能

快速44条：

bash scripts/run_quick_test.sh

全量七套：

bash scripts/run_full_test.sh

输出位于results/<时间>/，包含逐条结果、准确率、路由准确率、invalid、P50/P90/P95/P99总延迟、Retriever/Decoder分段耗时、prefill/decode速度、Native峰值内存和系统版本。

七套数据为Common240、fresh480、Regression478、Family640、Numeric128、Numeric288及noarg48。测试只推理，不修改权重。

网页

bash scripts/start_web.sh

同一局域网浏览器访问http://<PI_IP>:8081。当前Pi地址为192.168.40.38，即：

http://192.168.40.38:8081

默认使用8081，是因为当前Pi已有web_gateway占用8080。可用PORT=端口 bash scripts/start_web.sh覆盖。

日志：web.log。停止：bash scripts/stop_web.sh。

网页和POST /api/infer展示最终JSON、Retriever候选、保护层修改、归一化内容、总延迟、分阶段延迟、decode速度和Native内存。

注意

• 第一次启动会编译ARM64 JAX Retriever，冷启动明显慢于后续请求；初始化时间单独记录，不混入稳态延迟。
• 服务没有账号认证，只应开放在可信局域网。
• 当前系统没有独立execution/refusal gate（执行/拒绝门）；即使输出看似正确，也不要直接驱动机器人。
• checksums.sha256与manifest.json用于确认传输完整性。
• 本机完整验收结果见PI5_ACCEPTANCE_REPORT.md。