sdpy-kit 0.6.8__tar.gz → 0.6.9__tar.gz

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.8
+Version: 0.6.9
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -26,14 +26,16 @@ Provides-Extra: ai
 Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Requires-Dist: python-dotenv>=1.2.4; extra == 'ai'
 Provides-Extra: all
+Requires-Dist: decima-ai>=2.5.1; extra == 'all'
 Requires-Dist: docxtpl>=0.20.2; extra == 'all'
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
 Requires-Dist: httpx>=0.28.1; extra == 'all'
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'all'
-Requires-Dist: laya>=0.4.12; extra == 'all'
+Requires-Dist: laya>=0.4.21; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
 Requires-Dist: marker-pdf>=2.0.0; extra == 'all'
 Requires-Dist: numpy>=2.5.4; extra == 'all'
+Requires-Dist: onnxruntime>=1.18; extra == 'all'
 Requires-Dist: pikepdf>=10.17.0; extra == 'all'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
 Requires-Dist: psycopg2-binary>=2.9.13; extra == 'all'
@@ -47,13 +49,17 @@ Requires-Dist: trafilatura>=2.3.1; extra == 'all'
 Provides-Extra: anydoc
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
+Provides-Extra: decima
+Requires-Dist: decima-ai>=2.5.1; extra == 'decima'
+Requires-Dist: huggingface-hub<2,>=1.5; extra == 'decima'
+Requires-Dist: onnxruntime>=1.18; extra == 'decima'
 Provides-Extra: docx
 Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
 Provides-Extra: docx-parse
 Requires-Dist: rc-docparser>=0.2.2; extra == 'docx-parse'
 Provides-Extra: laya
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'laya'
-Requires-Dist: laya>=0.4.12; extra == 'laya'
+Requires-Dist: laya>=0.4.21; extra == 'laya'
 Provides-Extra: marker
 Requires-Dist: marker-pdf>=2.0.0; extra == 'marker'
 Provides-Extra: md2doc
@@ -80,7 +86,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（`created_*` / `updated_*` / `deleted`）与软删除查询过滤；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / Decima 决策模型（选项乱序不变、置信度可门控） / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -102,6 +108,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / multi_choice 多选 / score / noul，另含 decide 多字段 / decide_batch 批量 / predict_long 长文本 | `laya` |
+| `kit.decima_kit` | `DecimaKit` | 决策模型：choice / score / noul / multi_choice（原生 rank）；选项乱序不变、置信度可门控；另含 predict / predict_long / brief / choice_batch（方法名与 `LayaKit` 对齐） | `decima` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.crawl.article_io` | `resolve_stem` / `save_article` 等 | 落盘公共层（目录命名 / 图片本地化 / YAML 头 / `meta.json`），三个 `*ArticleKit` 共用 | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
@@ -132,6 +139,7 @@ uv add sdpy-kit
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
 | `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
+| `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
 
@@ -186,6 +194,14 @@ SQLITE_DB_PATH=./data/sqlite.db
 # LAYA_HF_DISABLE_XET=true
 # LAYA_PRELOAD=                 # true 时只预热当前 LAYA_MODEL
 # LAYA_MAX_LOADED=              # 同时驻留检查点上限，留空用 laya 默认 2
+
+# Decima（决策模型，可选依赖 sdpy-kit[decima]）
+# DECIMA_MODEL=amyrmahdy/decima-small
+# DECIMA_PRECISION=int8         # int8（127 MB）/ fp32（489 MB）
+# DECIMA_THREADS=1              # batch-1 单线程最快，不建议调大
+# DECIMA_LANG=zh                # 仅 fa/ar 有实质归一化
+# DECIMA_HF_ENDPOINT=https://hf-mirror.com
+# DECIMA_LOCAL_ONLY=false       # true = 只用本地缓存，离线部署
 ```
 
 ### 环境变量 ↔ 能力对照表
