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.
- yimo/__init__.py +26 -0
- yimo/kit/__init__.py +98 -0
- yimo/kit/ai/__init__.py +110 -0
- yimo/kit/ai/_internal/__init__.py +27 -0
- yimo/kit/ai/_internal/failover.py +535 -0
- yimo/kit/ai/_internal/pool.py +526 -0
- yimo/kit/ai/_internal/rerank_transport.py +137 -0
- yimo/kit/ai/_internal/retry_after.py +51 -0
- yimo/kit/ai/_internal/sdk_client.py +463 -0
- yimo/kit/ai/_internal/service_base.py +115 -0
- yimo/kit/ai/_internal/types.py +28 -0
- yimo/kit/ai/agent/__init__.py +127 -0
- yimo/kit/ai/agent/approval.py +66 -0
- yimo/kit/ai/agent/errors.py +128 -0
- yimo/kit/ai/agent/loop.py +643 -0
- yimo/kit/ai/agent/mcp.py +278 -0
- yimo/kit/ai/agent/registry.py +203 -0
- yimo/kit/ai/agent/session.py +150 -0
- yimo/kit/ai/agent/skill.py +370 -0
- yimo/kit/ai/agent/types.py +161 -0
- yimo/kit/ai/chat_service.py +724 -0
- yimo/kit/ai/decision/__init__.py +57 -0
- yimo/kit/ai/decision/decima.py +853 -0
- yimo/kit/ai/decision/laya.py +552 -0
- yimo/kit/ai/embedding_service.py +198 -0
- yimo/kit/ai/exceptions.py +109 -0
- yimo/kit/ai/image_service.py +84 -0
- yimo/kit/ai/messages.py +105 -0
- yimo/kit/ai/model_builder.py +121 -0
- yimo/kit/ai/model_client.py +62 -0
- yimo/kit/ai/profiles.py +577 -0
- yimo/kit/ai/rerank_service.py +136 -0
- yimo/kit/ai/runner.py +1127 -0
- yimo/kit/common_kit.py +221 -0
- yimo/kit/config/__init__.py +44 -0
- yimo/kit/config/kit_config.py +210 -0
- yimo/kit/config/log_config.py +171 -0
- yimo/kit/crawl/__init__.py +71 -0
- yimo/kit/crawl/article_io.py +325 -0
- yimo/kit/crawl/article_models.py +172 -0
- yimo/kit/crawl/deepseek_kit.py +673 -0
- yimo/kit/crawl/web_article_kit.py +638 -0
- yimo/kit/crawl/wx_article_kit.py +692 -0
- yimo/kit/db/__init__.py +101 -0
- yimo/kit/db/audit.py +625 -0
- yimo/kit/db/base_db_kit.py +1265 -0
- yimo/kit/db/crud.py +423 -0
- yimo/kit/db/engine.py +235 -0
- yimo/kit/db/exceptions.py +45 -0
- yimo/kit/db/models/__init__.py +33 -0
- yimo/kit/db/models/base.py +56 -0
- yimo/kit/db/mysql_kit.py +348 -0
- yimo/kit/db/pg_kit.py +442 -0
- yimo/kit/db/query.py +338 -0
- yimo/kit/db/session.py +85 -0
- yimo/kit/db/sqlite_kit.py +462 -0
- yimo/kit/db/transaction.py +109 -0
- yimo/kit/docs/__init__.py +34 -0
- yimo/kit/docs/anydoc_kit.py +490 -0
- yimo/kit/docs/docx_kit.py +895 -0
- yimo/kit/docs/md2doc_kit.py +1801 -0
- yimo/kit/docs/mineru_kit.py +1497 -0
- yimo/kit/docs/rc_docparser_kit.py +654 -0
- yimo/kit/file_kit.py +518 -0
- yimo/kit/license_kit.py +533 -0
- yimo/kit/redis_kit.py +392 -0
- yimo_kit-0.1.0.dist-info/METADATA +1673 -0
- yimo_kit-0.1.0.dist-info/RECORD +70 -0
- yimo_kit-0.1.0.dist-info/WHEEL +4 -0
- yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,724 @@
|
|
|
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-08-21
|
|
21
|
+
# refactor: 2026-11-04 传输层改 openai SDK(调用签名与 StreamStats 语义不变)
|
|
22
|
+
"""对话类模型服务(全异步,openai SDK 传输)。"""
|
|
23
|
+
|
|
24
|
+
import logging
|
|
25
|
+
import threading
|
|
26
|
+
import time
|
|
27
|
+
from collections.abc import AsyncIterator, Mapping, Sequence
|
|
28
|
+
from dataclasses import dataclass
|
|
29
|
+
from typing import Any, ClassVar, Final, Protocol, cast
|
|
30
|
+
|
|
31
|
+
from yimo.kit.ai._internal.sdk_client import SdkServiceBase
|
|
32
|
+
from yimo.kit.ai._internal.types import JSONObject
|
|
33
|
+
from yimo.kit.ai.exceptions import AIConfigError, AIError, AIResponseError
|
|
34
|
+
from yimo.kit.ai.messages import ChatReply, Message
|
|
35
|
+
from yimo.kit.ai.profiles import (
|
|
36
|
+
_RESERVED_PAYLOAD_KEYS,
|
|
37
|
+
ModelProfile,
|
|
38
|
+
resolve_max_tokens,
|
|
39
|
+
)
|
|
40
|
+
from yimo.kit.config.log_config import get_default_logger
|
|
41
|
+
|
|
42
|
+
__all__ = ["ChatRequest", "ChatService", "Message", "StreamStats"]
|
|
43
|
+
|
|
44
|
+
logger = get_default_logger(__name__)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class ToolSpecLike(Protocol):
|
|
48
|
+
"""工具声明的结构化契约(Agent 的 ``ToolSpec`` 满足本协议)。"""
|
|
49
|
+
|
|
50
|
+
name: str
|
|
51
|
+
description: str
|
|
52
|
+
input_schema: dict[str, Any]
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _tool_field(tool: ToolSpecLike | Mapping[str, Any], key: str) -> Any:
|
|
56
|
+
"""读取工具声明字段,兼容 dataclass 与 dict 两种形态。"""
|
|
57
|
+
if isinstance(tool, Mapping):
|
|
58
|
+
return tool[key]
|
|
59
|
+
return getattr(tool, key)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _wrap_tools(
|
|
63
|
+
tools: Sequence[ToolSpecLike | Mapping[str, Any]],
|
|
64
|
+
) -> list[dict[str, Any]]:
|
|
65
|
+
"""把 ToolSpec 转换为 OpenAI 的 function 工具结构(字段改名在此完成)。"""
|
|
66
|
+
wrapped: list[dict[str, Any]] = []
|
|
67
|
+
for tool in tools:
|
|
68
|
+
wrapped.append(
|
|
69
|
+
{
|
|
70
|
+
"type": "function",
|
|
71
|
+
"function": {
|
|
72
|
+
"name": _tool_field(tool, "name"),
|
|
73
|
+
"description": _tool_field(tool, "description"),
|
|
74
|
+
"parameters": _tool_field(tool, "input_schema"),
|
|
75
|
+
},
|
|
76
|
+
}
|
|
77
|
+
)
|
|
78
|
+
return wrapped
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
# 推理(思考)内容可能的字段名:GLM / DeepSeek / Qwen 用 reasoning_content,
|
|
82
|
+
# sensenova 用 reasoning(流式为 delta.*,非流式为 message.*)
|
|
83
|
+
_REASONING_KEYS: Final[tuple[str, ...]] = ("reasoning_content", "reasoning")
|
|
84
|
+
|
|
85
|
+
# 截断判定:OpenAI 系给 length,部分兼容端点给 max_tokens
|
|
86
|
+
_TRUNCATED_REASONS: Final[frozenset[str]] = frozenset({"length", "max_tokens"})
|
|
87
|
+
|
|
88
|
+
# 空正文诊断分级 → 告警文案(正文为 0 时才有分级,见 _classify_empty)
|
|
89
|
+
_EMPTY_HINTS: Final[dict[str, str]] = {
|
|
90
|
+
"budget_exhausted": "输出预算疑被思考耗尽(长度截断)",
|
|
91
|
+
"truncated_empty": "输出被长度截断、正文为空(无推理)",
|
|
92
|
+
"reasoning_only": "只产出推理、正文为空(finish=stop)",
|
|
93
|
+
"no_finish": "正文为空且未收到正常结束原因",
|
|
94
|
+
"stopped_empty": "无正文输出(finish=stop)",
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
_EMPTY_ACTIONS: Final[dict[str, str]] = {
|
|
98
|
+
"budget_exhausted": "(可调大 max_tokens,或对该调用传 thinking=False 关闭思考)",
|
|
99
|
+
"truncated_empty": "(调大 max_tokens;若模型支持独立推理预算,确认推理是否计入输出配额)",
|
|
100
|
+
"reasoning_only": "(推理未触顶但正文为空,可提高预算或换模型)",
|
|
101
|
+
"no_finish": "(端点未发送 finish_reason 或异常结束,可原样重试)",
|
|
102
|
+
"stopped_empty": "(检查提示词与模型输出)",
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _classify_empty(
|
|
107
|
+
*,
|
|
108
|
+
content_chars: int,
|
|
109
|
+
reasoning_chars: int,
|
|
110
|
+
finish_reason: str | None,
|
|
111
|
+
truncated: bool,
|
|
112
|
+
) -> str | None:
|
|
113
|
+
"""空正文诊断分级;正文非空返回 None。
|
|
114
|
+
|
|
115
|
+
- ``budget_exhausted``:被截断且有推理(预算被思考吃满)
|
|
116
|
+
- ``truncated_empty``:被截断且无推理(一个正文字符都没出)
|
|
117
|
+
- ``reasoning_only``:有推理、``finish_reason=stop``
|
|
118
|
+
- ``no_finish``:结束原因缺失或非 stop(无论有无推理)
|
|
119
|
+
- ``stopped_empty``:无推理、``finish_reason=stop``
|
|
120
|
+
"""
|
|
121
|
+
if content_chars:
|
|
122
|
+
return None
|
|
123
|
+
if truncated:
|
|
124
|
+
return "budget_exhausted" if reasoning_chars else "truncated_empty"
|
|
125
|
+
if reasoning_chars:
|
|
126
|
+
return "reasoning_only" if finish_reason == "stop" else "no_finish"
|
|
127
|
+
if finish_reason == "stop":
|
|
128
|
+
return "stopped_empty"
|
|
129
|
+
return "no_finish"
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
# 「无注入值」哨兵:区分「不注入」与「注入值为 None」
|
|
133
|
+
_UNSET: Final[object] = object()
|
|
134
|
+
|
|
135
|
+
# 思考开关告警去重:同一档案同一原因进程内只报一次(批处理会高频调用)
|
|
136
|
+
_WARNED: set[tuple[str, str]] = set()
|
|
137
|
+
_WARNED_LOCK: Final[threading.Lock] = threading.Lock()
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _warn_once(
|
|
141
|
+
profile_name: str,
|
|
142
|
+
reason: str,
|
|
143
|
+
*,
|
|
144
|
+
kind: str = "思考开关",
|
|
145
|
+
level: int = logging.WARNING,
|
|
146
|
+
) -> None:
|
|
147
|
+
"""线程安全的告警去重:``(档案名, 原因)`` 只报一次(可指定级别)。"""
|
|
148
|
+
key = (profile_name, reason)
|
|
149
|
+
with _WARNED_LOCK:
|
|
150
|
+
if key in _WARNED:
|
|
151
|
+
return
|
|
152
|
+
_WARNED.add(key)
|
|
153
|
+
logger.log(level, f"{kind}:{reason}(档案 {profile_name})")
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def reset_warned() -> None:
|
|
157
|
+
"""清空告警去重表(配置热重载后重新提示,避免旧原因被永久压制)。
|
|
158
|
+
|
|
159
|
+
供 :func:`yimo.kit.ai.runner.reload_config` 调用;线程安全。
|
|
160
|
+
"""
|
|
161
|
+
with _WARNED_LOCK:
|
|
162
|
+
_WARNED.clear()
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def _resolve_thinking(
|
|
166
|
+
profile: ModelProfile, thinking: bool | None
|
|
167
|
+
) -> tuple[object, bool | None, str | None, int]:
|
|
168
|
+
"""解析本次调用的思考开关。
|
|
169
|
+
|
|
170
|
+
逐调用 ``thinking`` 优先,未传时回落档案 ``thinking.default``(三态)。
|
|
171
|
+
|
|
172
|
+
Returns:
|
|
173
|
+
``(注入值 | _UNSET, 是否生效, 提示语, 日志级别)``。
|
|
174
|
+
是否生效为 None 表示本次未对请求体做思考相关注入(未要求,或档案
|
|
175
|
+
只声明了 ``off`` 而没声明 ``on``——按厂商默认处理);False 表示
|
|
176
|
+
要求了但档案完全没有 ``thinking`` 声明(不支持、不注入、不报错、
|
|
177
|
+
不影响候选链冷却)。
|
|
178
|
+
"""
|
|
179
|
+
spec = profile.thinking
|
|
180
|
+
mode = thinking if thinking is not None else (spec.default if spec else None)
|
|
181
|
+
if mode is None:
|
|
182
|
+
return _UNSET, None, None, logging.WARNING
|
|
183
|
+
if spec is None:
|
|
184
|
+
return _UNSET, False, "档案未声明思考开关,本次请求被忽略", logging.WARNING
|
|
185
|
+
if mode and spec.on is None:
|
|
186
|
+
# 只声明 off:开启只能走厂商默认(主流模型默认开启),不算「未生效」
|
|
187
|
+
return (
|
|
188
|
+
_UNSET,
|
|
189
|
+
None,
|
|
190
|
+
"档案未声明开启取值,按厂商默认处理",
|
|
191
|
+
logging.INFO,
|
|
192
|
+
)
|
|
193
|
+
return (spec.off if mode is False else spec.on), True, None, logging.WARNING
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
@dataclass
|
|
197
|
+
class StreamStats:
|
|
198
|
+
"""对话收尾统计(可变累加器:调用方传入,kit 累加)。
|
|
199
|
+
|
|
200
|
+
流式与非流式共用:``ask`` / ``complete`` 传入后在返回前写满,
|
|
201
|
+
``stream`` 传入后流结束时为最终值。
|
|
202
|
+
跨线程共享(后台事件循环写、业务线程读):**结束后为最终值**,
|
|
203
|
+
流式过程中读到的是尽力而为的中间值。
|
|
204
|
+
|
|
205
|
+
``reasoning_chars`` / ``content_chars`` 均为**字符数**,与 ``max_tokens``
|
|
206
|
+
(token)不可换算(实测中文约 2~2.5 字符/token,且各 provider 口径不一),
|
|
207
|
+
仅用于「是否发生思考 / 是否被长度截断」的判定。
|
|
208
|
+
|
|
209
|
+
Attributes:
|
|
210
|
+
reasoning_chars: 推理(思考)内容字符数;非思考模型恒为 0
|
|
211
|
+
content_chars: 已产出正文字符数(等于调用方收到的字符数)
|
|
212
|
+
finish_reason: 结束原因(stop / length / content_filter / …);
|
|
213
|
+
provider 未给出时为 None
|
|
214
|
+
thinking_applied: 思考开关是否生效——None 本次未对请求体做思考注入
|
|
215
|
+
(未要求,或档案只声明 off 未声明 on,按厂商默认处理)/
|
|
216
|
+
True 已按档案声明注入 / False 要求了但档案完全没有 thinking 声明
|
|
217
|
+
json_mode_applied: 结构化输出是否生效——None 本次未要求注入 /
|
|
218
|
+
True 已注入 / False 要求了但档案声明不支持(已忽略)
|
|
219
|
+
requested_max_tokens: 本次实际下发的输出上限(调用方 → 档案回落);
|
|
220
|
+
None 表示未下发、由 provider 默认值决定。在发出请求前写入,
|
|
221
|
+
失败/中断时也可读
|
|
222
|
+
|
|
223
|
+
只读派生属性:``truncated``(是否截断)、``empty_kind``(正文为空时的
|
|
224
|
+
诊断分级:``budget_exhausted`` / ``truncated_empty`` / ``reasoning_only`` /
|
|
225
|
+
``no_finish`` / ``stopped_empty``;正文非空为 None)。
|
|
226
|
+
"""
|
|
227
|
+
|
|
228
|
+
reasoning_chars: int = 0
|
|
229
|
+
content_chars: int = 0
|
|
230
|
+
finish_reason: str | None = None
|
|
231
|
+
thinking_applied: bool | None = None
|
|
232
|
+
json_mode_applied: bool | None = None
|
|
233
|
+
requested_max_tokens: int | None = None
|
|
234
|
+
|
|
235
|
+
@property
|
|
236
|
+
def truncated(self) -> bool:
|
|
237
|
+
"""是否因输出长度上限被截断。"""
|
|
238
|
+
return self.finish_reason in _TRUNCATED_REASONS
|
|
239
|
+
|
|
240
|
+
@property
|
|
241
|
+
def empty_kind(self) -> str | None:
|
|
242
|
+
"""正文为空时的诊断分级;正文非空返回 None。
|
|
243
|
+
|
|
244
|
+
取值:``budget_exhausted`` / ``truncated_empty`` / ``reasoning_only`` /
|
|
245
|
+
``no_finish`` / ``stopped_empty``。不依赖 token 数量,用「是否截断 +
|
|
246
|
+
是否有推理 + 结束原因」区分「预算吃满」「截断且无正文」「只推理」
|
|
247
|
+
「未正常收尾」「正常停住」。
|
|
248
|
+
"""
|
|
249
|
+
return _classify_empty(
|
|
250
|
+
content_chars=self.content_chars,
|
|
251
|
+
reasoning_chars=self.reasoning_chars,
|
|
252
|
+
finish_reason=self.finish_reason,
|
|
253
|
+
truncated=self.truncated,
|
|
254
|
+
)
|
|
255
|
+
|
|
256
|
+
def reset(self) -> None:
|
|
257
|
+
"""清零(候选链切换到下一个档案前调用)。"""
|
|
258
|
+
self.reasoning_chars = 0
|
|
259
|
+
self.content_chars = 0
|
|
260
|
+
self.finish_reason = None
|
|
261
|
+
self.thinking_applied = None
|
|
262
|
+
self.json_mode_applied = None
|
|
263
|
+
self.requested_max_tokens = None
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
@dataclass(frozen=True)
|
|
267
|
+
class ChatRequest:
|
|
268
|
+
"""对话请求模型。"""
|
|
269
|
+
|
|
270
|
+
messages: list[Message]
|
|
271
|
+
temperature: float | None = None
|
|
272
|
+
max_tokens: int | None = None
|
|
273
|
+
stream: bool = False
|
|
274
|
+
# 思考开关:None 不干预(请求体逐字节不变)/ True 开 / False 关
|
|
275
|
+
thinking: bool | None = None
|
|
276
|
+
# 结构化输出:None 不干预 / True 要求 JSON 对象 / False 与 None 等效
|
|
277
|
+
json_mode: bool | None = None
|
|
278
|
+
# 协议级逃生口:原样写入请求体(含 json_schema 严格模式),与 json_mode 互斥
|
|
279
|
+
response_format: dict[str, Any] | None = None
|
|
280
|
+
# 收尾统计累加器(不参与请求参数)
|
|
281
|
+
stats: StreamStats | None = None
|
|
282
|
+
|
|
283
|
+
def __post_init__(self) -> None:
|
|
284
|
+
if self.json_mode is not None and self.response_format is not None:
|
|
285
|
+
raise ValueError("json_mode 与 response_format 互斥,只能给一个")
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def _resolve_structured_output(
|
|
289
|
+
profile: ModelProfile, request: ChatRequest
|
|
290
|
+
) -> tuple[str, object, bool | None, str | None]:
|
|
291
|
+
"""解析本次调用的结构化输出注入。
|
|
292
|
+
|
|
293
|
+
``response_format`` 逐调用透传优先;否则按 ``json_mode`` 取档案声明
|
|
294
|
+
(未声明即内置协议默认)。
|
|
295
|
+
|
|
296
|
+
Returns:
|
|
297
|
+
``(请求体键名, 注入值 | _UNSET, 是否生效, 告警原因)``。是否生效为
|
|
298
|
+
None 表示本次未要求注入(请求体不变);False 表示要求了但档案显式
|
|
299
|
+
声明不支持(不注入、不报错、不影响候选链冷却)。
|
|
300
|
+
"""
|
|
301
|
+
spec = profile.structured_output
|
|
302
|
+
if request.response_format is not None:
|
|
303
|
+
arg = spec.arg if spec is not None else "response_format"
|
|
304
|
+
return arg, request.response_format, True, None
|
|
305
|
+
if not request.json_mode: # None / False 均不干预
|
|
306
|
+
return "", _UNSET, None, None
|
|
307
|
+
if spec is None:
|
|
308
|
+
return "", _UNSET, False, "档案声明不支持结构化输出,本次请求被忽略"
|
|
309
|
+
return spec.arg, spec.json_mode, True, None
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
class ChatService(SdkServiceBase):
|
|
313
|
+
"""对话类模型服务(全异步)。"""
|
|
314
|
+
|
|
315
|
+
_LABEL: ClassVar[str] = "对话模型"
|
|
316
|
+
|
|
317
|
+
# ------------------------------------------------------------------
|
|
318
|
+
# 请求增强:思考开关 + 结构化输出 → extra_body / response_format
|
|
319
|
+
# ------------------------------------------------------------------
|
|
320
|
+
|
|
321
|
+
def _build_injection(
|
|
322
|
+
self, request: ChatRequest
|
|
323
|
+
) -> tuple[JSONObject, JSONObject | None]:
|
|
324
|
+
"""把档案声明翻译成 SDK 调用参数。
|
|
325
|
+
|
|
326
|
+
Returns:
|
|
327
|
+
``(extra_body, response_format)``。``extra_body`` 为档案级
|
|
328
|
+
额外字段与思考开关的合并结果;``response_format`` 为 None 表示
|
|
329
|
+
不注入结构化输出要求。
|
|
330
|
+
"""
|
|
331
|
+
# 保留键(model / messages / stream / max_tokens / temperature 等)
|
|
332
|
+
# 由服务侧显式构造,不允许档案 extra_body 覆盖(0.6.9 由 payload
|
|
333
|
+
# 覆盖实现,SDK 侧无此层,故在此剔除)
|
|
334
|
+
extra: dict[str, Any] = {
|
|
335
|
+
key: value
|
|
336
|
+
for key, value in (self._profile.extra_body or {}).items()
|
|
337
|
+
if key not in _RESERVED_PAYLOAD_KEYS
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
thinking_value, thinking_applied, thinking_reason, thinking_level = (
|
|
341
|
+
_resolve_thinking(self._profile, request.thinking)
|
|
342
|
+
)
|
|
343
|
+
if thinking_reason is not None:
|
|
344
|
+
_warn_once(
|
|
345
|
+
self._profile.name, thinking_reason, level=thinking_level
|
|
346
|
+
)
|
|
347
|
+
if thinking_value is not _UNSET:
|
|
348
|
+
spec = self._profile.thinking
|
|
349
|
+
if spec is None: # 类型收窄:applied 为 True 时 spec 必非 None
|
|
350
|
+
thinking_applied = False
|
|
351
|
+
elif spec.arg in _RESERVED_PAYLOAD_KEYS:
|
|
352
|
+
_warn_once(
|
|
353
|
+
self._profile.name,
|
|
354
|
+
f"思考开关键 {spec.arg!r} 与请求体保留键冲突,已忽略",
|
|
355
|
+
)
|
|
356
|
+
thinking_applied = False
|
|
357
|
+
else:
|
|
358
|
+
current = extra.get(spec.arg)
|
|
359
|
+
merged: Any = (
|
|
360
|
+
{**current, **thinking_value}
|
|
361
|
+
if isinstance(current, dict) and isinstance(thinking_value, dict)
|
|
362
|
+
else thinking_value
|
|
363
|
+
)
|
|
364
|
+
declared = (self._profile.extra_body or {}).get(spec.arg)
|
|
365
|
+
if declared is not None and declared != merged:
|
|
366
|
+
_warn_once(
|
|
367
|
+
self._profile.name,
|
|
368
|
+
f"已覆盖档案 extra_body 的同名字段 {spec.arg!r}",
|
|
369
|
+
)
|
|
370
|
+
extra[spec.arg] = merged
|
|
371
|
+
|
|
372
|
+
if request.stats is not None:
|
|
373
|
+
request.stats.thinking_applied = thinking_applied
|
|
374
|
+
|
|
375
|
+
arg, value, applied, reason = _resolve_structured_output(
|
|
376
|
+
self._profile, request
|
|
377
|
+
)
|
|
378
|
+
if reason is not None:
|
|
379
|
+
_warn_once(self._profile.name, reason, kind="结构化输出")
|
|
380
|
+
response_format: JSONObject | None = None
|
|
381
|
+
if value is not _UNSET:
|
|
382
|
+
if arg in _RESERVED_PAYLOAD_KEYS:
|
|
383
|
+
_warn_once(
|
|
384
|
+
self._profile.name,
|
|
385
|
+
f"结构化输出键 {arg!r} 与请求体保留键冲突,已忽略",
|
|
386
|
+
kind="结构化输出",
|
|
387
|
+
)
|
|
388
|
+
applied = False
|
|
389
|
+
elif arg == "response_format":
|
|
390
|
+
# 整键替换:档案 extra_body 的同名字段必须剔除,否则会与
|
|
391
|
+
# 参数同名冲突(SDK 会把 extra_body 并入请求体)
|
|
392
|
+
declared = extra.pop("response_format", None)
|
|
393
|
+
if declared is not None and declared != value:
|
|
394
|
+
_warn_once(
|
|
395
|
+
self._profile.name,
|
|
396
|
+
"已覆盖档案 extra_body 的同名字段 'response_format'",
|
|
397
|
+
kind="结构化输出",
|
|
398
|
+
)
|
|
399
|
+
response_format = cast(JSONObject, value)
|
|
400
|
+
else:
|
|
401
|
+
# 厂商自定义键名:走 extra_body
|
|
402
|
+
extra[arg] = value
|
|
403
|
+
if request.stats is not None:
|
|
404
|
+
request.stats.json_mode_applied = applied
|
|
405
|
+
|
|
406
|
+
return cast(JSONObject, extra), response_format
|
|
407
|
+
|
|
408
|
+
# ------------------------------------------------------------------
|
|
409
|
+
# 非流式
|
|
410
|
+
# ------------------------------------------------------------------
|
|
411
|
+
|
|
412
|
+
async def create(
|
|
413
|
+
self,
|
|
414
|
+
messages: list[Message],
|
|
415
|
+
*,
|
|
416
|
+
temperature: float | None = None,
|
|
417
|
+
max_tokens: int | None = None,
|
|
418
|
+
thinking: bool | None = None,
|
|
419
|
+
json_mode: bool | None = None,
|
|
420
|
+
response_format: dict[str, Any] | None = None,
|
|
421
|
+
stats: StreamStats | None = None,
|
|
422
|
+
deadline: float | None = None,
|
|
423
|
+
) -> str:
|
|
424
|
+
"""多轮对话,返回模型回答文本。
|
|
425
|
+
|
|
426
|
+
Args:
|
|
427
|
+
thinking: 思考开关;None 不干预(按档案 ``thinking.default``,
|
|
428
|
+
仍未配置则请求体不变)/ True 开 / False 关。档案无声明时
|
|
429
|
+
忽略并告警(不报错、不触发冷却)
|
|
430
|
+
json_mode: 结构化输出;None/False 不干预 / True 要求 JSON 对象
|
|
431
|
+
(取值按档案 ``structured_output``,未声明用内置协议默认;
|
|
432
|
+
档案写 ``false`` 则忽略并告警)
|
|
433
|
+
response_format: 协议级原样透传(含 ``json_schema`` 严格模式);
|
|
434
|
+
与 ``json_mode`` 互斥,schema 由调用方负责
|
|
435
|
+
stats: 收尾统计累加器(可选);传入后可读 ``finish_reason`` /
|
|
436
|
+
``truncated`` / ``empty_kind`` / ``requested_max_tokens`` /
|
|
437
|
+
``reasoning_chars`` / ``json_mode_applied``
|
|
438
|
+
deadline: 整链预算截止时刻(``time.monotonic()`` 秒),约束
|
|
439
|
+
5xx 重试预算;None 表示不限制
|
|
440
|
+
"""
|
|
441
|
+
request = ChatRequest(
|
|
442
|
+
messages,
|
|
443
|
+
temperature=temperature,
|
|
444
|
+
max_tokens=max_tokens,
|
|
445
|
+
thinking=thinking,
|
|
446
|
+
json_mode=json_mode,
|
|
447
|
+
response_format=response_format,
|
|
448
|
+
stats=stats,
|
|
449
|
+
)
|
|
450
|
+
extra_body, response_format_arg = self._build_injection(request)
|
|
451
|
+
effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
|
|
452
|
+
if stats is not None:
|
|
453
|
+
stats.requested_max_tokens = effective_max_tokens
|
|
454
|
+
self._debug_payload(
|
|
455
|
+
{
|
|
456
|
+
"model": self._profile.model,
|
|
457
|
+
"messages": request.messages,
|
|
458
|
+
"extra_body": extra_body,
|
|
459
|
+
"response_format": response_format_arg,
|
|
460
|
+
}
|
|
461
|
+
)
|
|
462
|
+
with self._log_call():
|
|
463
|
+
content, reasoning, finish = await self._client.chat(
|
|
464
|
+
messages=request.messages,
|
|
465
|
+
extra_body=extra_body,
|
|
466
|
+
response_format=response_format_arg,
|
|
467
|
+
temperature=request.temperature,
|
|
468
|
+
max_tokens=request.max_tokens,
|
|
469
|
+
deadline=deadline,
|
|
470
|
+
)
|
|
471
|
+
if stats is not None:
|
|
472
|
+
stats.finish_reason = finish
|
|
473
|
+
stats.content_chars = len(content) if isinstance(content, str) else 0
|
|
474
|
+
stats.reasoning_chars = len(reasoning)
|
|
475
|
+
if not isinstance(content, str):
|
|
476
|
+
if finish in _TRUNCATED_REASONS and reasoning:
|
|
477
|
+
# 思考型模型截断时可能完全不返回 content(实测 sensenova)
|
|
478
|
+
raise AIResponseError(
|
|
479
|
+
f"输出预算被思考耗尽:finish_reason={finish},"
|
|
480
|
+
f"推理 {len(reasoning)} 字符、正文为空"
|
|
481
|
+
"(请调大 max_tokens,或对该调用传 thinking=False 关闭思考)"
|
|
482
|
+
)
|
|
483
|
+
raise AIResponseError(f"content 类型异常: {type(content).__name__}")
|
|
484
|
+
truncated = finish in _TRUNCATED_REASONS
|
|
485
|
+
kind = _classify_empty(
|
|
486
|
+
content_chars=len(content),
|
|
487
|
+
reasoning_chars=len(reasoning),
|
|
488
|
+
finish_reason=finish,
|
|
489
|
+
truncated=truncated,
|
|
490
|
+
)
|
|
491
|
+
if kind is not None:
|
|
492
|
+
self._log_empty(
|
|
493
|
+
kind=kind,
|
|
494
|
+
max_tokens=effective_max_tokens,
|
|
495
|
+
finish=finish,
|
|
496
|
+
reasoning_chars=len(reasoning),
|
|
497
|
+
)
|
|
498
|
+
elif truncated:
|
|
499
|
+
logger.warning(
|
|
500
|
+
f"{self._log_desc()} 输出被长度截断(finish_reason={finish}):"
|
|
501
|
+
f"推理 {len(reasoning)} 字符 / 正文 {len(content)} 字符"
|
|
502
|
+
"(可调大 max_tokens,或对该调用传 thinking=False 关闭思考)"
|
|
503
|
+
)
|
|
504
|
+
return content
|
|
505
|
+
|
|
506
|
+
async def create_with_tools(
|
|
507
|
+
self,
|
|
508
|
+
messages: list[Message],
|
|
509
|
+
tools: Sequence[ToolSpecLike | Mapping[str, Any]],
|
|
510
|
+
*,
|
|
511
|
+
tool_choice: str | dict[str, Any] | None = None,
|
|
512
|
+
temperature: float | None = None,
|
|
513
|
+
max_tokens: int | None = None,
|
|
514
|
+
thinking: bool | None = None,
|
|
515
|
+
stats: StreamStats | None = None,
|
|
516
|
+
deadline: float | None = None,
|
|
517
|
+
) -> ChatReply:
|
|
518
|
+
"""带工具定义的非流式对话,返回含 ``tool_calls`` 的完整回复。
|
|
519
|
+
|
|
520
|
+
与 :meth:`create` 的边界(E7):
|
|
521
|
+
|
|
522
|
+
- 不接受 ``json_mode`` / ``response_format``:工具调用与结构化输出
|
|
523
|
+
在部分厂商互斥,同时传会得到 400 或静默忽略;
|
|
524
|
+
- ``tools`` 为空时不下发该字段(不是传空数组);
|
|
525
|
+
- 正文为空但存在 ``tool_calls`` 时**不报错**,由调用方(Agent)
|
|
526
|
+
决定终止条件。
|
|
527
|
+
|
|
528
|
+
Args:
|
|
529
|
+
messages: 完整的消息列表(含历史与工具回灌)
|
|
530
|
+
tools: 工具声明序列;元素可为 :class:`ToolSpecLike` 或同形 dict
|
|
531
|
+
tool_choice: ``"auto"`` / ``"none"`` / 指定函数结构;None 不下发
|
|
532
|
+
temperature: 采样温度
|
|
533
|
+
max_tokens: 输出上限(回落档案配置)
|
|
534
|
+
thinking: 思考开关(语义同 :meth:`create`)
|
|
535
|
+
stats: 收尾统计累加器
|
|
536
|
+
deadline: 整链预算截止时刻(``time.monotonic()`` 秒)
|
|
537
|
+
"""
|
|
538
|
+
if self._profile.supports_tools is False:
|
|
539
|
+
raise AIConfigError(
|
|
540
|
+
f"档案 {self._profile.name} 声明不支持 tools"
|
|
541
|
+
"(supports_tools=false),请改用支持 function calling 的档案"
|
|
542
|
+
)
|
|
543
|
+
request = ChatRequest(
|
|
544
|
+
messages,
|
|
545
|
+
temperature=temperature,
|
|
546
|
+
max_tokens=max_tokens,
|
|
547
|
+
thinking=thinking,
|
|
548
|
+
stats=stats,
|
|
549
|
+
)
|
|
550
|
+
extra_body, _ = self._build_injection(request)
|
|
551
|
+
effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
|
|
552
|
+
if stats is not None:
|
|
553
|
+
stats.requested_max_tokens = effective_max_tokens
|
|
554
|
+
wrapped = _wrap_tools(tools) if tools else None
|
|
555
|
+
self._debug_payload(
|
|
556
|
+
{
|
|
557
|
+
"model": self._profile.model,
|
|
558
|
+
"messages": request.messages,
|
|
559
|
+
"tools": [
|
|
560
|
+
item["function"]["name"] for item in wrapped or []
|
|
561
|
+
],
|
|
562
|
+
"extra_body": extra_body,
|
|
563
|
+
}
|
|
564
|
+
)
|
|
565
|
+
with self._log_call():
|
|
566
|
+
reply = await self._client.chat_raw(
|
|
567
|
+
messages=cast(list[dict[str, Any]], request.messages),
|
|
568
|
+
tools=wrapped,
|
|
569
|
+
tool_choice=tool_choice,
|
|
570
|
+
extra_body=extra_body,
|
|
571
|
+
temperature=request.temperature,
|
|
572
|
+
max_tokens=request.max_tokens,
|
|
573
|
+
deadline=deadline,
|
|
574
|
+
)
|
|
575
|
+
if stats is not None:
|
|
576
|
+
stats.finish_reason = reply.finish_reason
|
|
577
|
+
stats.content_chars = len(reply.content) if reply.content else 0
|
|
578
|
+
stats.reasoning_chars = len(reply.reasoning)
|
|
579
|
+
return reply
|
|
580
|
+
|
|
581
|
+
async def create_once(
|
|
582
|
+
self,
|
|
583
|
+
prompt: str,
|
|
584
|
+
*,
|
|
585
|
+
temperature: float | None = None,
|
|
586
|
+
max_tokens: int | None = None,
|
|
587
|
+
thinking: bool | None = None,
|
|
588
|
+
json_mode: bool | None = None,
|
|
589
|
+
response_format: dict[str, Any] | None = None,
|
|
590
|
+
stats: StreamStats | None = None,
|
|
591
|
+
deadline: float | None = None,
|
|
592
|
+
) -> str:
|
|
593
|
+
"""单轮对话(语义同 :meth:`create`,参数含义一致)。"""
|
|
594
|
+
messages: list[Message] = [{"role": "user", "content": prompt}]
|
|
595
|
+
return await self.create(
|
|
596
|
+
messages,
|
|
597
|
+
temperature=temperature,
|
|
598
|
+
max_tokens=max_tokens,
|
|
599
|
+
thinking=thinking,
|
|
600
|
+
json_mode=json_mode,
|
|
601
|
+
response_format=response_format,
|
|
602
|
+
stats=stats,
|
|
603
|
+
deadline=deadline,
|
|
604
|
+
)
|
|
605
|
+
|
|
606
|
+
# ------------------------------------------------------------------
|
|
607
|
+
# 流式
|
|
608
|
+
# ------------------------------------------------------------------
|
|
609
|
+
|
|
610
|
+
async def create_stream(
|
|
611
|
+
self,
|
|
612
|
+
messages: list[Message],
|
|
613
|
+
*,
|
|
614
|
+
temperature: float | None = None,
|
|
615
|
+
max_tokens: int | None = None,
|
|
616
|
+
thinking: bool | None = None,
|
|
617
|
+
json_mode: bool | None = None,
|
|
618
|
+
response_format: dict[str, Any] | None = None,
|
|
619
|
+
stats: StreamStats | None = None,
|
|
620
|
+
) -> AsyncIterator[str]:
|
|
621
|
+
"""流式对话,逐 token 产出正文。
|
|
622
|
+
|
|
623
|
+
Args:
|
|
624
|
+
thinking: 思考开关(语义同 :meth:`create`);是否真正生效记在
|
|
625
|
+
``stats.thinking_applied``(None 未干预 / True 已注入 /
|
|
626
|
+
False 被忽略)
|
|
627
|
+
json_mode: 结构化输出要求(语义同 :meth:`create`);是否注入记在
|
|
628
|
+
``stats.json_mode_applied``。注意流式下 JSON 只能是半成品,
|
|
629
|
+
kit 不做增量解析
|
|
630
|
+
response_format: 协议级原样透传(与 ``json_mode`` 互斥)
|
|
631
|
+
stats: 收尾统计累加器(可选);None 时内部创建后丢弃——需要
|
|
632
|
+
``reasoning_chars`` / ``finish_reason`` / ``truncated`` /
|
|
633
|
+
``empty_kind`` / ``requested_max_tokens`` 时由调用方传入
|
|
634
|
+
|
|
635
|
+
推理内容(``delta.reasoning_content`` / ``delta.reasoning``)只计数
|
|
636
|
+
不产出;正文为空时按 ``empty_kind`` 分级输出 warning(不依赖是否有
|
|
637
|
+
推理或是否截断)。
|
|
638
|
+
"""
|
|
639
|
+
stats = stats if stats is not None else StreamStats()
|
|
640
|
+
request = ChatRequest(
|
|
641
|
+
messages,
|
|
642
|
+
temperature=temperature,
|
|
643
|
+
max_tokens=max_tokens,
|
|
644
|
+
stream=True,
|
|
645
|
+
thinking=thinking,
|
|
646
|
+
json_mode=json_mode,
|
|
647
|
+
response_format=response_format,
|
|
648
|
+
stats=stats,
|
|
649
|
+
)
|
|
650
|
+
extra_body, response_format_arg = self._build_injection(request)
|
|
651
|
+
effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
|
|
652
|
+
stats.requested_max_tokens = effective_max_tokens
|
|
653
|
+
desc = self._log_desc()
|
|
654
|
+
# 惰性 Start:异步生成器体在首次 __anext__ 前不执行,不消费不打日志
|
|
655
|
+
logger.info(f"********** {desc} ********** Start")
|
|
656
|
+
self._debug_payload(
|
|
657
|
+
{
|
|
658
|
+
"model": self._profile.model,
|
|
659
|
+
"messages": request.messages,
|
|
660
|
+
"extra_body": extra_body,
|
|
661
|
+
"response_format": response_format_arg,
|
|
662
|
+
"stream": True,
|
|
663
|
+
}
|
|
664
|
+
)
|
|
665
|
+
start = time.perf_counter()
|
|
666
|
+
note = ""
|
|
667
|
+
failed = False
|
|
668
|
+
try:
|
|
669
|
+
async for content, reasoning, finish in self._client.chat_stream(
|
|
670
|
+
messages=request.messages,
|
|
671
|
+
extra_body=extra_body,
|
|
672
|
+
response_format=response_format_arg,
|
|
673
|
+
temperature=request.temperature,
|
|
674
|
+
max_tokens=request.max_tokens,
|
|
675
|
+
):
|
|
676
|
+
if finish:
|
|
677
|
+
stats.finish_reason = finish
|
|
678
|
+
if reasoning:
|
|
679
|
+
stats.reasoning_chars += len(reasoning)
|
|
680
|
+
if content:
|
|
681
|
+
stats.content_chars += len(content)
|
|
682
|
+
yield content
|
|
683
|
+
except AIError as exc:
|
|
684
|
+
note = f"(失败:{exc})"
|
|
685
|
+
failed = True
|
|
686
|
+
raise
|
|
687
|
+
except BaseException: # noqa: BLE001 - 中断路径(提前 break/取消)也需收尾日志
|
|
688
|
+
note = "(中断)"
|
|
689
|
+
raise
|
|
690
|
+
else:
|
|
691
|
+
self._warn_if_empty(stats, effective_max_tokens)
|
|
692
|
+
finally:
|
|
693
|
+
log = logger.error if failed else logger.info
|
|
694
|
+
log(
|
|
695
|
+
f"********** {desc} ********** "
|
|
696
|
+
f"耗时 {time.perf_counter() - start:.1f}秒{note}"
|
|
697
|
+
)
|
|
698
|
+
|
|
699
|
+
def _warn_if_empty(self, stats: StreamStats, max_tokens: int | None) -> None:
|
|
700
|
+
"""正文为空时按诊断分级告警(不再一律归因为「预算被思考耗尽」)。"""
|
|
701
|
+
kind = stats.empty_kind
|
|
702
|
+
if kind is None:
|
|
703
|
+
return
|
|
704
|
+
self._log_empty(
|
|
705
|
+
kind=kind,
|
|
706
|
+
max_tokens=max_tokens,
|
|
707
|
+
finish=stats.finish_reason,
|
|
708
|
+
reasoning_chars=stats.reasoning_chars,
|
|
709
|
+
)
|
|
710
|
+
|
|
711
|
+
def _log_empty(
|
|
712
|
+
self,
|
|
713
|
+
*,
|
|
714
|
+
kind: str,
|
|
715
|
+
max_tokens: int | None,
|
|
716
|
+
finish: str | None,
|
|
717
|
+
reasoning_chars: int,
|
|
718
|
+
) -> None:
|
|
719
|
+
"""输出空正文诊断日志(``ask`` / ``stream`` 共用同一套文案)。"""
|
|
720
|
+
logger.warning(
|
|
721
|
+
f"{self._log_desc()} {_EMPTY_HINTS[kind]}:max_tokens={max_tokens},"
|
|
722
|
+
f"finish_reason={finish},推理 {reasoning_chars} 字符 / 正文 0 字符"
|
|
723
|
+
f"{_EMPTY_ACTIONS[kind]}"
|
|
724
|
+
)
|