SafeContext Gateway

SafeContext Gateway 是一个面向政企云端大模型受控调用的、确定性且失败关闭的业务事实编译网关。当前 MVP 以住房公积金个人住房贷款申请条件预检为实验场景，公开数据全部为合成数据。

v2.2 将权威链路收敛为：本地身份隔离 → Schema Adapter → 规则 Oracle → 用途事实编译 → 出域门禁。云端大模型只能接收无显式身份和稳定编号、按当前用途裁剪的事实包；本地或云端模型均不拥有权威业务事实的最终裁决权。

当前证据支持三层结论：

• 确定性网关工程可行性：已支持。 结论仅适用于合成数据和冻结实验规则；
• 云端回答链原型可行性：初步支持。 尚未完成多轮对话、RAG 间接注入和回答反推的系统验证；
• 27B 在线候选事实职责：未支持。 27B 可继续研究离线 Schema 映射、字段抽取或人工辅助价值，但退出默认权威放行链路。

项目核心约束：

• 默认演示只运行本地确定性链路，云端调用必须显式启用；
• 当前实验 API 模型为阿里云百炼 qwen3.8-max；历史 RC11 评测对应 qwen3.5-27b；
• 模型建议必须经过人工批准或确定性验证，不能直接进入最终事实包；
• 本地规则引擎是给定实验规则的唯一 Oracle，不代表上海公积金业务真值；
• 最小事实包按回答意图和字段预算生成；
• 不接入任何真实用户数据；
• 所有结果只用于验证实验规则遵循和应用层控制，禁止解读为业务准确性、生产合规或完整安全认证。

本地运行

核心模块仅依赖 Python 标准库：

$env:PYTHONPATH = "src"
python -m safecontext_gateway.cli demo
python -m safecontext_gateway.cli evaluate --count 1800
python -m safecontext_gateway.cli frozen-evaluate
python -m safecontext_gateway.cli freeze-dataset
python -m safecontext_gateway.cli local-report
python -m safecontext_gateway.cli stability --case-count 100 --repeat-count 10
python -m safecontext_gateway.api --host 127.0.0.1 --port 8080

开发验收需安装测试依赖：

python -m pip install -e ".[dev]"
python -m pytest -q

也可使用容器启动：

docker compose up --build

容器只监听本机 127.0.0.1:8080，使用只读文件系统和非 root 用户运行。

千问配置

仓库提供 .env.example 配置模板。GitHub 用户克隆项目后执行：

# Windows PowerShell
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

然后编辑本地 .env，填写：

QWEN_BASE_URL=百炼控制台显示的OpenAI兼容Base URL
DASHSCOPE_API_KEY=你的百炼API Key
QWEN_MODEL=qwen3.8-max

检查配置是否完整：

python -m safecontext_gateway.cli config-check

输出只显示是否已配置和配置来源，不显示 API Key。.env 已被 Git 和 Docker 构建上下文忽略，只有空值模板 .env.example 会进入开源仓库。

配置优先级为：系统环境变量 > SAFECONTEXT_ENV_FILE 指定文件 > 项目根目录 .env > 程序默认值。服务器、GitHub Actions 和其他 CI 环境应使用 Secret 注入 系统环境变量，不创建或提交 .env。

如通过已安装的 wheel 在项目目录外运行，可指定配置文件：

$env:SAFECONTEXT_ENV_FILE = "D:\safecontext\.env"

云端单例验证：

python -m safecontext_gateway.cli demo --cloud

Qwen3.8 Max 实验配置说明

当前兼容实验 Adapter 可使用模型 ID qwen3.8-max。.env.example 与容器实验默认值 已切换到该模型，但这不代表 Max 是生产权威事实组件，也不代表目标信任域已经完成 本地辅助模型端点与云端回答模型端点的全部拆分。如需复现 RC11 历史实验，请显式设置 QWEN_MODEL=qwen3.5-27b，并使用独立输出与检查点，不要覆盖原始实验结果。

云端批量评测会产生 API 调用费用，只在显式添加 --cloud 时启用：