@@ -284,6 +300,21 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` / `LAYA_PRELOAD` / `LAYA_MAX_LOADED` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
+**Decima** → `kit.decima_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `DECIMA_MODEL` | `amyrmahdy/decima-small` | HF repo id 或本地 ONNX 导出目录 |
+| `DECIMA_PRECISION` | `int8` | `int8`（127 MB，与 fp32 一致率 99.4%）/ `fp32`（489 MB） |
+| `DECIMA_THREADS` | `1` | ONNX Runtime intra-op 线程数；batch-1 单线程最快 |
+| `DECIMA_LANG` | `zh` | 传给 `Question.lang`；仅 fa/ar 有实质归一化 |
+| `DECIMA_HF_ENDPOINT` | `https://hf-mirror.com` | 权重下载入口（国内镜像）；置空则用官方源 |
+| `DECIMA_LOCAL_ONLY` | `false` | `true` 时只用本地缓存、不联网 |
+
+> `DECIMA_HF_ENDPOINT` 由 kit 在**导入 decima 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
+> `HF_HUB_DISABLE_XET=1` 由 kit 固定设置（国内镜像不支持 xet，会挂起）。
+> 不占用上游环境变量 `DECIMA_MODELS`（短名→路径覆盖）与 `DECIMA_DECODE`（自动解码）。
+
 **DeepSeek Search / Fetch** → `kit.crawl.deepseek_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -331,6 +362,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
 | `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.docs.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | `LAYA_HF_ENDPOINT` / `LAYA_HF_DISABLE_XET` | 仅在 `import kit.laya_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
+| `DECIMA_HF_ENDPOINT` / `HF_HUB_DISABLE_XET` | 仅在 `import kit.decima_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -1308,6 +1340,110 @@ if result.success:
 > 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为
 > 等宽 GFM（覆盖位留空，不输出 HTML `<table>`）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
 
