FDE 实战入门：把 AI 做进企业业务
JR Academy | 技术背景版 | 2026-11-18

你会运行什么
1. 不调用模型的权限实验：lab.py + evaluate.py。
2. 实际调用本机 Qwen 的知识助手：ai_app.py + evaluate_live.py。
3. 故障控制测试：test_ai_app.py，使用模拟响应，和真实生成分开记录。

本次真实验证
macOS Apple Silicon / Python 3.9.6 / llama.cpp b12503 / CPU 4 线程。
模型：Qwen2.5-0.5B-Instruct-GGUF，Q4_K_M，491,400,032 字节。
6 个教学用例通过：3 次实际生成，另 3 次在检索阶段返回状态。
真实停机 -> service_unavailable；重新启动 -> draft，演练通过。
离线权限检查 12/12；故障控制测试 8 个测试方法通过。
回答和版本、哈希在 reports/；事实核对见 manual-review.json。
这些只是小样本本地验证；没有云端 API、真实客户或生产环境验收。

一、先跑离线检查
需要 Python 3.9 或更新；配套 Python 代码只用标准库。
在解压后的 companion 目录打开终端：
  python3 lab.py --user ops_alice --question "差旅申请"
  python3 lab.py --user ops_alice --question "关账"
  python3 evaluate.py
  python3 -m unittest -v test_ai_app.py
预期：差旅引用 travel-v2；运营查关账为 no_evidence；离线评估 passed=12,total=12。
Windows 若没有 python3 命令，可使用 py -3。Windows 本次未实机验证。

二、准备本地模型
  python3 download_model.py
约 491 MB，会写入 models/ 并检查 SHA-256；网络不可用时稍后重试。
模型固定 revision：9217f5db79a29953eb74d5343926648285ec7e67
SHA-256：74a4da8c9fdbcd15bd1f6d01d621410d31c6fc00986f5eb687824e7b93d7a9db
官方模型与许可：https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF
模型权重不包含在配套 ZIP 中，按原仓库许可使用。

三、准备 llama.cpp
本书固定运行器版本 b12503：
https://github.com/ggml-org/llama.cpp/releases/tag/b12503
按自己的操作系统与处理器选择官方二进制包，解压后找到 llama-server。
本次 Apple Silicon 实测包：
https://github.com/ggml-org/llama.cpp/releases/download/b12503/llama-b12503-bin-macos-arm64.tar.gz
可将下面的 llama-server 替换成解压目录里的完整路径，含空格的路径加引号。
Windows 使用对应的 llama-server.exe；其他系统安装过程按官方说明。
不需要把下载文件复制到系统目录，也不要关闭系统安全控制。

在 companion 目录启动服务，以下一整行可直接复制：
  llama-server -m models/qwen2.5-0.5b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 8089 --alias northstar-qwen -c 2048 -ngl 0 -t 4
含义：模型文件、本机地址、端口、固定模型别名、上下文 2048、CPU 推理、4 线程。
等待日志出现 listening on http://127.0.0.1:8089，保持该终端运行。
若端口被占用，先确认占用程序；可改端口并用 ai_app.py --endpoint 指定新地址。

四、运行实际问答
另开终端，进入同一个 companion 目录：
  python3 ai_app.py --user ops_alice --question "差旅申请需要先做什么？"
  python3 ai_app.py --user fin_bob --question "关账检查码是什么？"
  python3 ai_app.py --user ops_alice --question "关账检查码是什么？"
  python3 evaluate_live.py > my-live-report.json
本次差旅回答：差旅申请应在预订前提交给直属经理审批。
检查 status=draft、citations[0].id=travel-v2，逐句与 citations.text 对照。
运营查关账应得到 no_evidence，model_called=false。
model_called=true 表示尝试请求模型；是否成功仍需看 status 和 error_code。
evaluate_live.py 是少量固定教学问题，不是未见问题的生产质量测评。

五、故障与恢复
在模型终端按 Ctrl+C，再运行差旅查询：应返回 service_unavailable，退出码 1。
重新启动服务，再问相同问题，检查草稿恢复且引用仍是现行资料。
真实停机与恢复记录在 reports/failure-drill.json。
test_ai_app.py 用模拟响应检查越界引用、截断、空回答等，不消耗模型请求。
CLI 的 invalid_input、unauthorized、service_unavailable 退出码为 1；
draft、no_evidence、needs_review 是可处理业务状态，退出码为 0。

六、完成示例与模板
worked-example/01-discovery.txt       D01 需求与未知项
worked-example/02-proposal.txt        D02 方案、替代路线与预算演算
worked-example/03-architecture.txt    D03 权限、模型与数据路径
worked-example/04-acceptance.csv      D04 需求与测试证据对照
worked-example/05-release.txt         D05 发布与回退记录
worked-example/06-pilot-plan.csv      D06 待执行的试点测量计划
worked-example/07-change.txt          D07 预算变化的建议方案
worked-example/08-handover.txt        D08 接手操作与演练步骤
worked-example/09-portfolio.txt       D09 如实说明项目能力与限制
templates/ 为可编辑空白模板；教学金额和阈值须按真实项目重新确认。

实现边界
- 检索为关键词匹配，没有向量库或语义检索；多份命中转人工是教学简化。
- --user 是可信本地夹具，不是认证；不能直接作为 Web API 身份参数。
- 生产身份应来自服务端验证会话，还需处理权限变更、日志、缓存、历史消息与审计。
- 引用 ID 检查只证明来源范围，不证明事实全部正确，生成结果统一返回 draft。
- 小模型可能重复、漏答或出错。它是降低教学资源门槛的选择，不是企业选型结论。
- 未证明提示注入抵抗、业务收益、生产可用性或跨平台兼容性。
配套代码与示例由本书编写，非厂商官方教程。llama.cpp 与 Qwen 按各自许可使用。