python -m safecontext_gateway.cli evaluate --count 30 --cloud

千问冒烟通过后，主实验应运行真正的 1,800 条冻结网关套件，而不是重新随机生成 1,800 条普通样本。套件中隐私、旧版本和故障注入样本会由本地网关阻断，因此实际 千问调用数少于 1,800；当前冻结套件预计为 1,180 次：

python -m safecontext_gateway.cli frozen-evaluate --cloud --output reports/qwen_frozen_rule_adherence.json
python -m safecontext_gateway.cli stability --cloud --case-count 100 --repeat-count 10 --output reports/qwen_stability_100x10.json

这两个长任务默认分别使用 reports/checkpoints/qwen_frozen_1800.jsonl 和 reports/checkpoints/qwen_stability_100x10.jsonl。每次完成模型调用后都会强制刷新 检查点；进程中断后重复执行原命令即可续跑。模型、Prompt、规则、数据集或稳定性 重复次数发生变化时，程序会拒绝复用旧检查点。也可通过 --checkpoint 指定其他 路径。

在完整冻结实验前，可先执行风险加权扩样。该命令按边界30%、缺失冲突30%、噪声 20%、人工回归10%、常见样本10%抽样，并在每例结束后写入检查点；中断后使用同一 命令会自动续跑，不重复已经完成的API调用：

python -m safecontext_gateway.cli risk-evaluate --count 150 --cloud
python -m safecontext_gateway.cli risk-report
python -m safecontext_gateway.cli freeze-risk-regression
python -m safecontext_gateway.cli regression-evaluate

默认检查点位于 reports/checkpoints/，该目录已被 Git 忽略，避免把本地调用过程、 模型原始候选或运行元数据误提交到开源仓库。

当前冻结组合的150例风险实验结果为126/150样本完全一致（84.0%），预注册等级 为D；主要弱点是缺失信息场景中的顶层聚合和擅自补全。详细结论见 reports/Qwen_Risk_150_Analysis.md。这不代表上海公积金业务准确性。

RC11 完整冻结实验已经完成：1,800/1,800 网关期望一致，400/400 隐私攻击在 出域前阻断；1,180 次计划模型调用中，候选样本完全一致 985 次（83.47%， 95% CI 81.25%—85.48%），逐事实一致 15,234/15,262（99.82%）。缺失/冲突 分层样本完全一致仅 52/200，确认主要短板是跨事实聚合。按预注册门槛仍为 D 级， 不得进入在线候选事实路径。完整结果和100×10稳定性结论见 reports/Qwen_Full_Evaluation_and_Stability_Final.md。

100×10稳定性也已完成：99/100案例十次签名全同，成对一致率99.8%；唯一波动为 一次供应商失败，成功候选之间未观察到内容变化。该集合由100个边界高风险案例 构成，不代表缺失/冲突场景稳定性。

外部生成的2,000条合成用户数据也完成了网关最终输出评测。V1严格案例一致率为 1,938/2,000（96.90%）；62条均为源适配器把UNKNOWN在缺失归一化前误作 整数或布尔解析。修复后使用同一冻结输入和同一Shadow Golden进行V2配对回归， 结果为2,000/2,000、无新增退化。V2是事后配对回归，不是新的独立盲测；该结果 衡量确定性网关最终输出，不改变千问27B候选能力83.47%、D级的结论。

修复后又使用新种子本地生成并预先冻结1,000条确认数据，与前2,000条业务画像重合 为0。首次评分暴露Shadow缺失值变体语义缺陷，原870/1,000结果按原样保留并标记为 Oracle无效；只修正Shadow后以新评测编号复跑，网关严格一致1,000/1,000，95% Wilson下界99.62%，57,540/57,540事实包叶子字段一致，40/40隐私最小化探针一致。 人工50条已在执行前固定并完成复核：49条一致、1条无法判断、0条确证不一致； 可判定样本一致率100%（49/49），全样本一致覆盖率98%（49/50）。无法判断的 CFM-0377涉及业务侧尚未确认的政策版本生效日期，未被强行算对或算错。