+## kit.decima_kit —— 选项乱序不变、置信度可门控的决策模型
+
+122M 参数的 late-interaction 决策模型（int8 ONNX，单 CPU 线程，**不依赖 torch**）。
+每个选项独立编码、独立与 state 打分，因此**调换选项顺序不会改变答案**。
+
+```bash
+pip install "sdpy-kit[decima]"
+```
+
+```python
+from kit.decima_kit import DecimaKit
+
+state = "我们三月份被重复扣费了两次，请把重复的那笔退款。"
+
+# 单选题：选项顺序不影响结果
+r = DecimaKit.choice(
+    state,
+    "这封来信应该由哪个部门处理？",
+    {"账务": "账单、付款、退款", "技术": "故障、报错"},
+)
+r["decision"], r["answer_confidence"], r["probabilities"]
+
+# 是否题 / 评分题：第一个参数是待判断文本，第二个是命题
+DecimaKit.noul(state, "客户是否明确要求退款？")
+DecimaKit.score(state, "有多紧急？", ["不紧急", "较快处理", "紧急"])
+
+# 多选：原生 rank（每项独立 sigmoid），返回 0-N 个
+DecimaKit.multi_choice(state, "涉及哪些事项？", {"账务": "账单", "技术": "故障"})
+
+# 批量 / 多问题 / 长文本（方法名与 LayaKit 对齐）
+DecimaKit.choice_batch(
+    [state, "系统登录后一直报错。"], "哪个部门？", {"账务": "账单", "技术": "故障"}
+)
+raw = DecimaKit.predict(
+    state,
+    {"dept": {"type": "choice", "instructions": "哪个部门？",
+              "criteria": {"账务": "账单", "技术": "故障"}}},
+)
+DecimaKit.brief(raw)
+DecimaKit.predict_long(state * 50, {"r": {"type": "noul", "instructions": "是否要求退款？"}})
+```
+
+**返回字段**（`answer_confidence` 与 `LayaKit` 同名同口径）：
+
+| 字段 | 含义 |
+|------|------|
+| `decision` | 选中标签 / 序数期望值 / P(true) |
+| `answer_confidence` | top-1 概率 `max(p)`；**与 laya 同名同口径，但在本 Kit 上已标定、可做门控** |
+| `confidence` | 上游归一化置信度 `(k·max(p)−1)/(k−1)`，0~1（本 Kit 特有） |
+| `top_prob` | 原始 top-1 概率 `max(p)`，与 `answer_confidence` 相同 |
+| `probabilities` | 完整分布（`score` 的键为档位文本） |
+| `abstained` | 仅当传了 `min_confidence` 才有布尔值，否则为 `None` |
+
+**从 LayaKit 迁移**：`choice` / `score` / `noul` / `multi_choice` / `predict` / `predict_long` /
+`brief` / `router` / `unload` 同名同形，**只改 import 即可**；
+`decide`（schema 多字段）、`decide_batch`、`route` 是 laya 独有能力，本 Kit 不提供
+（`decide_batch` 显式抛 `NotImplementedError`，不会静默按单选跑）。
+
+### 与 `LayaKit` 的取舍（同环境实测）
+
+| 维度 | `LayaKit`（0.4.21） | `DecimaKit`（small 1.1） |
+|---|---|---|
+| 选项顺序导致的决策变化 | 中文工单 15.0%、文献 17% | **0%**（构造性） |
+| 门控覆盖率（放行准确率 ≥90%） | 25.0% | **52.5%** |
+| 中文工单分诊（40 条） | 0.700 | **0.750** |
+| 其中三个实质类（剔除「其他」，**推算**） | **0.867** | 0.667 |
+| JevBench 231 题 | 0.485 | **0.563** |
+| JevBench easy 48 题 | **0.896** | 0.812 |
+| JevBench hard 111 题 | 0.333 | **0.441** |
+| 磁盘（单检查点） | 617 MB | **137.5 MB** |
+| 依赖 | laya + torch | decima-ai + onnxruntime |
+
+**怎么选**：要「动态选项 + 顺序稳定 + 低置信转人工」用 `DecimaKit`；要「固定标签 + 简单明确分诊 +
+多字段 schema / GPU / 语言自动路由」用 `LayaKit`。两者**并列存在**，不互相替代。
+（`unload()` 两边都不该当内存回收 API：laya 实测只回落 0.4%，decima 回落约 50% 但也不回基线。）
+
+### 限制
+
+- **不提供默认门控阈值**：阈值随选项数与业务分布变化（4 选项约 0.80、6 选项约 0.85、二选一约 0.54），
+  必须用自有数据标定后传入 `min_confidence`。
+- **不适用于复杂推理**：JevBench 231 题 0.563，同基准 Jev 1.13.0 为 0.986；
+  `multi_hop` 0.28、`trap` 0.12。多跳策略判断请用大模型。
+- **`score` 最弱**（上游自认 benchmark 0.447）：只返回分布与期望值，不承诺准确性。
+- **`multi_choice` 的 0.5 阈值偏严**：`rank` 是每选项独立 sigmoid，概率普遍低于 laya 的 `noul`
+  （实测「账务 0.49 / 技术 0.12」会返回空列表）；先看 `probabilities` 再定 `threshold`。
+- **无 schema 多字段能力**：`decide` / `decide_batch` 留在 laya 侧。
+- **仅 CPU**；**无真实释放接口**：上游没有 `unload`，`onnxruntime` 的 `InferenceSession`
+  也没有 `close()`，`unload()` 只能丢引用 + GC。实测 WorkingSet 882.7 → 440.2 MB（约 50%），
+  不回基线，反复加载/释放以 14~29 MB/轮 累积——长驻进程建议只加载一次。
+- **窗口 512 token 且不可调**：超长文本截断，或传 `long="chunk"` / `predict_long` 分窗。
+  分窗固定「512 token 窗口 + 64 token 重叠」，`predict_long` 的 `window` / `stride` /
+  `batch_size` **只是为兼容 LayaKit 签名而接受，内部丢弃**（首次传参会告警一次）；
+  需要更细粒度扫描请自行切分文本后逐段调用。长文档优先只喂标题 + 摘要。
+- **倾向选兜底类**：业务有「其他 / 无法判定」类时表现正常（实测该类 10/10 全对），
+  但代价是三个实质类低于 laya（账务 0.50 vs 0.80、销售 0.60 vs 0.80）——
+  **业务没有兜底类时准确率会下降**。
+
+> 实测数据来自 `research/decima/`（中文工单 40 条由 AI 标注、未人工复核，只作方向参考；
+> JevBench 为本轮独立复现，231 题实测 0.563 与模型卡自报 0.571 同量级）。
+
+> **许可提示**：权重为 Apache-2.0，但 `decima-small` 训练数据含 CC BY-NC 数据集
+> （ANLI / XNLI / multilingual-NLI-26lang）。商用前请自行复核许可条款；纯商用数据版本为
+> `decima-base-clean`（体积与延迟更大，改 `DECIMA_MODEL` 后需重新验证效果）。
+
 ## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 
 零第三方依赖（标准库 `urllib` + 内置 HTML→Markdown 转换器），**无需 extra**，按需 import：

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/README.md

