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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.7
+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+
 
@@ -101,7 +107,8 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
-| `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
+| `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 + 图片转存 | 无 |
@@ -131,7 +138,8 @@ uv add sdpy-kit
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
 | `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 / score / noul） | `pip install "sdpy-kit[laya]"` |
+| `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]"` |
 
@@ -184,6 +192,16 @@ SQLITE_DB_PATH=./data/sqlite.db
 # LAYA_DEVICE=                  # 留空由 laya 自动选择
 # LAYA_HF_ENDPOINT=https://hf-mirror.com
 # 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 = 只用本地缓存，离线部署
 ```
 
 ### 环境变量 ↔ 能力对照表
@@ -269,9 +287,33 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `LAYA_DEVICE` | 无（不写入 config） | 推理设备（`cpu` / `cuda`）；不配置则由 laya 自动选择 |
 | `LAYA_HF_ENDPOINT` | `https://hf-mirror.com` | 检查点权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
 | `LAYA_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+| `LAYA_PRELOAD` | 无（不写入 config） | `true` 时创建 Router 后预热当前 `LAYA_MODEL`（只预热这一份） |
+| `LAYA_MAX_LOADED` | 无（不写入 config） | Router 同时驻留的检查点上限；不配置则用 laya 默认 2 |
+
+> 能力边界：`decide` 的 schema 仅支持 `enum` / `boolean` / 带 `minimum`+`maximum` 的数值字段
+> （数组、嵌套对象、联合类型不支持）；`decide` 中的 `score` 投影为最置信档位（argmax），
+> 不是序数期望值；`decide` 返回 `DecisionResult` 的 7 个键，`min_confidence` 低于阈值时字段值为 `None`；
+> 长文本用 `predict_long`，批量用 `decide_batch`（上游没有 `decide_long`）。
+> 多选用 `multi_choice`：每个候选标签独立做 `noul` 判断，返回 0-N 个标签；
+> `threshold`（默认 0.5）由调用方给定且未标定，可能出现 0 个或全部命中，请按 `probabilities` 复核。
 
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
-> `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
+> `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`
 