在修复 Adapter 后，qwen3.8-max 又对同一外部 2,000 条冻结输入运行候选实验： 1,925 条进入模型调用，候选完全一致 1,222/1,925（63.48%），逐事实一致率 98.41%， 缺失信息召回 46.58%，冲突分层完全一致 0/250；最终 2,000 条释放事实包仍全部来自 本地 Oracle，并与确定性 V2 结果逐条相同。该实验不能与 27B 的 83.47% 直接排序， 因为两组数据集和分层权重不同。详见 reports/Qwen38_Max_External_2000_Analysis.md。

失败案例会生成 datasets/frozen/sh_gjj_frozen_v1/qwen_risk_regression_v1.json，清单仅包含案例ID、 错误类型和版本证据，不包含模型正文。regression-evaluate默认使用本地oracle； 显式添加--cloud时才调用千问，并逐例写入可恢复检查点。

超过 30 例的云端实验会校验冻结文件哈希和非业务声明标识，但不要求业务专家 双签。业务双签仅在业务准确性声明、真实数据接入或业务发布前要求。

演示 API 默认只运行本地确定性链路。请求中显式设置 "use_cloud": true 时才调用千问；无论候选是否匹配，最小事实包都由本地规则 oracle 编译，模型候选不直接放行。

API 路由：

• POST /api/v1/datasets/generate
• POST /api/v1/evaluations/run
• POST /api/v1/facts/transform
• POST /api/v1/answers/generate
• POST /api/v1/mappings/propose
• POST /api/v1/mappings/compile

回答接口只接受同一网关进程已经验证并登记哈希的最小事实包。E2 映射编译必须 提供与候选清单哈希一致的人工批准记录。

论文与实验结论

• v2.2 中文论文（Markdown）
• v2.2 中文论文（Word）
• 专家意见采纳评估（Markdown）
• 专家意见采纳评估（Word）
• 上一版工程实验论文

论文区分三类不能混用的结论：模型候选规则遵循、确定性网关转换正确性、正式业务 政策正确性。本仓库目前只对前两类提供合成数据证据，不声明上海公积金正式审批 准确率，也不应直接用于真实用户或生产审批。

开源协作

• 贡献与实验变更要求见 CONTRIBUTING.md。
• 漏洞、密钥和隐私问题的报告方式见 SECURITY.md。
• 学术或工程引用信息见 CITATION.cff。

许可证

除另有明确说明的第三方材料外，项目自有代码、文档和合成数据采用 Apache License 2.0 发布。模型及服务商名称仍归其各自权利人所有； 本许可证不改变云服务、模型输出或第三方材料各自适用的条款。

方案文档

• docs/SafeContext_Gateway_PRD.md
• docs/SafeContext_Gateway_MVP_Development_Plan.md
• docs/SafeContext_Gateway_Metrics_Spec.md
• docs/SafeContext_Gateway_Rule_DSL_Spec.md
• docs/Qwen_Rule_Adherence_Experiment_Runbook.md
• docs/Second_Scenario_Paper_Migration.md
• docs/Real_Data_Phase_Compliance_Mapping.md
• reports/local_mvp_validation_v1.md
• reports/Qwen_Smoke_30_Analysis.md
• reports/Qwen_Risk_150_Analysis.md
• reports/Qwen_Full_Evaluation_and_Stability_Final.md
• reports/Qwen38_Max_External_2000_Analysis.md
• reports/External_2000_Multi_Judge_Final_V1.md
• reports/External_2000_V1_V2_Missing_Token_Fix.md
• reports/External_Conversion_MVP_Final_Decision.md
• reports/External_Confirmatory_1000_V1_Oracle_Discrepancy.md
• reports/External_Confirmatory_1000_V2_Shadow_Fix.md
• reports/External_Confirmatory_1000_Human_Review_Final.md
• reports/MVP_Completion_Audit.md
• reports/PRD_Acceptance_Matrix.md
• docs/SafeContext_Gateway_Paper_Review_Disposition_v2_2.md