@@ -4,7 +4,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（`created_*` / `updated_*` / `deleted`）与软删除查询过滤；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / Decima 决策模型（选项乱序不变、置信度可门控） / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -26,6 +26,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / multi_choice 多选 / score / noul，另含 decide 多字段 / decide_batch 批量 / predict_long 长文本 | `laya` |
+| `kit.decima_kit` | `DecimaKit` | 决策模型：choice / score / noul / multi_choice（原生 rank）；选项乱序不变、置信度可门控；另含 predict / predict_long / brief / choice_batch（方法名与 `LayaKit` 对齐） | `decima` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.crawl.article_io` | `resolve_stem` / `save_article` 等 | 落盘公共层（目录命名 / 图片本地化 / YAML 头 / `meta.json`），三个 `*ArticleKit` 共用 | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
@@ -56,6 +57,7 @@ uv add sdpy-kit
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
 | `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
+| `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
 
@@ -110,6 +112,14 @@ SQLITE_DB_PATH=./data/sqlite.db
 # LAYA_HF_DISABLE_XET=true
 # LAYA_PRELOAD=                 # true 时只预热当前 LAYA_MODEL
 # LAYA_MAX_LOADED=              # 同时驻留检查点上限，留空用 laya 默认 2
+
+# Decima（决策模型，可选依赖 sdpy-kit[decima]）
+# DECIMA_MODEL=amyrmahdy/decima-small
+# DECIMA_PRECISION=int8         # int8（127 MB）/ fp32（489 MB）
+# DECIMA_THREADS=1              # batch-1 单线程最快，不建议调大
+# DECIMA_LANG=zh                # 仅 fa/ar 有实质归一化
+# DECIMA_HF_ENDPOINT=https://hf-mirror.com
+# DECIMA_LOCAL_ONLY=false       # true = 只用本地缓存，离线部署
 ```
 
 ### 环境变量 ↔ 能力对照表
