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,552 @@
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-10-13
21
+ """laya 决策引擎工具类,把任意文本变成类型化决策
22
+
23
+ laya(https://github.com/NandhaKishorM/laya)是单次前向传播的类型化决策引擎
24
+ (多语言、非自回归),本工具类封装它的三类决策原语:
25
+
26
+ - `choice(state, instructions, criteria)`:候选标签里选一个,`decision` 为选中标签;
27
+ - `score(state, instructions, criteria)`:序数标尺上评分,`decision` 为期望值;
28
+ - `noul(state, instructions)`:判断是否成立,`decision` 为 P(true)(0.0-1.0)。
29
+
30
+ 三者都返回 `{decision, answer_confidence, probabilities}`——判断结果 + 置信度;
31
+ 需要完整字段(`routing` / `usage`)时用 `predict()` + `brief()`。
32
+
33
+ 多字段、批量与长文本(0.6.8 新增):
34
+
35
+ - `decide(schema=...)`:按 JSON schema / pydantic 模型一次返回多字段类型化结果,
36
+ 适合同时问「选哪个 + 打几分 + 是否成立」;
37
+ - `decide_batch(states, schema=...)`:同一 schema 批量判定,结果按输入顺序返回;
38
+ - `predict_long(state, questions)`:超长文本分窗扫描(`usage["windows"]` 为窗口数),
39
+ 避免 `predict` 只取首个窗口导致后半段文本被截断。
40
+
41
+ 关键用法(实测得出,务必遵守):
42
+
43
+ - 判断规则必须写进 `instructions`,只靠 `criteria` 描述做语义推断会判错;
44
+ - 候选标签的文字本身会改变输出分布(中文标签与英文标签结果不同);
45
+ - **措辞敏感**:同一意思换同义词会明显改变 `answer_confidence`(如「退款」→「退费」
46
+ 使置信度由 0.92 降到 0.57),因此**不要用绝对置信度做门控阈值**;需要稳定请在
47
+ 业务侧做输入归一化——本工具类**不改写任何文本**;
48
+ - 上游检查点温度标定无效,置信度未经标定,仅供参考。
49
+
50
+ 配置走 `yimo.kit.config.Settings`(`.env` / 环境变量):`LAYA_MODEL`(检查点)、
51
+ `LAYA_DEVICE`(推理设备)、`LAYA_HF_ENDPOINT`(权重下载入口)、`LAYA_HF_DISABLE_XET`、
52
+ `LAYA_PRELOAD`(是否预热当前检查点)、`LAYA_MAX_LOADED`(同时驻留检查点上限)。
53
+ **HF 相关环境变量必须在导入本模块前生效**(本模块导入即设置并加载 laya),
54
+ 如需自定义请在 `.env` 或进程启动前设置。
55
+
56
+ 用法:
57
+ from yimo.kit.ai.decision import LayaKit
58
+
59
+ result = LayaKit.choice(
60
+ state="我们三月份被重复扣费了两次,请把重复的那笔退款。",
61
+ instructions="这封来信应该由哪个部门处理?",
62
+ criteria={"账务": "账单、付款、退款", "技术": "故障、报错"},
63
+ )
64
+ print(result["decision"], result["answer_confidence"])
65
+
66
+ 说明:本模块为可选依赖,需安装 `pip install "yimo-kit[laya]"`;首次使用会下载
67
+ 检查点权重(322M-421M 参数),模型常驻内存,用完可 `LayaKit.unload()` 释放。
68
+ """
69
+
70
+ import os
71
+ import threading
72
+ from collections.abc import Sequence
73
+ from dataclasses import asdict
74
+ from typing import Any
75
+
76
+ from yimo.kit.config.kit_config import get_settings
77
+ from yimo.kit.config.log_config import get_default_logger
78
+
79
+ logger = get_default_logger(__name__)
80
+
81
+ _settings = get_settings()
82
+
83
+ # HuggingFace 相关环境必须在导入 laya / huggingface_hub 之前设置,否则不生效。
84
+ # 统一使用 setdefault:仅当用户未显式设置环境变量时生效,不覆盖显式配置。
85
+ if _settings.LAYA_HF_ENDPOINT:
86
+ os.environ.setdefault("HF_ENDPOINT", _settings.LAYA_HF_ENDPOINT)
87
+ if _settings.LAYA_HF_DISABLE_XET:
88
+ os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
89
+
90
+ try:
91
+ import laya
92
+ except ImportError as e:
93
+ raise ImportError(
94
+ "yimo.kit.ai.decision.laya 需要可选依赖,请安装:pip install yimo-kit[laya]"
95
+ ) from e
96
+
97
+ # 单问题封装使用的内部问题 id(调用方无需关心)
98
+ _QID: str = "answer"
99
+
100
+ # 决策原语的取值键(与 laya 返回体一致,按优先级取第一个存在的)
101
+ _DECISION_KEYS: tuple[str, ...] = ("choice", "score", "noul")
102
+
103
+ # 推理锁:串行化「加载 / 卸载 Router + 推理」全过程。
104
+ # 锁序恒为 _infer_lock → _router_lock,任何路径都不得反向获取,否则会死锁。
105
+ _infer_lock: threading.RLock = threading.RLock()
106
+
107
+
108
+ class LayaError(Exception):
109
+ """laya 决策异常(模型加载失败 / 推理失败 / 返回体不符合预期)"""
110
+
111
+
112
+ class LayaKit:
113
+ """laya 决策引擎工具类(无状态,方法均为 `classmethod`)
114
+
115
+ Router 为类级单例(模型加载开销极大,必须复用),配置统一走
116
+ `yimo.kit.config.Settings` 的 `LAYA_*` 配置项;**不改写任何输入文本**。
117
+ """
118
+
119
+ _router: Any = None
120
+ _router_lock: threading.Lock = threading.Lock()
121
+
122
+ @classmethod
123
+ def router(cls) -> Any:
124
+ """惰性创建并缓存 Router(进程内单例,线程安全)
125
+
126
+ Returns:
127
+ Any: laya.Router 实例
128
+ """
129
+ with cls._router_lock:
130
+ if cls._router is None:
131
+ kwargs: dict[str, Any] = {"default": _settings.LAYA_MODEL}
132
+ if _settings.LAYA_DEVICE:
133
+ kwargs["device"] = _settings.LAYA_DEVICE
134
+ if _settings.LAYA_MAX_LOADED is not None:
135
+ kwargs["max_loaded"] = _settings.LAYA_MAX_LOADED
136
+ logger.info(
137
+ f"加载 laya Router:检查点={_settings.LAYA_MODEL},"
138
+ f"设备={_settings.LAYA_DEVICE or 'auto'},"
139
+ f"驻留上限={_settings.LAYA_MAX_LOADED or '默认 2'}"
140
+ )
141
+ cls._router = laya.Router(**kwargs)
142
+ # 预热只针对当前生效检查点:上游 preload=True 会加载全部内置检查点(3 份),
143
+ # 内存开销过大,因此显式按名预热。
144
+ if _settings.LAYA_PRELOAD:
145
+ cls._router.preload([_settings.LAYA_MODEL])
146
+ return cls._router
147
+
148
+ @classmethod
149
+ def route(
150
+ cls, state: str | dict[str, Any], questions: dict[str, Any] | None = None
151
+ ) -> dict[str, Any]:
152
+ """纯路由决策(不加载检查点、不下载权重,可离线)
153
+
154
+ Args:
155
+ state: 任意文本或结构化 state
156
+ questions: 可选问题定义(None 时只做语言/脚本探测)
157
+
158
+ Returns:
159
+ dict[str, Any]: 路由结果,含 `model` / `reason` / `detection`
160
+ """
161
+ decision = cls.router().route(state, questions)
162
+ if isinstance(decision, dict):
163
+ return decision
164
+ raw = getattr(decision, "__dict__", None)
165
+ if isinstance(raw, dict):
166
+ return raw
167
+ return {
168
+ "model": getattr(decision, "model", None),
169
+ "reason": getattr(decision, "reason", None),
170
+ }
171
+
172
+ @classmethod
173
+ def predict(
174
+ cls,
175
+ state: str | dict[str, Any],
176
+ questions: dict[str, Any],
177
+ *,
178
+ min_confidence: float | None = None,
179
+ ) -> dict[str, Any]:
180
+ """多问题一次前向传播,返回 laya 原始结果(`answers` / `routing` / `usage`)
181
+
182
+ Args:
183
+ state: 任意文本或结构化 state
184
+ questions: 问题定义字典(choice / score / noul 可混合)
185
+ min_confidence: 置信度门控阈值,低于该值会在答案里标记 low_confidence;
186
+ 注意上游置信度未标定(见模块 docstring),阈值需自行标定
187
+
188
+ Returns:
189
+ dict[str, Any]: laya 原始返回(字段最全,便于调用方自行取用)
190
+ """
191
+ kwargs: dict[str, Any] = {"model": _settings.LAYA_MODEL}
192
+ if min_confidence is not None:
193
+ kwargs["min_confidence"] = min_confidence
194
+ # 推理与卸载互斥:先取推理锁,再在 router() 内取路由锁(锁序不可颠倒)
195
+ with _infer_lock:
196
+ return cls.router().predict(state, questions, **kwargs)
197
+
198
+ @classmethod
199
+ def brief(cls, raw: dict[str, Any]) -> dict[str, Any]:
200
+ """把 predict 原始结果压成「判断结果 + 置信度」两部分
201
+
202
+ Args:
203
+ raw: `predict()` 的原始返回
204
+
205
+ Returns:
206
+ dict[str, Any]: 问题 id → {decision, answer_confidence, probabilities}
207
+ """
208
+ brief: dict[str, Any] = {}
209
+ for qid, answer in (raw.get("answers") or {}).items():
210
+ if not isinstance(answer, dict):
211
+ brief[qid] = answer
212
+ continue
213
+ decision = next(
214
+ (answer[key] for key in _DECISION_KEYS if key in answer),
215
+ None,
216
+ )
217
+ brief[qid] = {
218
+ "decision": decision,
219
+ "answer_confidence": answer.get("answer_confidence"),
220
+ "probabilities": answer.get("probabilities"),
221
+ }
222
+ return brief
223
+
224
+ @classmethod
225
+ def decide(
226
+ cls,
227
+ state: str | dict[str, Any] | list[Any],
228
+ schema: Any = None,
229
+ *,
230
+ questions: dict[str, Any] | None = None,
231
+ min_confidence: float | None = None,
232
+ ) -> dict[str, Any]:
233
+ """多字段类型化判定:按 schema(或显式问题)一次前向传播返回所有字段
234
+
235
+ `schema` 与 `questions` 必须且只能提供一个。schema 支持 JSON Schema 字典或
236
+ pydantic 模型,可映射字段为:`enum` → 选择项、`boolean` → 是否、
237
+ 带 `minimum`/`maximum` 的 `integer`/`number` → 打分;数组、嵌套对象、
238
+ 联合类型不支持(上游抛出的异常统一包装为 `LayaError`)。
239
+
240
+ 注意:`score` 字段投影为**置信度最高的档位值**(argmax),不是序数期望值。
241
+
242
+ Args:
243
+ state: 待判断的文本或结构化 state
244
+ schema: JSON Schema 字典或 pydantic 模型(与 `questions` 二选一)
245
+ questions: laya 问题定义字典(与 `schema` 二选一),可混合 choice/score/noul;
246
+ 此时 `values` 直接返回各问题的原始答案
247
+ min_confidence: 置信度门控阈值,低于阈值的字段值变为 None
248
+
249
+ Returns:
250
+ dict[str, Any]: `DecisionResult` 的 7 个字段——`values`(按 schema 形状的
251
+ 输出)、`confidence`、`probabilities`、`answers`、`usage`、`routing`、
252
+ `answer_confidence`
253
+
254
+ Raises:
255
+ ValueError: `schema` 与 `questions` 同时提供或都未提供
256
+ LayaError: 模型加载或推理失败(含 schema 非法、投影失败等上游异常)
257
+ """
258
+ if (schema is None) == (questions is None):
259
+ raise ValueError("schema 与 questions 必须且只能提供一个")
260
+
261
+ with _infer_lock:
262
+ try:
263
+ result = cls.router().decide(
264
+ state,
265
+ schema,
266
+ questions=questions,
267
+ model=_settings.LAYA_MODEL,
268
+ min_confidence=min_confidence,
269
+ return_details=True,
270
+ )
271
+ except Exception as exc:
272
+ raise LayaError(f"laya decide 执行失败:{exc}") from exc
273
+ return asdict(result)
274
+
275
+ @classmethod
276
+ def decide_batch(
277
+ cls,
278
+ states: Sequence[str | dict[str, Any] | list[Any]],
279
+ schema: Any = None,
280
+ *,
281
+ questions: dict[str, Any] | None = None,
282
+ min_confidence: float | None = None,
283
+ batch_size: int | None = None,
284
+ sort_by_length: bool = False,
285
+ ) -> list[dict[str, Any]]:
286
+ """批量多字段判定:同一 schema 跑多条 state,结果按输入顺序返回
287
+
288
+ 推理按批分组执行,比逐条调用 `decide` 吞吐更高;schema 只规划一次。
289
+ 参数与返回口径同 `decide`,每个元素是 `DecisionResult` 的 7 个字段。
290
+
291
+ Args:
292
+ states: 多条待判断文本或结构化 state 的序列
293
+ schema: JSON Schema 字典或 pydantic 模型(与 `questions` 二选一)
294
+ questions: laya 问题定义字典(与 `schema` 二选一)
295
+ min_confidence: 置信度门控阈值,低于阈值的字段值变为 None
296
+ batch_size: 单次前向传播的最大条数,None 交由上游决定
297
+ sort_by_length: 为 True 时上游按文本长度排序以减少 padding,
298
+ 返回结果仍会还原为输入顺序
299
+
300
+ Returns:
301
+ list[dict[str, Any]]: 与 `states` 等长、顺序一致的结果列表
302
+
303
+ Raises:
304
+ ValueError: `schema` 与 `questions` 同时提供或都未提供
305
+ LayaError: 模型加载或推理失败
306
+ """
307
+ if (schema is None) == (questions is None):
308
+ raise ValueError("schema 与 questions 必须且只能提供一个")
309
+
310
+ kwargs: dict[str, Any] = {
311
+ "questions": questions,
312
+ "model": _settings.LAYA_MODEL,
313
+ "min_confidence": min_confidence,
314
+ "return_details": True,
315
+ }
316
+ if batch_size is not None:
317
+ kwargs["batch_size"] = batch_size
318
+ if sort_by_length:
319
+ kwargs["sort_by_length"] = True
320
+
321
+ with _infer_lock:
322
+ try:
323
+ results = cls.router().decide_batch(states, schema, **kwargs)
324
+ except Exception as exc:
325
+ raise LayaError(f"laya decide_batch 执行失败:{exc}") from exc
326
+ return [asdict(item) for item in results]
327
+
328
+ @classmethod
329
+ def predict_long(
330
+ cls,
331
+ state: str | dict[str, Any] | list[Any],
332
+ questions: dict[str, Any],
333
+ *,
334
+ window: int | None = None,
335
+ stride: int | None = None,
336
+ batch_size: int | None = None,
337
+ ) -> dict[str, Any]:
338
+ """长文本决策:把 state 切成重叠窗口逐一推理并聚合,避免只取首个窗口
339
+
340
+ 聚合规则由上游决定:`noul` 取最强窗口,`choice` / `score` 取最置信窗口。
341
+ 窗口默认按检查点预算(约 `max_len - head_max_len - 8` 个 token)计算。
342
+
343
+ Args:
344
+ state: 待判断的文本或结构化 state
345
+ questions: laya 问题定义字典(可混合 choice/score/noul)
346
+ window: 每个窗口的 token 数,None 使用检查点预算
347
+ stride: 窗口间步长(token),None 使用窗口的一半(50% 重叠)
348
+ batch_size: 单次前向传播最多处理的窗口数,用于控制内存
349
+
350
+ Returns:
351
+ dict[str, Any]: laya 原始返回,`usage["windows"]` 为实际扫描的窗口数
352
+
353
+ Raises:
354
+ LayaError: 模型加载或推理失败
355
+ """
356
+ kwargs: dict[str, Any] = {"model": _settings.LAYA_MODEL}
357
+ if window is not None:
358
+ kwargs["window"] = window
359
+ if stride is not None:
360
+ kwargs["stride"] = stride
361
+ if batch_size is not None:
362
+ kwargs["batch_size"] = batch_size
363
+ with _infer_lock:
364
+ try:
365
+ return cls.router().predict_long(state, questions, **kwargs)
366
+ except Exception as exc:
367
+ raise LayaError(f"laya predict_long 执行失败:{exc}") from exc
368
+
369
+ @classmethod
370
+ def choice(
371
+ cls,
372
+ state: str | dict[str, Any],
373
+ instructions: str,
374
+ criteria: dict[str, str],
375
+ *,
376
+ min_confidence: float | None = None,
377
+ ) -> dict[str, Any]:
378
+ """单选题:在 `criteria` 给出的候选标签里选一个
379
+
380
+ Args:
381
+ state: 待判断的文本或结构化 state
382
+ instructions: 判断规则与问题——**规则写这里**,不要只写在 criteria 描述里
383
+ criteria: 候选标签 → 该标签的说明文字
384
+ min_confidence: 置信度门控阈值
385
+
386
+ Returns:
387
+ dict[str, Any]: {decision: 选中标签, answer_confidence, probabilities}
388
+ """
389
+ question = {
390
+ "type": "choice",
391
+ "instructions": instructions,
392
+ "criteria": criteria,
393
+ }
394
+ return cls._ask(question, state, min_confidence)
395
+
396
+ @classmethod
397
+ def multi_choice(
398
+ cls,
399
+ state: str | dict[str, Any] | list[Any],
400
+ instructions: str,
401
+ criteria: dict[str, str],
402
+ *,
403
+ threshold: float = 0.5,
404
+ min_confidence: float | None = None,
405
+ ) -> dict[str, Any]:
406
+ """多选题:每个候选标签独立判断,返回 0-N 个选中标签
407
+
408
+ 每个标签被构造成一个 `noul` 问句,一次前向传播返回各自的 P(true);
409
+ `decisions` 是 P(true) >= `threshold` 的标签,按概率降序排列,
410
+ 因此可能返回 0 个(全部不命中)到全部 N 个。
411
+
412
+ Args:
413
+ state: 待判断的文本或结构化 state
414
+ instructions: 判断规则与问题——**规则写这里**,不要只写在 criteria 描述里
415
+ criteria: 候选标签 → 该标签的说明文字(每个标签独立判断)
416
+ threshold: P(true) 判定阈值,默认 0.5;取值 [0, 1]
417
+ min_confidence: 置信度门控阈值,透传上游
418
+
419
+ Returns:
420
+ dict[str, Any]: `decisions`(选中标签列表,0-N 个,按概率降序)、
421
+ `probabilities`(标签 → P(true))、`answer_confidence`(标签 → 答案置信度)
422
+
423
+ Raises:
424
+ ValueError: `criteria` 为空或 `threshold` 不在 [0, 1]
425
+ LayaError: 模型加载或推理失败(含上游未返回某个标签的答案)
426
+ """
427
+ if not criteria:
428
+ raise ValueError("criteria 不能为空")
429
+ if not 0 <= threshold <= 1:
430
+ raise ValueError("threshold 必须在 [0, 1] 之间")
431
+
432
+ # 每个标签一个 noul 问句:把判断规则与标签说明都写进 instructions,
433
+ # 上游 noul 只读取 instructions,不能只依赖 criteria 描述。
434
+ questions = {
435
+ label: {
436
+ "type": "noul",
437
+ "instructions": f"{instructions}\n候选标签:{label};判定说明:{description}",
438
+ }
439
+ for label, description in criteria.items()
440
+ }
441
+ kwargs: dict[str, Any] = {"model": _settings.LAYA_MODEL}
442
+ if min_confidence is not None:
443
+ kwargs["min_confidence"] = min_confidence
444
+ # 一次前向传播完成全部候选判断;推理锁保证与卸载互斥(锁序不可颠倒)
445
+ with _infer_lock:
446
+ try:
447
+ raw = cls.router().predict(state, questions, **kwargs)
448
+ except Exception as exc:
449
+ raise LayaError(f"laya multi_choice 执行失败:{exc}") from exc
450
+
451
+ answers = raw.get("answers") or {}
452
+ probabilities: dict[str, float] = {}
453
+ answer_confidence: dict[str, float] = {}
454
+ for label in criteria:
455
+ answer = answers.get(label)
456
+ if not isinstance(answer, dict):
457
+ raise LayaError(f"laya 未返回标签 {label} 的答案:{answer!r}")
458
+ probabilities[label] = float(answer.get("noul", 0.0))
459
+ answer_confidence[label] = float(answer.get("answer_confidence", 0.0))
460
+
461
+ # 0-N 个:阈值过滤后按概率降序,调用方直接使用,无需二次排序
462
+ decisions = sorted(
463
+ (label for label, p in probabilities.items() if p >= threshold),
464
+ key=lambda label: probabilities[label],
465
+ reverse=True,
466
+ )
467
+ return {
468
+ "decisions": decisions,
469
+ "probabilities": probabilities,
470
+ "answer_confidence": answer_confidence,
471
+ }
472
+
473
+ @classmethod
474
+ def score(
475
+ cls,
476
+ state: str | dict[str, Any],
477
+ instructions: str,
478
+ criteria: list[str],
479
+ *,
480
+ min_confidence: float | None = None,
481
+ ) -> dict[str, Any]:
482
+ """评分题:在 `criteria` 给出的序数标尺上给出期望值
483
+
484
+ Args:
485
+ state: 待判断的文本或结构化 state
486
+ instructions: 判断规则与问题
487
+ criteria: 从低到高的等级描述列表
488
+ min_confidence: 置信度门控阈值
489
+
490
+ Returns:
491
+ dict[str, Any]: {decision: 序数期望值, answer_confidence, probabilities}
492
+ """
493
+ question = {
494
+ "type": "score",
495
+ "instructions": instructions,
496
+ "criteria": criteria,
497
+ }
498
+ return cls._ask(question, state, min_confidence)
499
+
500
+ @classmethod
501
+ def noul(
502
+ cls,
503
+ state: str | dict[str, Any],
504
+ instructions: str,
505
+ *,
506
+ min_confidence: float | None = None,
507
+ ) -> dict[str, Any]:
508
+ """是否题:返回 P(true)
509
+
510
+ Args:
511
+ state: 待判断的文本或结构化 state
512
+ instructions: 待判断的命题(如「客户是否明确要求退款?」)
513
+ min_confidence: 置信度门控阈值
514
+
515
+ Returns:
516
+ dict[str, Any]: {decision: P(true), answer_confidence, probabilities}
517
+ """
518
+ question = {"type": "noul", "instructions": instructions}
519
+ return cls._ask(question, state, min_confidence)
520
+
521
+ @classmethod
522
+ def _ask(
523
+ cls,
524
+ question: dict[str, Any],
525
+ state: str | dict[str, Any],
526
+ min_confidence: float | None,
527
+ ) -> dict[str, Any]:
528
+ """单问题封装:构造 questions → predict → 取该问的 brief 结果
529
+
530
+ Raises:
531
+ LayaError: laya 未返回该问题的答案时抛出(返回体结构变化)
532
+ """
533
+ raw = cls.predict(state, {_QID: question}, min_confidence=min_confidence)
534
+ brief = cls.brief(raw)
535
+ if _QID not in brief:
536
+ raise LayaError(f"laya 未返回问句 {_QID} 的答案:{raw!r}")
537
+ return brief[_QID]
538
+
539
+ @classmethod
540
+ def unload(cls) -> None:
541
+ """释放 Router 与模型内存(先调用底层 unload,再置空单例)
542
+
543
+ 锁序与推理一致:先取推理锁等待在途推理结束,再取路由锁。
544
+ """
545
+ with _infer_lock:
546
+ with cls._router_lock:
547
+ if cls._router is not None:
548
+ unload_fn = getattr(cls._router, "unload", None)
549
+ if callable(unload_fn):
550
+ unload_fn()
551
+ cls._router = None
552
+ logger.info("laya Router 已释放")