@@ -320,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)` |
@@ -783,9 +826,9 @@ shutdown()                                                     # 应用退出前
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
-| chat | `chat_complete(prompt, *, max_tokens=None, thinking=None) -> str` | 单轮对话（仅 user 消息） |
-| chat | `chat_ask(messages, *, max_tokens=None, thinking=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None, thinking=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `thinking_applied` |
+| chat | `chat_complete(prompt, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 单轮对话（仅 user 消息） |
+| chat | `chat_ask(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -804,9 +847,10 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读五个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `thinking_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
-token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
+迭代器在流结束后可读六个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
+见下文「结构化输出」）：
 
 ```python
 with AI.chat_stream(messages, max_tokens=450) as stream:
@@ -852,6 +896,52 @@ kit 不认识任何厂商字段名，请求体字段由档案 `thinking` 声明
 > 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
 > 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
 
+#### 结构化输出（JSON 模式，0.6.8）
+
+只要「合法 JSON 对象」用 `json_mode=True`；要约束字段用协议的 `response_format` 原样透传：
+
+```python
+answer = AI.chat_ask(messages, json_mode=True)          # 要求返回 JSON 对象
+
+fmt = {
+    "type": "json_schema",
+    "json_schema": {
+        "name": "extract",
+        "strict": True,
+        "schema": {
+            "type": "object",
+            "properties": {"tags": {"type": "array", "items": {"type": "string"}}},
+            "required": ["tags"],
+            "additionalProperties": False,
+        },
+    },
+}
+answer = AI.chat_ask(messages, response_format=fmt)     # 严格模式：schema 由你负责
+```
+
+- **缺省即注入（开箱即用）**：档案未声明 `structured_output` 时，`json_mode=True` 按 OpenAI 兼容默认写
+  `{"response_format": {"type": "json_object"}}`；**实测不支持该字段的端点必须在档案写
+  `"structured_output": false`**，否则会 400 并触发冷却。
+- **kit 不校验 JSON**：`json_mode=True` 只是「要求」，返回可能仍是散文或被截断的 JSON；schema 的生成、
+  校验、修补都不在 kit（`response_format` 写错即端点 400）。
+- **互斥**：`json_mode` 与 `response_format` 同时给 → `ValueError`；`json_mode=False` 与 `None` 等效（不注入）。
+- **跨候选降级**：切到已写 `false` 的备胎时本次调用退回普通文本，只在日志与 `json_mode_applied` 中体现。
+- **`stream=True` 兼容性未知**：部分端点会静默忽略 `response_format`，kit 不探测；流式 JSON 只能是半成品，kit 不做增量解析。
+
+`json_mode_applied`（流式迭代器属性 / `StreamStats` 字段）：`None` 未要求注入 / `True` 已注入 / `False` 要求了但该档案已关闭。
+
+**非流式收尾统计**：`ask` / `complete` 也接受 `stats=StreamStats()`（类名沿用历史，流式与非流式共用同一累加器），
+可读 `finish_reason` / `truncated` / `content_chars` / `reasoning_chars` / `json_mode_applied`：
+
+```python
+from kit.ai import StreamStats
+
+stats = StreamStats()
+body = AI.chat_ask(messages, json_mode=True, stats=stats)
+if stats.truncated:          # finish_reason 为 length / max_tokens
+    ...                      # 半截 JSON：直接重试或调大 max_tokens，不要尝试修复
+```
+
 > **非流式（`ask` / `complete`）的同款诊断**：provider 在截断时可能完全不返回 `content` 键，
 > 此时 kit 抛 `AIResponseError`，消息里带 `finish_reason` 与推理字符数（不再只报「content
 > 类型异常」，可直接判断是否被思考吃光）；正文为空串时返回 `""` 并打 `WARNING`。
@@ -876,7 +966,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., thinking=None, stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` 语义与门面一致 |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats: StreamStats \| None = None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats \| None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` / `json_mode` / `response_format` 语义与门面一致 |
 | `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性（**目标维度**，见下） |
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> str` |
@@ -1250,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：
@@ -1411,6 +1605,7 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
 | 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |
 | 档案级 | `thinking` | 思考开关的注入声明（0.6.7）：`{"arg": "thinking", "off": {"type": "disabled"}, "on": {"type": "enabled"}, "default": false}`。`arg` 是请求体顶层键名（不得占用 `model` / `messages` / `stream` / `max_tokens` / `temperature` 等保留键，配置期与运行期双重校验）；`off` / `on` 可为**任意 JSON 值**（双方都是 dict 时浅合并，否则整键替换）；`on` 缺省表示不能显式开启；`default` 为档案默认三态（`null` 不干预 / `false` 默认关 / `true` 默认开）。**未声明 = 不支持按调用切换**：逐调用 `thinking` 被忽略并告警（不报错、不影响候选链冷却）。kit 只做翻译，不含任何厂商名 |
+| 档案级 | `structured_output` | 结构化输出的注入声明（0.6.8）：`{"arg": "response_format", "json_mode": {"type": "json_object"}}`。`arg` 是请求体顶层键名（不得占用保留键）；`json_mode` 是 `json_mode=True` 时写入该键的取值。**未声明 = 用内置 OpenAI 兼容默认**（`response_format: {"type":"json_object"}`，开箱即用）；`"structured_output": false` 表示该档案不支持（`json_mode=True` 被忽略 + 告警，不发任何字段）。逐调用 `response_format` 原样透传优先于本声明。kit 只做翻译，不含任何厂商名 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 `thinking` 声明两种实测形态（按平台各自写入档案）：
@@ -1424,10 +1619,19 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 - **强制思考模型**（如只接受 `low/high/max` 的平台）不写 `thinking` 声明，逐调用开关会被忽略并告警；
 - 声明写错（`arg` 拼错、值形态不符）由厂商判定，可能 400 → 冷却；语义正确性由使用方的模型能力清单保证。
 
+`structured_output` 声明与关闭形态：
+
+```json
+"structured_output": {"arg": "response_format", "json_mode": {"type": "json_object"}}
+"structured_output": false          // 该端点实测不支持：json_mode=True 时忽略并告警
+```
+
 > **`extra_body` 的用法边界**：`extra_body` 是**档案级**的固有配置，无法按调用点切换。需要
 > 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`
 > （0.6.7 起）；仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
 > （门面侧 `AI.use("chat", "<档案名>")` 是进程级切换，非并发安全）。
+> 结构化输出同理：档案声明只给 `json_mode=True` 提供取值，按调用点变化的 schema 一律走
+> 逐调用 `response_format`（0.6.8 起）。
 
 ### 候选链切换语义（两类，勿混淆）