aps-kernel — Metis 谋序(APS 标准版)
运筹帷幄,谋定后动 —— 同衡·谋序·同枢,智造同频。 One Truth. One Plan. One Rhythm.
可嵌入的确定性排产内核:CP-SAT 精确求解、独立复核器、 工序-资源适配数据模型、设备槽位与班次日历、ε-约束 trade-off、headless CLI。
标准版 vs 专业版:本包只含可嵌入内核(无 UI / 无服务 / 无 LLM)。 甘特图前端、Web 控制台、AI 编排层、多租户 RLS、审批与 IM 通道 属专业版(Docker 镜像 + docker compose)。
🌐 官网:https://aps.zhinengti.online 家族:Nereus 同衡(数字孪生)· Metis 谋序(智能排产)· Hermes 同枢(物流调度)
⭐ 求解能力(横向基准,非自说自话)
在 16 个标准 FJSP 实例(ft/la/abz/orb/swv/ta/yn,来源 job_shop_lib MIT,
含文献公认最优值)上的实测:
| 实例 | 工单×机器 | SPT 基线 | 规则链 | CP-SAT | 文献最优 | vs 最优 |
|---|---|---|---|---|---|---|
| ft06 | 6×6 | 94 | 92 | 55 | 55 | +0.0% OPTIMAL |
| ft10 | 10×10 | 1530 | 1310 | 930 | 930 | +0.0% OPTIMAL |
| ft20 | 20×5 | 1513 | 1565 | 1165 | 1165 | +0.0% OPTIMAL |
| la01-05 | 10×5 | ~1000 | ~940 | 最优 | — | +0.0% OPTIMAL |
| abz5/6 | 10×10 | ~1700 | ~1600 | 1234/943 | 同 | +0.0% OPTIMAL |
| orb01 | 10×10 | 1489 | 1631 | 1082 | 1059 | +2.2% FEASIBLE |
| swv01/02 | 20×10 | ~2100 | ~2100 | 1495/1562 | 1407/1475 | +6% FEASIBLE |
| ta01/02 | 15×15 | ~2100 | ~2040 | 1233/1248 | 1231/1244 | +0.3% FEASIBLE |
| yn1 | 20×20 | 1547 | 1509 | 944 | 884 | +6.8% FEASIBLE |
11/16 达到文献最优,其余为大规模实例(20 秒预算不足,已如实标 gap)。 全部 11/11 独立复核通过。
python benchmarks/run_standard_bench.py --time-limit 30
当前状态
v1.20.0 —— 插单影响仿真 What-If(冻结已下达计划 + 重排 + 差分:谁被推后/谁从准时变拖期)+ 修冻结窗口在多窗口日历下判 INFEASIBLE 的真 bug。704 tests passed
| 模块 | 状态 | 关键能力 |
|---|---|---|
| 数据模型 P0 | ✅ | 工序-资源适配、空适配 ≠ 全设备可用、槽位 |
| 输入校验 P0 | ✅ | 三项 P0 准则 + 5 类检查 + 跨窗口工序预警(OP_WINDOW_TOO_SMALL,1.19.0) |
| 规则引擎 P1 | ✅ | 7 条规则(CR/EDD/SPT/WKWR/ATC/加权优先级/FIFO)+ 8 条链 |
| 日历与齐套 P2 | ✅ | 三日历求交、班次×资源×位置、工单级齐套布尔判定 |
| 换型规则链 P2 | ✅ | frePPLe 语义、无匹配 = 硬约束禁止、参数配置化、非对称 A→B≠B→A、矩阵格式 |
| CP-SAT 求解 P3 | ✅ | 字典序三级目标、容量池用 AddCumulative、冻结窗口 |
| 独立复核器 P4 | ✅ | 13 项真检查(含日历可行、模具互斥、技能资格、依赖满足、技能池容量、换型成本)、用输入重算不信任求解器 |
| Provenance P4 | ✅ | 快照 hash + 配置/源码/求解器版本 |
| CLI + 基准 P5 | ✅ | solve / benchmark / explain / chains / health / lotting |
| 冲突诊断 | ✅ | aps explain —— 最小冲突集 + 排不下原因 |
| ε-约束 trade-off | ✅ | 钉住交期预算,问 makespan 能压到多少 |
| 数据体检 | ✅ | aps health —— 四张底账逐项核对 + 可执行率估计 |
| 设备负载均衡旋钮 | ✅ | ε-约束第 3 个旋钮:钉住设备负荷不均衡度 |
| 工装模具约束 | ✅ | 跨设备 NoOverlap —— 冲压/注塑的头号约束,「机床等模具」不再是隐患 |
| 并行工序 | ✅ | 同 seq 的工序可同时执行(双人工位装配 / 多工位并行检测) |
| 序列相关换型 | ✅ | 换型真实占用产能(贪心+CP-SAT+复核器三方一致);A→B 与 B→A 可不同 |
| 换型成本 | ✅ | SetupRule.cost(元/次)→ Assignment.setup_cost,result.csv/甘特图/求解证书三个出口(1.17.0)。⚠️ 只计真换型,固定准备不计;四层费率由用户自配 |
| 换型矩阵格式 | ✅ | 直接贴工厂的换型矩阵表(行业通用格式),支持非对称与「禁止该换型」 |
| 拆批合批 | ✅ | 求解前预处理;工时按数量缩放;最小批量约束;合批守交期红线 |
| 人员技能资格 | ✅ | 工序声明技能 → 资源必须持证(1.6.0)。无证资源自动跳过;缺证时警告点名技能而非静默 |
| 工序依赖 | ✅ | predecessors + min_lag_minutes(1.7.0):跨工单拓扑就绪门 + 并行组内分层 + 前道完工地板;pred 未排 ⟹ 约束不生效(与 CP-SAT presence 语义一致) |
| 固定准备时间 | ✅ | setup_seconds(1.7.0):装夹/调机首件确认每单必付,占用区间 [start−P, end] 两求解器+复核器三方同口径 |
| 有效工时(能率/倍速) | ✅ | Resource.max_efficiency(设备能率上限)× OperationResource.efficiency(产品实际倍速),取 min 后折算工时(1.11.0)。2 腔注塑机跑 1 穴产品不会凭空快一倍 |
| 设备保养窗口 | ✅ | Resource.maintenance + calendar.maintenance_schedule(every_days=6, duration_days=1)(1.15.0)。日历层挖洞,两求解器+复核器天然同口径。⚠️ 周期按自然日近似,非按累计加工量 |
| 计划员入口(标准版用起来) | ✅ | aps demo 生成 CSV 模板 → Excel 填报 → aps solve --gantt/--csv/--certificate/--validation-report。全程不写代码(1.9.0) |
| 插单影响仿真(What-If) | ✅ | aps whatif --add delta.json:插一个急单,谁被推后/谁从准时变拖期/makespan 增多少。冻结已下达计划 + 重排 + 差分;冻结逐条核对(frozen_honored),CP-SAT 回退贪心时如实标注质量降级(1.20.0) |
| 行业分册(专业版规则库) | ✅ | src/aps_kernel/data/industries/*.yaml 可执行配置(随 wheel 分发,pip 用户 aps industries 直接可见)+ aps industries / solve --industry。注塑册(1.18.0:非对称换型矩阵 + 四层成本 + 保养 + 首检/烘料)、冲压册(1.19.0:同吨位 12min / 跨吨位 45min + 首件检测 2h)。每条参数标来源;应用后结果必须改变(测试锁住) |
三个设计立场
1. 诚实高于漂亮
OPTIMAL 只在真正证明最优时才标;FEASIBLE 必带真实 gap;
超时回退贪心解时 diagnostics["solver_fallback"] 明确标注来源;
全部未排时标 INFEASIBLE 而非 OPTIMAL(避免"看起来排好了")。
这直接对应论文《Formalize, Don't Optimize》的三个统计口径: 返回结果率 / 验证通过率 / 已返回中通过比例 —— 分母不同,不可混比。
2. 复核器是必需品,不是锦上添花
validator.independent_validate() 用输入数据重算(时长、槽位、日历、
换型、设备资格、技能资格、依赖满足),不信任求解结果自报的值。这不是防御性冗余 ——
开发中它抓到过槽位重叠 48 处而求解器报
OPTIMAL、 makespan = 2.3e18 的垃圾值(UNKNOWN时仍读未赋值变量)。
3. 基准必须公平
所有基线必须在相同约束集下比较。曾实现一个无视日历/工序先后的 SPT 基线, 得出「SPT 比 CP-SAT 还优」的颠倒结论(vsSPT = -203%)。
非法基线比没有基线更糟 —— 它会得出完全相反的结论。
🏗 分层架构:本包的位置
博客园《CP-SAT 排产、排程、排班》:
「APS(长周期规划)+ RTS/RTD(实时派工)双层架构是业界最佳实践」 「前一天做的排程,第二天全乱套」—— 排程 ≠ 派工 是经典误区
┌─────────────────────────────────────────────────┐
│ 上层(aps-platform / 本包之外) │
│ · MRP / 采购 / 库存 │
│ · APS 长周期计划(天/周) │
│ · RTS / RTD 实时派工(分钟级) ← 不在本包 │
│ · MES 执行回写 / 甘特图 UI │
└─────────────────────────────────────────────────┘
↕ ScheduleInput / ScheduleResult
┌─────────────────────────────────────────────────┐
│ aps-kernel(本包)—— 求解内核,不含流程 │
│ ✅ 数据模型 / 输入校验 │
│ ✅ 规则引擎(7 规则 + 8 链) │
│ ✅ CP-SAT 精确求解 + 贪心兜底 │
│ ✅ 冻结窗口(支持增量重排) │
│ ✅ 独立复核器(13 项) │
│ ✅ ε-约束 trade-off / 冲突诊断 / 基准 │
│ ❌ 不做派工、不做 UI、不做持久化、不含 LLM │
└─────────────────────────────────────────────────┘
⚠️ 为什么派工不在本包:派工是高频决策(分钟级刷新), 需要实时状态推送与人工干预;本包是低频决策(计划级), 追求确定性与可审计。把两者混在一个包里会同时失去两者。
⚠️ 本包负责「证明这个计划可执行」,不负责「生成甘特图」:
「排产的难点从来不是生成一个计划,而是证明这个计划在约束下可执行。」 —— 《LLM 不会给你最优排产,求解器会》
版本与兼容性
| 当前 | 1.20.0 —— 功能优先迭代期,API 会随功能演进 |
| 含义 | ⚠️ 1.0.0 的 API 冻结承诺已于 2026-10-17 取消,现按功能优先迭代 |
| 变更记录 | CHANGELOG.md —— 含破坏性变更与迁移动作 |
快速开始
⭐ 不会写 JSON?走这条路(1.9.0 起,给计划员用的入口)
pip install aps-kernel
# 1) 生成一套带示例数据的 CSV 模板(五张表)
aps demo mydata
# 2) 用 Excel 打开 mydata/ 下的 CSV,改成你的数据
# (jobs / operations / operation_resources / resources / calendar)
# 3) 求解 + 出甘特图 + 出可贴回 Excel 的结果 + 求解证书 + 复核报告
aps solve mydata/ --solver cpsat \
--gantt gantt.html --csv result.csv \
--certificate cert.txt --validation-report audit.html
# 4) 双击 gantt.html 看甘特图;audit.html 看独立复核的 13 项
三个产物各回答一个问题:
| 产物 | 回答 |
|---|---|
gantt.html |
计划长什么样 |
cert.txt |
这个解证明过吗(OPTIMAL 才写「已证明最优」,贪心解写「未经求解器验证」) |
audit.html |
独立复核器逐条验算的结果(不复用求解器任何中间结果) |
全程不需要写一行代码、不需要懂 JSON。五张表都是扁平 CSV, Excel 直接改;导入时缺列/类型错会点名到文件和列名,不会静默取默认值。
程序员路径(JSON / Python)
# 0) ⭐ 上线前先体检(核对工时/BOM/日历/换型矩阵四张底账)
aps health input.json --bom bom.json --inventory stock.json
# 1) 看内置规则链
aps chains
# 2) 求解(贪心,快)
aps solve input.json --chain default
# 3) 求解(CP-SAT,可证 OPTIMAL)
aps solve input.json --solver cpsat --time-limit 30 --gantt g.html --csv r.csv
# 4) 排不下时诊断原因(最小冲突集)
aps explain input.json
# 5) 基准验证(规则链 vs SPT vs CP-SAT)
aps benchmark --sizes 5,8,10 --chains default
aps health的退出码可直接接 CI:0可上线 /1需补数 /2阻断。
from aps_kernel import schedule, solve, CpSatOptions, independent_validate
# 贪心(快,不证明最优)
result = schedule(data, chain="default")
# CP-SAT(可证 OPTIMAL)
result, stats = solve(
data, options=CpSatOptions(time_limit_seconds=30, workers=8),
)
# 独立复核 —— 不信任求解器自报
checks = independent_validate(data, result)
assert all(ok for _, ok, _ in checks)
已知局限(诚实列出)
| 局限 | 说明 |
|---|---|
Job.due_date 只能表达天 |
✅ 已修复(v0.10.0):改为 `date |
| 交期需整日或整时 | 建议传 datetime;传 date 时按当天 00:00 算,不是「当天结束」—— 与部分 APS 的约定不同,转换时请留意 |
| 大规模 gap 仍大 | 实测(1.8.0,12 机 24 槽位,30 秒预算):CP-SAT 约 50 工单以内达 OPTIMAL,80 工单起超时回退贪心。已修的根因是 presolve 吃光预算(branches: 0,搜索从未运行)—— 熔断后 3 工单快 8 倍、20 工单从 UNKNOWN 变 OPTIMAL/6.9s。仍存限制:makespan 级本身在 30 秒内证不了最优(裸模型能 OPTIMAL,说明瓶颈在该目标的建模而非 presolve,属下一步优化对象) |
| ✅ 已修复(v1.4.0/1.5.0):换型时间真实占用产能(此前只记录不预留,计划现场执行不了);A→B 与 B→A 可不同(换下的模具比装上的更重是物理现实)。仍不支持「A→B→C 链式换型」的组合优化 | |
✅ 已修复(v1.5.0):split_input / merge_compatible_jobs。工时按数量线性缩放(不缩放时拆 4 批 makespan 120→480)。合批守交期红线,默认关闭 |
|
| 换型建模假设「同槽位同组成块」 | CP-SAT 的换型约束是充分非必要的(排除交错排法),非等价改写。换型极贵时该假设成立,但这是真实限制 |
| 工序必须放进单个日历窗口 | 两个求解器都不支持跨窗口工序(一道工序要整个放进一段连续可用时间):贪心会静默把它放进 unscheduled(计划仍报 FEASIBLE),CP-SAT 报 INFEASIBLE。1.19.0 起求解前有 OP_WINDOW_TOO_SMALL 预警点名(需求分钟 vs 最大窗口);根治见 docs/待办总账 P2-7 |
✅ 已修复(v1.15.0):Resource.maintenance + calendar.maintenance_schedule(日历层挖洞,两求解器+复核器同口径)。⚠️ 周期按自然日近似,非按累计加工量;「这副模还能用几次」的寿命计数仍未建模(冲压按冲次保养同属此列,P2-8) |
|
✅ 已修复(v1.16.0):ScheduleInput.skill_pool(厂级几人 = 几并行),CP-SAT/贪心/复核器三方同口径。⚠️ 多工种共享同一设备的并发上限仍未建模(专业版) |
|
| 无持久化状态 | 每次求解无状态,冻结窗口需由调用方传入 |
| 合成 demo 交期偏宽 | demo 默认交期 = horizon+5 天 ≫ makespan → 拖期恒为 0;验证拖期逻辑需改用紧交期 |
| 体检的可执行率是估计值 | 基于静态校验,不检查「现场是否会临时变更」。cp_sat_demo 实测 44%,本估计通常偏乐观 |
安装与依赖
- Python ≥ 3.11
- 运行时依赖:
ortools >= 9.12、PyYAML - 仅发 wheel(
py3-none-any),不发 sdist
License
MIT
Metadata
Release files for aps-kernel 1.20.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aps_kernel-1.20.0-py3-none-any.whl | Python 3 | none | any | Details for aps_kernel-1.20.0-py3-none-any.whl |
Release files / aps_kernel-1.20.0-py3-none-any.whl
| Download URL | aps_kernel-1.20.0-py3-none-any.whl |
|---|---|
| Size | 254.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5646d595417c0cccfe3c218f4e82931de3222ee18fc4d7df702177c44f977958
|
|
BLAKE2b-256 checksum How to use checksums |
fb0583936599f84492726b230017ccd798ecb1bdcbe61bf0778fd1f204f2336a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for aps-kernel 1.20.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.