@@ -208,6 +218,21 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` / `LAYA_PRELOAD` / `LAYA_MAX_LOADED` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
+**Decima** → `kit.decima_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `DECIMA_MODEL` | `amyrmahdy/decima-small` | HF repo id 或本地 ONNX 导出目录 |
+| `DECIMA_PRECISION` | `int8` | `int8`（127 MB，与 fp32 一致率 99.4%）/ `fp32`（489 MB） |
+| `DECIMA_THREADS` | `1` | ONNX Runtime intra-op 线程数；batch-1 单线程最快 |
+| `DECIMA_LANG` | `zh` | 传给 `Question.lang`；仅 fa/ar 有实质归一化 |
+| `DECIMA_HF_ENDPOINT` | `https://hf-mirror.com` | 权重下载入口（国内镜像）；置空则用官方源 |
+| `DECIMA_LOCAL_ONLY` | `false` | `true` 时只用本地缓存、不联网 |
+
+> `DECIMA_HF_ENDPOINT` 由 kit 在**导入 decima 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
+> `HF_HUB_DISABLE_XET=1` 由 kit 固定设置（国内镜像不支持 xet，会挂起）。
+> 不占用上游环境变量 `DECIMA_MODELS`（短名→路径覆盖）与 `DECIMA_DECODE`（自动解码）。
+
 **DeepSeek Search / Fetch** → `kit.crawl.deepseek_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -255,6 +280,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
 | `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.docs.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | `LAYA_HF_ENDPOINT` / `LAYA_HF_DISABLE_XET` | 仅在 `import kit.laya_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
+| `DECIMA_HF_ENDPOINT` / `HF_HUB_DISABLE_XET` | 仅在 `import kit.decima_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -1232,6 +1258,110 @@ if result.success:
 > 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为
 > 等宽 GFM（覆盖位留空，不输出 HTML `<table>`）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
 
