yimo-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,853 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2026-11-03
21
+ """decima 决策模型工具类:选项乱序不变、置信度已标定的本地判定
22
+
23
+ decima(https://github.com/amyrmahdy/decima)是 122M 参数的 late-interaction 决策模型,
24
+ int8 ONNX 单 CPU 线程推理。与 `yimo/kit/ai/decision/laya.py` **并列**,二者不共享实现,
25
+ 但**同一能力同名**:
26
+
27
+ - **选项在构造上不参与彼此的打分**,因此调换选项顺序不会改变答案(实测 0% 变化;
28
+ laya 同场景 15%~17%);`score` 的档位顺序是问题的一部分,不适用;
29
+ - **置信度出场即已标定**(模型内置温度),可直接做阈值门控;laya 的置信度未标定,
30
+ 实测最高置信度样本本身判错。
31
+
32
+ 原语与 laya 一一对应:`choice` / `score` / `noul` / `multi_choice`(多选)/
33
+ `predict`(多问题)/
34
+ `predict_long`(长文本)/ `brief`(整形)/ `unload`(释放)。
35
+
36
+ **laya 独有能力,本 Kit 不提供**:`decide`(JSON schema 多字段)、`route`(语言路由)。
37
+ `decide_batch`(schema 驱动的批量多字段)在 laya 侧保留;
38
+ 本 Kit 的单选批量叫 `choice_batch`,
39
+ `decide_batch` 被显式定义为抛 `NotImplementedError`,避免「同名不同义」静默出错。
40
+
41
+ 返回字段(`choice` / `score` / `noul`):
42
+
43
+ - `decision`:选中标签 / 期望值 / P(true);
44
+ - `answer_confidence`:**与 laya 同名同口径**(都是 `max(p)`),
45
+ 本 Kit 上该值已标定、可做门控;
46
+ - `confidence`:上游归一化置信度 `(k·max(p)−1)/(k−1)`,0~1,本 Kit 特有;
47
+ - `top_prob`:原始 top-1 概率 `max(p)`,与 `answer_confidence` 数值相同
48
+ (保留两个名字是为兼容两套调用习惯);
49
+ - `probabilities`:完整分布(`score` 的键为档位文本);
50
+ - `abstained`:传了 `min_confidence` 才有值,否则为 `None`(不表示「已确认无需人工」)。
51
+
52
+ 关键用法:
53
+
54
+ - **不提供默认门控阈值**——阈值必须按业务数据自行标定,不同选项数下分布差异很大;
55
+ - `state` 支持 `str` / `dict` / `list`,非字符串按 JSON 序列化
56
+ (与本工具类不改写文本的纪律一致,
57
+ 序列化不是改写);
58
+ - 长文本用 `predict_long`(对齐 laya 的方法名)或各方法的 `long="chunk"`;分窗由模型的
59
+ `max_state_tokens` 与 `overlap` 决定,**`window` / `stride` 不生效**
60
+ (仅接受以兼容调用);
61
+ - **能力边界**:擅长「歧义兜底 + 顺序稳定 + 可门控」;简单明确分类不如 laya
62
+ (JevBench easy 0.812 vs 0.896),复杂多跳策略推理两者都不够(0.563 vs 0.986)。
63
+
64
+ 许可提示:`decima-small` 权重为 Apache-2.0,但其训练数据含 CC BY-NC 数据集
65
+ (ANLI / XNLI / multilingual-NLI-26lang)。商用前请自行复核;纯商用数据版本为
66
+ `decima-base-clean`(更大更慢,需改 `DECIMA_MODEL` 并重新验证)。
67
+
68
+ 配置走 `yimo.kit.config.Settings`(`.env` / 环境变量):`DECIMA_MODEL` / `DECIMA_PRECISION` /
69
+ `DECIMA_THREADS` / `DECIMA_LANG` / `DECIMA_HF_ENDPOINT` / `DECIMA_LOCAL_ONLY`。
70
+ **HF 相关环境变量必须在导入本模块前生效**(本模块导入即设置并加载 decima)。
71
+
72
+ 用法:
73
+ from yimo.kit.ai.decision import DecimaKit
74
+
75
+ result = DecimaKit.choice(
76
+ state="我们三月份被重复扣费了两次,请把重复的那笔退款。",
77
+ instructions="这封来信应该由哪个部门处理?",
78
+ criteria={"账务": "账单、付款、退款", "技术": "故障、报错"},
79
+ )
80
+ print(result["decision"], result["answer_confidence"])
81
+
82
+ 说明:本模块为可选依赖,需安装 `pip install "yimo-kit[decima]"`;首次使用会下载
83
+ int8 ONNX 权重(约 137 MB),模型常驻内存。
84
+
85
+ 关于 `unload()`:上游**没有**释放接口,`onnxruntime` 的 `InferenceSession` 也没有
86
+ `close()` / `__exit__`(1.31.1 实测),因此 `unload()` 只能「丢引用 + 触发 GC」。
87
+ 2026-11-03 实测(Windows,20 次推理后):WorkingSet 882.7 MB → 440.2 MB(回落约 50%),
88
+ 但不回落到基线,且三轮「加载→释放」有 14~29 MB/轮 的轻微累积。**不要把它当作
89
+ 可反复申请/释放重内存的手段**,长驻进程建议只加载一次。
90
+ """
91
+
92
+ import gc
93
+ import json
94
+ import os
95
+ import threading
96
+ from collections.abc import Sequence
97
+ from typing import Any
98
+
99
+ from yimo.kit.config.kit_config import get_settings
100
+ from yimo.kit.config.log_config import get_default_logger
101
+
102
+ logger = get_default_logger(__name__)
103
+
104
+ _settings = get_settings()
105
+
106
+ # HF 相关环境必须在导入 decima(进而导入 huggingface_hub)之前设置。
107
+ # 统一使用 setdefault:仅当用户未显式设置环境变量时生效。
108
+ if _settings.DECIMA_HF_ENDPOINT:
109
+ os.environ.setdefault("HF_ENDPOINT", _settings.DECIMA_HF_ENDPOINT)
110
+ # 国内镜像不支持 xet 存储后端,开启会导致权重下载挂起
111
+ os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
112
+
113
+ try:
114
+ from decima import Decima, Question
115
+ from decima.systemone import system_one
116
+ except ImportError as e: # pragma: no cover - 依赖缺失路径
117
+ raise ImportError(
118
+ "yimo.kit.ai.decision.decima 需要可选依赖,请安装:pip install yimo-kit[decima]"
119
+ ) from e
120
+
121
+ # 单问题封装使用的内部问题 id(调用方无需关心)
122
+ _QID: str = "answer"
123
+
124
+ # 决策原语的取值键(与上游 answers 条目一致,按优先级取第一个存在的)
125
+ _DECISION_KEYS: tuple[str, ...] = ("choice", "score", "noul")
126
+
127
+ # 支持的长文本聚合方式(与上游 longdoc.AGGREGATES 一致)
128
+ _AGGREGATES: tuple[str, ...] = ("max", "mean", "sum")
129
+
130
+ # 长文本分窗开关:上游只认 None 与 "chunk"
131
+ _LONG_VALUES: tuple[str | None, ...] = (None, "chunk")
132
+
133
+ # score 原语的档位上限(上游 ordinal head 按 10 档训练)
134
+ _SCORE_MIN_LEVELS: int = 2
135
+ _SCORE_MAX_LEVELS: int = 10
136
+
137
+ # 推理锁:串行化「加载 / 卸载 + 推理」全过程。
138
+ # 锁序恒为 _infer_lock → _model_lock,任何路径都不得反向获取,否则会死锁。
139
+ _infer_lock: threading.RLock = threading.RLock()
140
+
141
+ # `predict_long` 的分窗参数告警标记:只提示一次,避免热路径刷屏
142
+ _warned_ignored_window: bool = False
143
+ _warn_lock: threading.Lock = threading.Lock()
144
+
145
+
146
+ def _warn_ignored_window_params(
147
+ window: int | None, stride: int | None, batch_size: int | None
148
+ ) -> None:
149
+ """首次检测到被忽略的分窗参数时告警一次(之后静默)
150
+
151
+ decima 只有 `long="chunk"` 一个开关,窗口大小与重叠由模型配置和上游默认值决定,
152
+ 调用方传的 `window` / `stride` / `batch_size` 无法透传。
153
+ """
154
+ global _warned_ignored_window
155
+ if _warned_ignored_window:
156
+ return
157
+ with _warn_lock:
158
+ if _warned_ignored_window:
159
+ return
160
+ _warned_ignored_window = True
161
+ logger.warning(
162
+ "decima 的分窗固定为「模型窗口 512 token + 重叠 64 token」,"
163
+ f"window={window} / stride={stride} / batch_size={batch_size} 已忽略;"
164
+ "需要更细粒度的窗口扫描请自行切分文本后逐段调用"
165
+ )
166
+
167
+
168
+ class DecimaError(Exception):
169
+ """decima 决策异常(模型加载失败 / 推理失败 / 返回体不符合预期)"""
170
+
171
+
172
+ class DecimaKit:
173
+ """decima 决策模型工具类(无状态,方法均为 `classmethod`)
174
+
175
+ 模型为类级单例(加载开销大,必须复用),配置统一走 `yimo.kit.config.Settings` 的
176
+ `DECIMA_*` 配置项;**不改写任何输入文本**。
177
+
178
+ 方法命名与 `LayaKit` 对齐(同能力同名),
179
+ 差异只在 laya 独有能力(`decide` / `route`,
180
+ 本 Kit 不提供)与 decima 增量能力(`model` / `predict_many` / `choice_batch`)。
181
+ """
182
+
183
+ _model: Any = None
184
+ _model_lock: threading.Lock = threading.Lock()
185
+
186
+ # ------------------------------------------------------------------
187
+ # 模型生命周期
188
+ # ------------------------------------------------------------------
189
+ @classmethod
190
+ def model(cls) -> Any:
191
+ """惰性创建并缓存模型(进程内单例,线程安全)
192
+
193
+ Returns:
194
+ Any: `decima.Decima`(ONNX 运行时,不依赖 PyTorch)
195
+ """
196
+ with cls._model_lock:
197
+ if cls._model is None:
198
+ logger.info(
199
+ f"加载 decima 模型:{_settings.DECIMA_MODEL},"
200
+ f"精度={_settings.DECIMA_PRECISION},"
201
+ f"线程={_settings.DECIMA_THREADS},"
202
+ f"语言={_settings.DECIMA_LANG}"
203
+ )
204
+ cls._model = Decima.from_pretrained(
205
+ _settings.DECIMA_MODEL,
206
+ precision=_settings.DECIMA_PRECISION,
207
+ threads=_settings.DECIMA_THREADS,
208
+ local_files_only=_settings.DECIMA_LOCAL_ONLY,
209
+ )
210
+ return cls._model
211
+
212
+ @classmethod
213
+ def router(cls) -> Any:
214
+ """兼容别名:返回底层模型实例
215
+
216
+ 与 `LayaKit.router()` 同名同用途;差别是 decima 只有单个模型,
217
+ 不存在 laya 的多检查点 `Router` 管理。
218
+ """
219
+ return cls.model()
220
+
221
+ @classmethod
222
+ def unload(cls) -> None:
223
+ """释放模型引用(**伪卸载**:上游无释放接口,内存由 GC 与 ORT 决定何时归还)
224
+
225
+ 锁序与推理一致:先取推理锁等待在途推理结束,再取模型锁。
226
+ `gc.collect()` 放在锁外执行,避免长时间持锁阻塞其他推理。
227
+
228
+ 实际效果(2026-11-03 实测):WorkingSet 从 882.7 MB 回落到 440.2 MB(约 50%),
229
+ 但**不回基线**,反复加载/释放会以 14~29 MB/轮 累积。原因有三:上游没有释放
230
+ 接口、`onnxruntime` 的 `InferenceSession` 无 `close()`、ORT 默认启用 CPU
231
+ memory arena 会把释放的内存留在自己的池里。
232
+
233
+ 另注意:若调用方另存了 `model()` 的返回值,本方法不会使其失效。
234
+ """
235
+ released = False
236
+ with _infer_lock:
237
+ with cls._model_lock:
238
+ if cls._model is not None:
239
+ cls._model = None
240
+ released = True
241
+ if released:
242
+ gc.collect()
243
+ logger.info("decima 模型引用已释放(ONNX 内存由 GC 回收,不保证立即归还)")
244
+
245
+ # ------------------------------------------------------------------
246
+ # 内部工具
247
+ # ------------------------------------------------------------------
248
+ @staticmethod
249
+ def _state_text(state: str | dict[str, Any] | list[Any]) -> str:
250
+ """把 state 归一成字符串(非字符串按 JSON 序列化,与上游逐字符一致)"""
251
+ if isinstance(state, str):
252
+ return state
253
+ return json.dumps(state, ensure_ascii=False)
254
+
255
+ @staticmethod
256
+ def _check_long(aggregate: str, long: str | None) -> None:
257
+ """校验长文本相关参数
258
+
259
+ Raises:
260
+ ValueError: `aggregate` 非法,或 `long` 不是 None / "chunk"
261
+ """
262
+ if aggregate not in _AGGREGATES:
263
+ raise ValueError(f"aggregate 必须是 {_AGGREGATES} 之一")
264
+ if long not in _LONG_VALUES:
265
+ raise ValueError(f'long 必须是 {_LONG_VALUES} 之一(分窗请传 "chunk")')
266
+
267
+ @classmethod
268
+ def _brief(cls, answer: dict[str, Any], qtype: str) -> dict[str, Any]:
269
+ """把上游 answers 条目压成统一 6 键形状
270
+
271
+ `answer_confidence` 与 laya 同名同口径。
272
+
273
+ Raises:
274
+ DecimaError: 返回体缺少关键字段(上游结构变化)
275
+ """
276
+ abstained = answer.get("abstain")
277
+
278
+ if qtype == "noul":
279
+ if "noul" not in answer:
280
+ raise DecimaError(f"decima 未返回 noul 字段:{answer!r}")
281
+ p = float(answer["noul"])
282
+ # 上游 noul 只有 P(true)(softmax over yes/no),没有独立置信度;
283
+ # 与 laya 对齐后 answer_confidence 也取该概率
284
+ return {
285
+ "decision": p,
286
+ "answer_confidence": p,
287
+ "confidence": p,
288
+ "top_prob": p,
289
+ "probabilities": {"yes": p, "no": 1.0 - p},
290
+ "abstained": abstained,
291
+ }
292
+
293
+ raw_probs = answer.get("probabilities") or {}
294
+ if qtype == "score":
295
+ if "score" not in answer:
296
+ raise DecimaError(f"decima 未返回 score 字段:{answer!r}")
297
+ # 上游键是档位索引字符串("0"/"1"...),映射回档位文本
298
+ legend = answer.get("legend") or {}
299
+ probs = {legend.get(str(k), str(k)): float(v) for k, v in raw_probs.items()}
300
+ top = max(probs.values()) if probs else 0.0
301
+ return {
302
+ "decision": float(answer["score"]),
303
+ "answer_confidence": top,
304
+ "confidence": float(answer.get("confidence", 0.0)),
305
+ "top_prob": top,
306
+ "probabilities": probs,
307
+ "abstained": abstained,
308
+ }
309
+
310
+ if "choice" not in answer:
311
+ raise DecimaError(f"decima 未返回 choice 字段:{answer!r}")
312
+ probs = {str(k): float(v) for k, v in raw_probs.items()}
313
+ decision = answer["choice"]
314
+ if decision not in probs:
315
+ raise DecimaError(
316
+ f"decima 返回的 decision={decision!r} 不在 probabilities 中:{probs!r}"
317
+ )
318
+ top = probs[decision]
319
+ return {
320
+ "decision": decision,
321
+ "answer_confidence": top,
322
+ "confidence": float(answer.get("confidence", 0.0)),
323
+ "top_prob": top,
324
+ "probabilities": probs,
325
+ "abstained": abstained,
326
+ }
327
+
328
+ @classmethod
329
+ def _ask_locked(
330
+ cls,
331
+ state: str | dict[str, Any] | list[Any],
332
+ spec: dict[str, Any],
333
+ *,
334
+ lang: str | None = None,
335
+ long: str | None = None,
336
+ aggregate: str = "max",
337
+ min_confidence: float | None = None,
338
+ ) -> dict[str, Any]:
339
+ """单问题封装(**调用方必须已持有 `_infer_lock`**)
340
+
341
+ Raises:
342
+ ValueError: 长文本参数非法
343
+ DecimaError: 推理失败或上游未返回该问题的答案
344
+ """
345
+ cls._check_long(aggregate, long)
346
+ try:
347
+ answers = system_one(
348
+ cls.model(),
349
+ cls._state_text(state),
350
+ {_QID: spec},
351
+ lang=lang or _settings.DECIMA_LANG,
352
+ long=long,
353
+ aggregate=aggregate,
354
+ min_confidence=min_confidence,
355
+ )
356
+ except Exception as exc:
357
+ raise DecimaError(f"decima 推理失败:{exc}") from exc
358
+
359
+ answer = answers.get(_QID)
360
+ if not isinstance(answer, dict):
361
+ raise DecimaError(f"decima 未返回问题 {_QID} 的答案:{answers!r}")
362
+ return cls._brief(answer, spec["type"])
363
+
364
+ @staticmethod
365
+ def _pack(answers: dict[str, Any]) -> dict[str, Any]:
366
+ """把裸 answers 包成与 `LayaKit.predict` 同形的三键结构
367
+
368
+ `routing` 恒为 None(decima 无语言路由);`usage.windows` 取各问题里最大的
369
+ 窗口数,上游只在**分窗时**写入 `window.count`,因此单窗口时回落到 1
370
+ (与 laya 的「实际扫描窗口数 ≥1」语义一致,避免把 0 误读成「没扫」)。
371
+ """
372
+ windows = max(
373
+ (
374
+ int(a.get("window", {}).get("count", 0))
375
+ for a in answers.values()
376
+ if isinstance(a, dict)
377
+ ),
378
+ default=0,
379
+ )
380
+ return {"answers": answers, "routing": None, "usage": {"windows": windows or 1}}
381
+
382
+ # ------------------------------------------------------------------
383
+ # 单问原语
384
+ # ------------------------------------------------------------------
385
+ @classmethod
386
+ def choice(
387
+ cls,
388
+ state: str | dict[str, Any] | list[Any],
389
+ instructions: str,
390
+ criteria: dict[str, str],
391
+ *,
392
+ min_confidence: float | None = None,
393
+ lang: str | None = None,
394
+ long: str | None = None,
395
+ aggregate: str = "max",
396
+ ) -> dict[str, Any]:
397
+ """单选题:在 `criteria` 给出的候选标签里选一个
398
+
399
+ 选项顺序不影响结果(每个选项独立编码、独立与 state 打分)。
400
+
401
+ Args:
402
+ state: 待判断的文本、结构化 state 或列表
403
+ instructions: 判断规则与问题——**规则写这里**,不要只写在 criteria 描述里
404
+ criteria: 候选标签 → 该标签的说明文字(顺序无关)
405
+ min_confidence: 置信度门控阈值;给了才有 `abstained`,阈值**需自行标定**
406
+ lang: 文本语言(None 用 `DECIMA_LANG`);仅 fa/ar 有实质归一化
407
+ long: 传 `"chunk"` 时对超长文本分窗判定
408
+ aggregate: 分窗聚合方式,`max` / `mean` / `sum`
409
+
410
+ Returns:
411
+ dict[str, Any]: {decision, answer_confidence, confidence, top_prob,
412
+ probabilities, abstained}
413
+
414
+ Raises:
415
+ ValueError: `criteria` 为空,或 `aggregate` / `long` 非法
416
+ DecimaError: 模型加载或推理失败
417
+ """
418
+ if not criteria:
419
+ raise ValueError("criteria 不能为空")
420
+ spec = {"type": "choice", "instructions": instructions, "criteria": criteria}
421
+ with _infer_lock:
422
+ return cls._ask_locked(
423
+ state,
424
+ spec,
425
+ lang=lang,
426
+ long=long,
427
+ aggregate=aggregate,
428
+ min_confidence=min_confidence,
429
+ )
430
+
431
+ @classmethod
432
+ def score(
433
+ cls,
434
+ state: str | dict[str, Any] | list[Any],
435
+ instructions: str,
436
+ criteria: list[str],
437
+ *,
438
+ min_confidence: float | None = None,
439
+ lang: str | None = None,
440
+ long: str | None = None,
441
+ aggregate: str = "max",
442
+ ) -> dict[str, Any]:
443
+ """评分题:在 `criteria` 给出的序数标尺上返回期望值
444
+
445
+ 档位顺序**是问题的一部分**(从低到高),不存在「乱序不变」保证。
446
+
447
+ Args:
448
+ state: 待判断的文本、结构化 state 或列表
449
+ instructions: 判断规则与问题
450
+ criteria: 从低到高的等级描述列表(2~10 档)
451
+ min_confidence: 置信度门控阈值
452
+ lang: 文本语言(None 用 `DECIMA_LANG`)
453
+ long: 传 `"chunk"` 时分窗判定
454
+ aggregate: 分窗聚合方式
455
+
456
+ Returns:
457
+ dict[str, Any]: `decision` 为序数期望值,`probabilities` 键为档位文本
458
+
459
+ Raises:
460
+ ValueError: 档位数量不在 2~10,或 `aggregate` / `long` 非法
461
+ DecimaError: 模型加载或推理失败
462
+ """
463
+ if not _SCORE_MIN_LEVELS <= len(criteria) <= _SCORE_MAX_LEVELS:
464
+ raise ValueError(
465
+ f"score 的 criteria 需要 {_SCORE_MIN_LEVELS}~{_SCORE_MAX_LEVELS} 个档位"
466
+ )
467
+ spec = {"type": "score", "instructions": instructions, "criteria": criteria}
468
+ with _infer_lock:
469
+ return cls._ask_locked(
470
+ state,
471
+ spec,
472
+ lang=lang,
473
+ long=long,
474
+ aggregate=aggregate,
475
+ min_confidence=min_confidence,
476
+ )
477
+
478
+ @classmethod
479
+ def noul(
480
+ cls,
481
+ state: str | dict[str, Any] | list[Any],
482
+ instructions: str,
483
+ *,
484
+ min_confidence: float | None = None,
485
+ lang: str | None = None,
486
+ long: str | None = None,
487
+ aggregate: str = "max",
488
+ ) -> dict[str, Any]:
489
+ """是否题:返回 P(true)
490
+
491
+ Args:
492
+ state: 待判断的文本、结构化 state 或列表
493
+ instructions: 待判断的命题(如「客户是否明确要求退款?」)
494
+ min_confidence: 置信度门控阈值
495
+ lang: 文本语言(None 用 `DECIMA_LANG`)
496
+ long: 传 `"chunk"` 时分窗判定
497
+ aggregate: 分窗聚合方式
498
+
499
+ Returns:
500
+ dict[str, Any]: `decision` 为 P(true),`answer_confidence` / `confidence` /
501
+ `top_prob` 与它相等
502
+ """
503
+ spec = {"type": "noul", "instructions": instructions}
504
+ with _infer_lock:
505
+ return cls._ask_locked(
506
+ state,
507
+ spec,
508
+ lang=lang,
509
+ long=long,
510
+ aggregate=aggregate,
511
+ min_confidence=min_confidence,
512
+ )
513
+
514
+ @classmethod
515
+ def multi_choice(
516
+ cls,
517
+ state: str | dict[str, Any] | list[Any],
518
+ instructions: str,
519
+ criteria: dict[str, str],
520
+ *,
521
+ threshold: float = 0.5,
522
+ min_confidence: float | None = None,
523
+ lang: str | None = None,
524
+ long: str | None = None,
525
+ aggregate: str = "max",
526
+ ) -> dict[str, Any]:
527
+ """多选题:每个候选标签独立判断,返回 0-N 个选中标签
528
+
529
+ 走 decima 原生 `rank`(每选项一个独立 sigmoid),**不是** N 个 `noul` 问句;
530
+ 一次前向即可拿到全部候选的概率。
531
+
532
+ Args:
533
+ state: 待判断的文本、结构化 state 或列表
534
+ instructions: 判断规则与问题——**规则写这里**
535
+ criteria: 候选标签 → 该标签的说明文字(每个标签独立判断)
536
+ threshold: P(true) 判定阈值,默认 0.5;取值 [0, 1]
537
+ min_confidence: 置信度门控阈值;所有标签的 `answer_confidence` 都低于它时
538
+ `abstained` 为 True(rank 是独立 sigmoid,没有整体分布可弃权)
539
+ lang: 文本语言(None 用 `DECIMA_LANG`)
540
+ long: 传 `"chunk"` 时分窗判定
541
+ aggregate: 分窗聚合方式
542
+
543
+ Returns:
544
+ dict[str, Any]: `decisions`(选中标签列表,0-N 个,按概率降序)、
545
+ `probabilities`(标签 → P(true))、
546
+ `answer_confidence`(标签 → max(p, 1−p))、
547
+ `threshold`(回显实际阈值)、
548
+ `abstained`(未传 min_confidence 时为 None)
549
+
550
+ Raises:
551
+ ValueError: `criteria` 为空、`threshold` 不在 [0, 1],
552
+ 或 `aggregate` / `long` 非法
553
+ DecimaError: 模型加载或推理失败
554
+ """
555
+ if not criteria:
556
+ raise ValueError("criteria 不能为空")
557
+ if not 0 <= threshold <= 1:
558
+ raise ValueError("threshold 必须在 [0, 1] 之间")
559
+ cls._check_long(aggregate, long)
560
+
561
+ # 与 choice 保持同一渲染口径("标签: 描述"),description 为空时只用标签
562
+ rendered = [
563
+ f"{label}: {desc}" if desc else label for label, desc in criteria.items()
564
+ ]
565
+ question = Question(
566
+ instructions,
567
+ rendered,
568
+ kind="rank",
569
+ lang=lang or _settings.DECIMA_LANG,
570
+ )
571
+ with _infer_lock:
572
+ try:
573
+ decision = cls.model().decide(
574
+ cls._state_text(state), question, long=long
575
+ )
576
+ except Exception as exc:
577
+ raise DecimaError(f"decima multi_choice 执行失败:{exc}") from exc
578
+
579
+ if len(decision.probs) != len(rendered):
580
+ raise DecimaError(
581
+ f"decima 概率数与选项数不一致:{len(decision.probs)} != {len(rendered)}"
582
+ )
583
+ probabilities = {
584
+ label: float(p) for label, p in zip(criteria, decision.probs, strict=True)
585
+ }
586
+ # rank 每项是独立 sigmoid,没有分布;置信度取「离 0.5 多远」映射到 0.5~1
587
+ answer_confidence = {
588
+ label: max(p, 1.0 - p) for label, p in probabilities.items()
589
+ }
590
+ decisions = sorted(
591
+ (label for label, p in probabilities.items() if p >= threshold),
592
+ key=lambda label: probabilities[label],
593
+ reverse=True,
594
+ )
595
+ abstained = None
596
+ if min_confidence is not None:
597
+ abstained = all(c < min_confidence for c in answer_confidence.values())
598
+ return {
599
+ "decisions": decisions,
600
+ "probabilities": probabilities,
601
+ "answer_confidence": answer_confidence,
602
+ "threshold": threshold,
603
+ "abstained": abstained,
604
+ }
605
+
606
+ # ------------------------------------------------------------------
607
+ # 多问题 / 批量
608
+ # ------------------------------------------------------------------
609
+ @classmethod
610
+ def predict(
611
+ cls,
612
+ state: str | dict[str, Any] | list[Any],
613
+ questions: dict[str, Any],
614
+ *,
615
+ min_confidence: float | None = None,
616
+ lang: str | None = None,
617
+ long: str | None = None,
618
+ aggregate: str = "max",
619
+ ) -> dict[str, Any]:
620
+ """多问题一次前向:返回与 `LayaKit.predict` 同形的三键结构
621
+
622
+ 返回 `{answers, routing, usage}`。decima 无语言路由,`routing` 恒为 None;
623
+ `usage` 只含 `windows`(分窗时的最大窗口数)。
624
+
625
+ Args:
626
+ state: 待判断的文本、结构化 state 或列表
627
+ questions: TypeSafe 问题字典(`choice` / `score` / `noul` 可混合)
628
+ min_confidence: 置信度门控阈值
629
+ lang: 文本语言(None 用 `DECIMA_LANG`)
630
+ long: 传 `"chunk"` 时分窗判定
631
+ aggregate: 分窗聚合方式
632
+
633
+ Returns:
634
+ dict[str, Any]: {answers, routing, usage};`answers` 的问题 id → 上游条目
635
+
636
+ Raises:
637
+ ValueError: `questions` 为空,或 `aggregate` / `long` 非法
638
+ DecimaError: 模型加载或推理失败
639
+ """
640
+ if not questions:
641
+ raise ValueError("questions 不能为空")
642
+ cls._check_long(aggregate, long)
643
+ with _infer_lock:
644
+ try:
645
+ answers = system_one(
646
+ cls.model(),
647
+ cls._state_text(state),
648
+ questions,
649
+ lang=lang or _settings.DECIMA_LANG,
650
+ long=long,
651
+ aggregate=aggregate,
652
+ min_confidence=min_confidence,
653
+ )
654
+ except Exception as exc:
655
+ raise DecimaError(f"decima predict 执行失败:{exc}") from exc
656
+ return cls._pack(answers)
657
+
658
+ @classmethod
659
+ def brief(cls, raw: dict[str, Any]) -> dict[str, Any]:
660
+ """把 `predict` 结果压成「判断 + 置信度 + 分布」(与 `LayaKit.brief` 同形)
661
+
662
+ Args:
663
+ raw: `predict()` / `predict_long()` 的返回
664
+
665
+ Returns:
666
+ dict[str, Any]: 问题 id → {decision, answer_confidence, probabilities}
667
+ """
668
+ brief: dict[str, Any] = {}
669
+ for qid, answer in (raw.get("answers") or {}).items():
670
+ if not isinstance(answer, dict):
671
+ brief[qid] = answer
672
+ continue
673
+ decision = next(
674
+ (answer[key] for key in _DECISION_KEYS if key in answer),
675
+ None,
676
+ )
677
+ if "noul" in answer:
678
+ # 上游 noul 条目没有 confidence 字段,与 laya 对齐后取该概率
679
+ confidence = answer["noul"]
680
+ probabilities: Any = {"yes": answer["noul"], "no": 1.0 - answer["noul"]}
681
+ else:
682
+ confidence = answer.get("confidence")
683
+ probabilities = answer.get("probabilities")
684
+ brief[qid] = {
685
+ "decision": decision,
686
+ "answer_confidence": confidence,
687
+ "probabilities": probabilities,
688
+ }
689
+ return brief
690
+
691
+ @classmethod
692
+ def predict_long(
693
+ cls,
694
+ state: str | dict[str, Any] | list[Any],
695
+ questions: dict[str, Any],
696
+ *,
697
+ window: int | None = None,
698
+ stride: int | None = None,
699
+ batch_size: int | None = None,
700
+ min_confidence: float | None = None,
701
+ lang: str | None = None,
702
+ aggregate: str = "max",
703
+ ) -> dict[str, Any]:
704
+ """长文本决策:按重叠窗口扫描全文并聚合(与 `LayaKit.predict_long` 同名)
705
+
706
+ ⚠ decima 的分窗由模型 `max_state_tokens`(512)与 `overlap`(64 token)决定,
707
+ **`window` / `stride` / `batch_size` 三个参数不生效**,仅接受以兼容 laya 的调用
708
+ 写法;`aggregate` 决定跨窗口聚合方式。
709
+
710
+ Args:
711
+ state: 待判断的文本、结构化 state 或列表
712
+ questions: TypeSafe 问题字典
713
+ window: 为兼容而接受,**不生效**
714
+ stride: 为兼容而接受,**不生效**
715
+ batch_size: 为兼容而接受,**不生效**
716
+ min_confidence: 置信度门控阈值
717
+ lang: 文本语言(None 用 `DECIMA_LANG`)
718
+ aggregate: 分窗聚合方式:`max` / `mean` / `sum`(含义见模块 docstring)
719
+
720
+ Returns:
721
+ dict[str, Any]: 与 `predict` 同形的 {answers, routing, usage}
722
+
723
+ Raises:
724
+ ValueError: `questions` 为空,或 `aggregate` 非法
725
+ DecimaError: 模型加载或推理失败
726
+ """
727
+ if window is not None or stride is not None or batch_size is not None:
728
+ _warn_ignored_window_params(window, stride, batch_size)
729
+ return cls.predict(
730
+ state,
731
+ questions,
732
+ min_confidence=min_confidence,
733
+ lang=lang,
734
+ long="chunk",
735
+ aggregate=aggregate,
736
+ )
737
+
738
+ @classmethod
739
+ def predict_many(
740
+ cls,
741
+ states: Sequence[str | dict[str, Any] | list[Any]],
742
+ questions: dict[str, Any],
743
+ *,
744
+ min_confidence: float | None = None,
745
+ lang: str | None = None,
746
+ long: str | None = None,
747
+ aggregate: str = "max",
748
+ ) -> list[dict[str, Any]]:
749
+ """同一组问题跑多条 state,结果按输入顺序返回
750
+
751
+ Args:
752
+ states: 多条待判断文本或结构化 state
753
+ questions: TypeSafe 问题字典
754
+ min_confidence: 置信度门控阈值
755
+ lang: 文本语言(None 用 `DECIMA_LANG`)
756
+ long: 传 `"chunk"` 时分窗判定
757
+ aggregate: 分窗聚合方式
758
+
759
+ Returns:
760
+ list[dict[str, Any]]: 与 `states` 等长、顺序一致,元素同 `predict`
761
+ """
762
+ if not states:
763
+ return []
764
+ if not questions:
765
+ raise ValueError("questions 不能为空")
766
+ cls._check_long(aggregate, long)
767
+ results: list[dict[str, Any]] = []
768
+ with _infer_lock:
769
+ for index, state in enumerate(states):
770
+ try:
771
+ answers = system_one(
772
+ cls.model(),
773
+ cls._state_text(state),
774
+ questions,
775
+ lang=lang or _settings.DECIMA_LANG,
776
+ long=long,
777
+ aggregate=aggregate,
778
+ min_confidence=min_confidence,
779
+ )
780
+ except Exception as exc:
781
+ raise DecimaError(
782
+ f"decima predict_many 第 {index}/{len(states)} 条失败:{exc}"
783
+ ) from exc
784
+ results.append(cls._pack(answers))
785
+ return results
786
+
787
+ @classmethod
788
+ def choice_batch(
789
+ cls,
790
+ states: Sequence[str | dict[str, Any] | list[Any]],
791
+ instructions: str,
792
+ criteria: dict[str, str],
793
+ *,
794
+ min_confidence: float | None = None,
795
+ lang: str | None = None,
796
+ long: str | None = None,
797
+ aggregate: str = "max",
798
+ ) -> list[dict[str, Any]]:
799
+ """一条单选题跑多条 state(单选批量),结果按输入顺序返回
800
+
801
+ 与 `LayaKit.decide_batch` **不同**:那个是 schema 多字段批量(laya 独有),
802
+ 本方法是单选题的批量版,对应 `LayaKit.choice` 的多 state 形态。
803
+
804
+ 选项编码会按「同一组选项」缓存,批量场景比逐条 `choice` 更省。
805
+
806
+ Args:
807
+ states: 多条待判断文本或结构化 state
808
+ instructions: 判断规则与问题
809
+ criteria: 候选标签 → 说明文字
810
+ min_confidence: 置信度门控阈值
811
+ lang: 文本语言(None 用 `DECIMA_LANG`)
812
+ long: 传 `"chunk"` 时分窗判定
813
+ aggregate: 分窗聚合方式
814
+
815
+ Returns:
816
+ list[dict[str, Any]]: 与 `states` 等长、顺序一致的结果列表
817
+
818
+ Raises:
819
+ ValueError: `criteria` 为空,或 `aggregate` / `long` 非法
820
+ DecimaError: 模型加载或推理失败
821
+ """
822
+ if not criteria:
823
+ raise ValueError("criteria 不能为空")
824
+ if not states:
825
+ return []
826
+ cls._check_long(aggregate, long)
827
+ spec = {"type": "choice", "instructions": instructions, "criteria": criteria}
828
+ with _infer_lock:
829
+ return [
830
+ cls._ask_locked(
831
+ state,
832
+ spec,
833
+ lang=lang,
834
+ long=long,
835
+ aggregate=aggregate,
836
+ min_confidence=min_confidence,
837
+ )
838
+ for state in states
839
+ ]
840
+
841
+ @classmethod
842
+ def decide_batch(cls, *args: Any, **kwargs: Any) -> list[dict[str, Any]]:
843
+ """不提供:schema 驱动的多字段批量判定是 `LayaKit` 独有能力
844
+
845
+ 保留本方法只为在迁移时给出明确错误,避免「同名不同义」被静默当成单选批量使用。
846
+
847
+ Raises:
848
+ NotImplementedError: 总是抛出
849
+ """
850
+ raise NotImplementedError(
851
+ "DecimaKit 没有 schema / questions 驱动的多字段批量判定能力(laya 独有);"
852
+ "单选批量请用 DecimaKit.choice_batch,多字段请用 LayaKit.decide_batch"
853
+ )