☁️云真 · 助手
内测说明 | 操作指南

0. 前置条件

• 一台满足硬件要求的 Windows 10/11 PC（推荐：i9-13900K / 128GB RAM / RTX 4090 / 4TB SSD）
• 已安装 Microsoft Flight Simulator 2024（或 2020），并可正常运行
• 已安装 Fenix A320 或 FlyByWire A32NX（至少一款机模）
• 已安装 SPAD.neXt（试用版即可）并启用远程控制（端口 18082，允许数据读取）
• 已安装 Python 3.11+ 及 pip
• （可选）Docker 环境用于 API 部署

1. 数据采集流水线

1.1 克隆项目代码

git clone https://gitee.com/your-org/cloudtruth-seeker.git
cd cloudtruth-seeker

1.2 安装 Python 依赖

pip install -r requirements.txt

如未提供 requirements.txt，手动安装：simconnect, pandas, chromadb, openai, pytest, flake8。

1.3 配置采集脚本

编辑 data_collection/spad_collector.py 中的变量：

SPAD_HOST = "127.0.0.1"          # 如果 SPAD.neXt 在另一台机器，改为其 IP
SPAD_PORT = 18082                # 默认端口
SAMPLE_INTERVAL = 0.1            # 10 Hz

1.4 启动采集

• 启动 MSFS 2024，加载 Fenix A320 至任意机场（冷舱或跑道）
• 启动 SPAD.neXt（确保远程控制已开启）
• 运行采集脚本：python data_collection/spad_collector.py

按 Ctrl+C 停止。数据保存在 training_data/raw/时间戳/flight_data.csv。

1.5 自动故障注入采集

python data_collection/auto_fault_session.py --fault ENG1_OIL_LEAK --duration 90

支持的故障列表见 auto_fault_session.py 中的 FAULT_MAP。

2. 情境生成与知识库构建

2.1 从 CSV 生成情境片段

python scripts/scenario_generator.py --input training_data/raw/ --output training_data/scenarios/

输出：scenarios_index.json（情境元数据） + 独立 CSV 片段。

2.2 构建 RAG 知识库

将手工编写的故障知识卡片（JSON 格式）放入 knowledge/knowledge_cards/（模板见 docs/knowledge_card_template.json）。

python knowledge/knowledge_base_builder.py

生成 Chroma 向量数据库于 knowledge/chroma_db/。

2.3 测试知识库检索

python tests/test_kb_retrieval.py --query "滑油压力下降"

应返回相关故障卡片内容。

3. 训练数据生成与模型微调

3.1 准备训练数据

将情境与专家标注回复合并，形成 ideal_samples.jsonl（格式见 docs/data_format.md）。

python scripts/convert_to_alpaca.py --input ideal_samples.jsonl --output train_alpaca.jsonl

3.2 微调模型（以 Qwen2-7B-Instruct 为例）

python scripts/finetune_qwen.py \
  --model_path /path/to/Qwen2-7B-Instruct \
  --data_path training_data/samples/train_alpaca.jsonl \
  --output_dir ./output/lora_cloudtruth \
  --num_epochs 3

3.3 合并模型（可选）

python scripts/merge_lora.py --base_model /path/to/Qwen2-7B-Instruct --lora_model ./output/lora_cloudtruth --output ./models/cloudtruth-merged

4. 部署云真 API 服务

4.1 启动 FastAPI 服务（开发测试）

cd deployment
pip install -r requirements-api.txt
python api_server.py --model ./models/cloudtruth-merged --port 8000

4.2 使用 Docker 部署（生产推荐）

docker build -t cloudtruth-api:latest .
docker run -d --gpus all -p 8000:8000 --name cloudtruth-api cloudtruth-api:latest

4.3 测试 API

curl -X POST http://localhost:8000/advise -H "Content-Type: application/json" -d '{"instruction":"发动机滑油压力低"}'

5. EFB 插件测试

5.1 前端构建

cd efb
npm install
npm run build

产物位于 efb/dist。

5.2 本地预览

npm run preview -- --port 5173

浏览器访问 http://localhost:5173，输入 API 地址即可对话。

5.3 嵌入 MSFS

将 efb/dist 文件夹复制到 MSFS 的 Community 模组目录，或使用注入工具。

5.4 测试故障推送

在 MSFS 中激活故障（如 Fenix 故障面板），观察 EFB 是否自动弹出建议。

6. 常见问题与排错

现象	可能原因	解决方法
SPAD.neXt 连接失败	远程控制未启用或端口被防火墙阻止	检查 SPAD.neXt 设置；关闭 Windows Defender 防火墙或添加入站规则
SimConnect 变量读取为 None	L:Var Bridge 未安装	重装 Bridge（SPAD.neXt → Settings → Simulator → Install Bridge）
故障注入无效果	变量名错误或机模未完全初始化	在 SPAD.neXt Data Monitor 中手动设置该变量为 1 验证
API 服务模型加载 OOM	显存不足	使用 4-bit 量化（修改 api_server.py 加载参数）
EFB 无法连接 API	CORS 或网络问题	确保 API 服务地址正确，且前端未使用 HTTPS 而 API 为 HTTP（开发环境）

7. 安全与脱敏注意事项

• 禁止提交任何 API 密钥、个人账号、真实 IP 地址、内网路径到版本控制系统。
• 配置文件使用 .env 文件存放敏感信息，并加入 .gitignore。
• 数据脱敏发布的训练数据集中，移除可能包含真实航班号、飞行员姓名、坐标的信息。
• 内部测试所有采集的 CSV 和模型权重仅限内部使用，不得外传。

8. 发布检查清单（内部测试版）

• ✅ 所有阶段脚本能在新安装的 Windows 10/11 上无报错运行。
• ✅ 采集脚本持续运行 1 小时以上无崩溃。
• ✅ 至少采集 3 种不同故障的数据（各 60 秒），成功生成情境片段。
• ✅ 知识库构建后，检索测试返回正确卡片。
• ✅ 微调模型后，对 5 个未见故障情境的回复质量经专家评分 ≥4.0。
• ✅ API 服务在 Docker 中稳定运行 24 小时，内存无泄漏。
• ✅ EFB 插件在 MSFS 中正常加载，点击“获取建议”能在 5 秒内收到回复。
• ✅ 编写完成内部测试报告（模板见 docs/test_report_template.md）。

9. 联系与反馈

📬 内部问题反馈：使用 Gitee Issues 标签 [测试]。
📝 技术文档更新：向 docs/ 目录提交 PR。
✈️ 本说明自签署之日起生效，版本 0.26.428 Beta (内模测试专用)。