+## kit.decima_kit —— 选项乱序不变、置信度可门控的决策模型
+
+122M 参数的 late-interaction 决策模型（int8 ONNX，单 CPU 线程，**不依赖 torch**）。
+每个选项独立编码、独立与 state 打分，因此**调换选项顺序不会改变答案**。
+
+```bash
+pip install "sdpy-kit[decima]"
+```
+
+```python
+from kit.decima_kit import DecimaKit
+
+state = "我们三月份被重复扣费了两次，请把重复的那笔退款。"
+
+# 单选题：选项顺序不影响结果
+r = DecimaKit.choice(
+    state,
+    "这封来信应该由哪个部门处理？",
+    {"账务": "账单、付款、退款", "技术": "故障、报错"},
+)
+r["decision"], r["answer_confidence"], r["probabilities"]
+
+# 是否题 / 评分题：第一个参数是待判断文本，第二个是命题
+DecimaKit.noul(state, "客户是否明确要求退款？")
+DecimaKit.score(state, "有多紧急？", ["不紧急", "较快处理", "紧急"])
+
+# 多选：原生 rank（每项独立 sigmoid），返回 0-N 个
+DecimaKit.multi_choice(state, "涉及哪些事项？", {"账务": "账单", "技术": "故障"})
+
+# 批量 / 多问题 / 长文本（方法名与 LayaKit 对齐）
+DecimaKit.choice_batch(
+    [state, "系统登录后一直报错。"], "哪个部门？", {"账务": "账单", "技术": "故障"}
+)
+raw = DecimaKit.predict(
+    state,
+    {"dept": {"type": "choice", "instructions": "哪个部门？",
+              "criteria": {"账务": "账单", "技术": "故障"}}},
+)
+DecimaKit.brief(raw)
+DecimaKit.predict_long(state * 50, {"r": {"type": "noul", "instructions": "是否要求退款？"}})
+```
+
+**返回字段**（`answer_confidence` 与 `LayaKit` 同名同口径）：
+
+| 字段 | 含义 |
+|------|------|
+| `decision` | 选中标签 / 序数期望值 / P(true) |
+| `answer_confidence` | top-1 概率 `max(p)`；**与 laya 同名同口径，但在本 Kit 上已标定、可做门控** |
+| `confidence` | 上游归一化置信度 `(k·max(p)−1)/(k−1)`，0~1（本 Kit 特有） |
+| `top_prob` | 原始 top-1 概率 `max(p)`，与 `answer_confidence` 相同 |
+| `probabilities` | 完整分布（`score` 的键为档位文本） |
+| `abstained` | 仅当传了 `min_confidence` 才有布尔值，否则为 `None` |
+
+**从 LayaKit 迁移**：`choice` / `score` / `noul` / `multi_choice` / `predict` / `predict_long` /
+`brief` / `router` / `unload` 同名同形，**只改 import 即可**；
+`decide`（schema 多字段）、`decide_batch`、`route` 是 laya 独有能力，本 Kit 不提供
+（`decide_batch` 显式抛 `NotImplementedError`，不会静默按单选跑）。
+
+### 与 `LayaKit` 的取舍（同环境实测）
+
+| 维度 | `LayaKit`（0.4.21） | `DecimaKit`（small 1.1） |
+|---|---|---|
+| 选项顺序导致的决策变化 | 中文工单 15.0%、文献 17% | **0%**（构造性） |
+| 门控覆盖率（放行准确率 ≥90%） | 25.0% | **52.5%** |
+| 中文工单分诊（40 条） | 0.700 | **0.750** |
+| 其中三个实质类（剔除「其他」，**推算**） | **0.867** | 0.667 |
+| JevBench 231 题 | 0.485 | **0.563** |
+| JevBench easy 48 题 | **0.896** | 0.812 |
+| JevBench hard 111 题 | 0.333 | **0.441** |
+| 磁盘（单检查点） | 617 MB | **137.5 MB** |
+| 依赖 | laya + torch | decima-ai + onnxruntime |
+
+**怎么选**：要「动态选项 + 顺序稳定 + 低置信转人工」用 `DecimaKit`；要「固定标签 + 简单明确分诊 +
+多字段 schema / GPU / 语言自动路由」用 `LayaKit`。两者**并列存在**，不互相替代。
+（`unload()` 两边都不该当内存回收 API：laya 实测只回落 0.4%，decima 回落约 50% 但也不回基线。）
+
+### 限制
+
+- **不提供默认门控阈值**：阈值随选项数与业务分布变化（4 选项约 0.80、6 选项约 0.85、二选一约 0.54），
+  必须用自有数据标定后传入 `min_confidence`。
+- **不适用于复杂推理**：JevBench 231 题 0.563，同基准 Jev 1.13.0 为 0.986；
+  `multi_hop` 0.28、`trap` 0.12。多跳策略判断请用大模型。
+- **`score` 最弱**（上游自认 benchmark 0.447）：只返回分布与期望值，不承诺准确性。
+- **`multi_choice` 的 0.5 阈值偏严**：`rank` 是每选项独立 sigmoid，概率普遍低于 laya 的 `noul`
+  （实测「账务 0.49 / 技术 0.12」会返回空列表）；先看 `probabilities` 再定 `threshold`。
+- **无 schema 多字段能力**：`decide` / `decide_batch` 留在 laya 侧。
+- **仅 CPU**；**无真实释放接口**：上游没有 `unload`，`onnxruntime` 的 `InferenceSession`
+  也没有 `close()`，`unload()` 只能丢引用 + GC。实测 WorkingSet 882.7 → 440.2 MB（约 50%），
+  不回基线，反复加载/释放以 14~29 MB/轮 累积——长驻进程建议只加载一次。
+- **窗口 512 token 且不可调**：超长文本截断，或传 `long="chunk"` / `predict_long` 分窗。
+  分窗固定「512 token 窗口 + 64 token 重叠」，`predict_long` 的 `window` / `stride` /
+  `batch_size` **只是为兼容 LayaKit 签名而接受，内部丢弃**（首次传参会告警一次）；
+  需要更细粒度扫描请自行切分文本后逐段调用。长文档优先只喂标题 + 摘要。
+- **倾向选兜底类**：业务有「其他 / 无法判定」类时表现正常（实测该类 10/10 全对），
+  但代价是三个实质类低于 laya（账务 0.50 vs 0.80、销售 0.60 vs 0.80）——
+  **业务没有兜底类时准确率会下降**。
+
+> 实测数据来自 `research/decima/`（中文工单 40 条由 AI 标注、未人工复核，只作方向参考；
+> JevBench 为本轮独立复现，231 题实测 0.563 与模型卡自报 0.571 同量级）。
+
+> **许可提示**：权重为 Apache-2.0，但 `decima-small` 训练数据含 CC BY-NC 数据集
+> （ANLI / XNLI / multilingual-NLI-26lang）。商用前请自行复核许可条款；纯商用数据版本为
+> `decima-base-clean`（体积与延迟更大，改 `DECIMA_MODEL` 后需重新验证效果）。
+
 ## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 
 零第三方依赖（标准库 `urllib` + 内置 HTML→Markdown 转换器），**无需 extra**，按需 import：

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.6.8"
+__version__ = "0.6.9"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/kit/ai/base_service.py

@@ -18,6 +18,7 @@ Author: Clark Chang
 """
 
 import json
+import logging
 import time
 from abc import ABC, abstractmethod
 from typing import ClassVar, Final, Self, cast, override
@@ -78,6 +79,12 @@ def _truncate(text: str, limit: int) -> str:
     return text
 
 
+def _dump_params(payload: JSONObject) -> str:
+    """请求体转单行日志文本（裁剪单字段与总长；仅 DEBUG 级别使用）。"""
+    dumped = json.dumps(_clip(payload), ensure_ascii=False)
+    return _truncate(dumped, _LOG_PAYLOAD_LIMIT)
+
+
 class BaseAIService[RequestT, ResponseT](ABC):
     """AI 服务基类（模板方法 + 泛型）。
 
@@ -150,7 +157,11 @@ class BaseAIService[RequestT, ResponseT](ABC):
         return None
 
     async def _call(
-        self, request: RequestT, *, deadline: float | None = None
+        self,
+        request: RequestT,
+        *,
+        deadline: float | None = None,
+        log: bool = True,
     ) -> ResponseT:
         """统一编排：构造请求体 → 发送 → 解析响应（含中文 info 日志）。
 
@@ -158,16 +169,21 @@ class BaseAIService[RequestT, ResponseT](ABC):
             request: 请求模型
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒），透传给
                 ``post_json`` 的重试预算检查；None 表示不限制
+            log: 是否记录本次调用的生命周期日志（默认 True）。``False`` 供
+                批量编排层（如 ``EmbeddingService.embed_texts``）静默内层
+                批次——省略 Start 与成功耗时，避免 3N+3 条重复；请求参数
+                仍受级别控制（DEBUG 可见，排障时批级请求体不丢），失败仍记
+                ERROR 便于定位到模型与实例
         """
         desc = self._log_desc()
         payload = self._apply_request_extras(
             self._apply_extra_body(self._build_payload(request)), request
         )
-        params = _truncate(
-            json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
-        )
-        logger.info(f"********** {desc} ********** Start")
-        logger.info(f"请求参数: {params}")
+        if log:
+            logger.info(f"********** {desc} ********** Start")
+        # 请求体序列化开销不小（批量文本可达数千字符），非 DEBUG 不构造
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"请求参数: {_dump_params(payload)}")
         start = time.perf_counter()
         try:
             data = await self._client.post_json(payload, deadline=deadline)
@@ -179,9 +195,10 @@ class BaseAIService[RequestT, ResponseT](ABC):
                 f"耗时 {time.perf_counter() - start:.1f}秒（失败：{exc}）"
             )
             raise
-        logger.info(
-            f"********** {desc} ********** 耗时 {time.perf_counter() - start:.1f}秒"
-        )
+        if log:
+            logger.info(
+                f"********** {desc} ********** 耗时 {time.perf_counter() - start:.1f}秒"
+            )
         return result
 
     async def close(self) -> None:

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/kit/ai/chat_service.py

@@ -17,20 +17,14 @@ Project: sdpy
 Author: Clark Chang
 """
 
-import json
+import logging
 import threading
 import time
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from typing import Any, ClassVar, Final, cast, override
 
-from kit.ai.base_service import (
-    _LOG_PAYLOAD_LIMIT,
-    BaseAIService,
-    _clip,
-    _truncate,
-    safe_get,
-)
+from kit.ai.base_service import BaseAIService, _dump_params, safe_get
 from kit.ai.exceptions import AIError, AIResponseError
 from kit.ai.profiles import _RESERVED_PAYLOAD_KEYS, ModelProfile
 from kit.ai.types import JSONObject
@@ -458,9 +452,6 @@ class ChatService(BaseAIService[ChatRequest, str]):
             self._apply_extra_body(self._build_payload(request)), request
         )
         desc = self._log_desc()
-        params = _truncate(
-            json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
-        )
         stats = stats if stats is not None else StreamStats()
         stats.thinking_applied = _resolve_thinking(self._profile, request.thinking)[1]
         arg, value, applied, _ = _resolve_structured_output(self._profile, request)
@@ -469,7 +460,9 @@ class ChatService(BaseAIService[ChatRequest, str]):
         stats.json_mode_applied = applied
         # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
         logger.info(f"********** {desc} ********** Start")
-        logger.info(f"请求参数: {params}")
+        # 请求体序列化开销不小（messages 常含长 prompt），非 DEBUG 不构造
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"请求参数: {_dump_params(payload)}")
         start = time.perf_counter()
         note = ""
         failed = False

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/kit/ai/embedding_service.py

@@ -162,6 +162,11 @@ class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
         batch_size: int | None = None,
         concurrency: int = _DEFAULT_CONCURRENCY,
     ) -> list[list[float]]:
+        """批量向量化（分批 + 限并发）。
+
+        日志只由本方法的「整批汇总」记录起止：内层批次传 ``log=False`` 静默，
+        避免 3N+3 条重复输出；单批失败仍由基类记 ERROR。
+        """
         if not texts:
             return []
 
@@ -183,7 +188,9 @@ class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
             async def _one(batch_index: int, chunk: tuple[str, ...]) -> None:
                 async with semaphore:
                     try:
-                        vectors = await self._call(EmbeddingRequest(list(chunk)))
+                        vectors = await self._call(
+                            EmbeddingRequest(list(chunk)), log=False
+                        )
                     except AIError as exc:
                         failures.append(f"批次 {batch_index}: {exc}")
                         return

{sdpy_kit-0.6.8 → sdpy_kit-0.6.9}/kit/config/kit_config.py

@@ -138,6 +138,41 @@ class Settings(BaseSettings):
         description="Router 同时驻留的检查点上限，None 沿用 laya 默认 2",
     )
 
+    # Decima 决策模型配置（int8 ONNX，仅 CPU；选项乱序不变、置信度已标定）
+    DECIMA_MODEL: str = Field(
+        default="amyrmahdy/decima-small",
+        description=(
+            "HF repo id 或本地 ONNX 导出目录"
+            "（含 encoder.onnx / scorer.onnx / decima.json / tokenizer）"
+        ),
+    )
+    DECIMA_PRECISION: str = Field(
+        default="int8",
+        description="ONNX 精度：int8（127 MB，与 fp32 一致率 99.4%）/ fp32（489 MB）",
+    )
+    DECIMA_THREADS: int = Field(
+        default=1,
+        ge=1,
+        description=(
+            "ONNX Runtime intra-op 线程数；上游实测 batch-1 单线程最快，不建议调大"
+        ),
+    )
+    DECIMA_LANG: str = Field(
+        default="zh",
+        description=(
+            "传入 Question.lang；仅 fa/ar 有实质文本归一化，"
+            "中文/英文等价但影响选项缓存键"
+        ),
+    )
+    DECIMA_HF_ENDPOINT: str = Field(
+        default="https://hf-mirror.com",
+        description="权重下载入口（默认国内镜像），置空则使用 HuggingFace 官方源",
+    )
+    DECIMA_LOCAL_ONLY: bool = Field(
+        default=False,
+        description="True 时只用本地缓存、不联网（离线部署）",
+    )
+
     # 文章抓取自检阈值（三个 *ArticleKit 共用）：正文长度低于该值时给出非致命提示
     # 0 表示关闭该判据（正文仍按实际长度全量返回，不做截断）
     CRAWL_MIN_CONTENT_CHARS: int = Field(