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,51 @@
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
+ """``Retry-After`` 响应头解析(SDK 传输与 rerank 传输共用)。"""
21
+
22
+ from datetime import datetime, timezone
23
+ from email.utils import parsedate_to_datetime
24
+ from typing import Final
25
+
26
+ __all__ = ["parse_retry_after"]
27
+
28
+ # 重试前剩余整链预算的最小门槛(秒):不足则放弃重试直接抛出
29
+ MIN_RETRY_BUDGET: Final[float] = 1.0
30
+
31
+
32
+ def parse_retry_after(raw: str | None) -> float | None:
33
+ """解析 ``Retry-After`` 响应头为等待秒数。
34
+
35
+ 支持 RFC 7231 两种格式:整数秒与 HTTP-date(按 UTC 计算剩余秒,
36
+ 过去时刻钳为 0);缺失或非法返回 None。
37
+ """
38
+ if not raw:
39
+ return None
40
+ raw = raw.strip()
41
+ if raw.isdigit():
42
+ return float(raw)
43
+ try:
44
+ dt = parsedate_to_datetime(raw)
45
+ except (TypeError, ValueError):
46
+ return None
47
+ if dt is None:
48
+ return None
49
+ if dt.tzinfo is None:
50
+ dt = dt.replace(tzinfo=timezone.utc)
51
+ return max((dt - datetime.now(timezone.utc)).total_seconds(), 0.0)
@@ -0,0 +1,463 @@
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-04
21
+ """openai SDK 传输层(chat / embedding / image / 探活)。
22
+
23
+ 把 SDK 的响应对象收敛为 kit 的简单结果,业务服务层不直接接触 SDK 类型:
24
+
25
+ - ``chat`` 返回 ``(content, reasoning, finish_reason)``
26
+ - ``chat_stream`` 逐帧产出 ``(content, reasoning, finish_reason)``
27
+ - ``embed`` 返回 ``list[list[float]]``
28
+ - ``image`` 返回 ``str``(URL 或 Base64)
29
+
30
+ 重试语义与自研传输保持一致:仅 5xx 重试、超时不重试、``deadline``
31
+ 剩余预算不足 1 秒时放弃重试。
32
+ """
33
+
34
+ import asyncio
35
+ import json
36
+ import logging
37
+ import random
38
+ import time
39
+ from collections.abc import AsyncIterator
40
+ from typing import Any, Final
41
+
42
+ try:
43
+ import openai
44
+ except ImportError as e:
45
+ raise ImportError(
46
+ "yimo.kit.ai 需要可选依赖,请安装:pip install yimo-kit[ai]"
47
+ ) from e
48
+
49
+ from yimo.kit.ai._internal.retry_after import MIN_RETRY_BUDGET, parse_retry_after
50
+ from yimo.kit.ai._internal.service_base import LoggingServiceBase
51
+ from yimo.kit.ai._internal.types import JSONObject
52
+ from yimo.kit.ai.exceptions import (
53
+ AIError,
54
+ AIRequestError,
55
+ AIResponseError,
56
+ AITimeoutError,
57
+ )
58
+ from yimo.kit.ai.messages import ChatReply, ToolCall
59
+ from yimo.kit.ai.profiles import ModelProfile, resolve_max_tokens
60
+ from yimo.kit.config.log_config import get_default_logger
61
+
62
+ __all__ = ["SdkClient", "SdkServiceBase"]
63
+
64
+ logger = get_default_logger(__name__)
65
+
66
+ # 探活独立超时(秒):只验证密钥有效性,与业务请求超时无关
67
+ _LIST_MODELS_TIMEOUT: Final[float] = 10.0
68
+
69
+ # 推理(思考)内容字段名:GLM / DeepSeek / Qwen 用 reasoning_content,
70
+ # sensenova 用 reasoning
71
+ _REASONING_KEYS: Final[tuple[str, ...]] = ("reasoning_content", "reasoning")
72
+
73
+ # 流式帧的简化结构:(正文增量, 推理增量, 结束原因)
74
+ StreamFrame = tuple[str | None, str | None, str | None]
75
+
76
+
77
+ def _retryable(exc: AIError) -> bool:
78
+ """仅服务端 5xx 可重试(超时不重试:同档案重试注定再超时)。"""
79
+ return (
80
+ isinstance(exc, AIRequestError)
81
+ and exc.status_code is not None
82
+ and exc.status_code >= 500
83
+ )
84
+
85
+
86
+ def _extra_of(obj: Any, key: str) -> Any:
87
+ """读取 SDK 对象上未声明的字段(``extra="allow"`` 落在 ``model_extra``)。"""
88
+ extra = getattr(obj, "model_extra", None)
89
+ if isinstance(extra, dict):
90
+ return extra.get(key)
91
+ return None
92
+
93
+
94
+ def _reasoning_of(holder: Any) -> str:
95
+ """从 message / delta 中取推理文本(两种厂商键名)。"""
96
+ for key in _REASONING_KEYS:
97
+ part = getattr(holder, key, None)
98
+ if not isinstance(part, str) or not part:
99
+ part = _extra_of(holder, key)
100
+ if isinstance(part, str) and part:
101
+ return part
102
+ return ""
103
+
104
+
105
+ def _parse_tool_calls(message: Any) -> list[ToolCall]:
106
+ """把 SDK 的 ``message.tool_calls`` 收敛为 kit 的 ``ToolCall`` 列表。
107
+
108
+ ``arguments`` 在 OpenAI 协议里是 JSON 字符串;部分兼容端点回 dict,
109
+ 统一序列化为字符串(``ToolCall`` 的契约就是字符串)。
110
+ """
111
+ raw = getattr(message, "tool_calls", None)
112
+ if raw is None:
113
+ raw = _extra_of(message, "tool_calls")
114
+ if not raw:
115
+ return []
116
+ if not isinstance(raw, list):
117
+ raise AIResponseError("tool_calls 类型异常")
118
+ calls: list[ToolCall] = []
119
+ for index, item in enumerate(raw):
120
+ function = getattr(item, "function", None)
121
+ name = getattr(function, "name", None)
122
+ arguments = getattr(function, "arguments", None)
123
+ call_id = getattr(item, "id", None)
124
+ if not isinstance(name, str) or not name:
125
+ raise AIResponseError(f"tool_calls[{index}] 缺少 function.name")
126
+ if arguments is None:
127
+ arguments = "{}"
128
+ elif not isinstance(arguments, str):
129
+ arguments = json.dumps(arguments, ensure_ascii=False)
130
+ calls.append(
131
+ ToolCall(
132
+ id=str(call_id or f"call_{index}"),
133
+ type="function",
134
+ function={"name": name, "arguments": arguments},
135
+ )
136
+ )
137
+ return calls
138
+
139
+
140
+ class SdkClient:
141
+ """openai SDK 客户端(全异步,单实例复用)。
142
+
143
+ 构造参数固定 ``max_retries=0``:SDK 默认会重试超时与 429,与 kit
144
+ 「仅 5xx 重试、超时不重试」的语义冲突,故重试由本类自行编排。
145
+ """
146
+
147
+ def __init__(self, profile: ModelProfile) -> None:
148
+ self._profile: ModelProfile = profile
149
+ self._client: openai.AsyncOpenAI = openai.AsyncOpenAI(
150
+ api_key=profile.api_key,
151
+ base_url=profile.base_url,
152
+ timeout=profile.timeout,
153
+ max_retries=0,
154
+ )
155
+
156
+ # ------------------------------------------------------------------
157
+ # 错误映射与重试
158
+ # ------------------------------------------------------------------
159
+
160
+ def _map_error(self, exc: BaseException) -> AIError:
161
+ """把 SDK 异常映射为 kit 异常族(任何 SDK 异常都不允许穿透)。"""
162
+ if isinstance(exc, openai.APITimeoutError):
163
+ return AITimeoutError(f"请求超时: {exc}")
164
+ if isinstance(exc, openai.APIStatusError):
165
+ status_code = exc.status_code
166
+ retry_after = (
167
+ parse_retry_after(exc.response.headers.get("retry-after"))
168
+ if status_code == 429
169
+ else None
170
+ )
171
+ body = ""
172
+ try:
173
+ body = str(exc.response.text)[:200]
174
+ except Exception: # noqa: BLE001 - 错误体读取失败不影响主流程
175
+ body = ""
176
+ return AIRequestError(
177
+ f"HTTP 错误 {status_code}: {body}",
178
+ status_code=status_code,
179
+ retry_after=retry_after,
180
+ )
181
+ if isinstance(exc, openai.APIConnectionError):
182
+ return AIRequestError(f"请求失败: {exc}")
183
+ if isinstance(exc, openai.APIError):
184
+ return AIRequestError(f"请求失败: {exc}")
185
+ return AIRequestError(f"请求失败: {exc}")
186
+
187
+ async def _request(self, factory: Any, *, deadline: float | None) -> Any:
188
+ """执行单次调用,按档案 ``retries`` 对 5xx 做指数退避重试。"""
189
+ max_attempts = self._profile.retries + 1
190
+ for attempt in range(max_attempts):
191
+ try:
192
+ return await factory()
193
+ except openai.OpenAIError as exc:
194
+ mapped = self._map_error(exc)
195
+ if attempt >= max_attempts - 1 or not _retryable(mapped):
196
+ raise mapped from exc
197
+ if (
198
+ deadline is not None
199
+ and time.monotonic() + MIN_RETRY_BUDGET >= deadline
200
+ ):
201
+ raise AIRequestError(
202
+ f"剩余整链预算不足,放弃重试: {mapped}",
203
+ status_code=mapped.status_code
204
+ if isinstance(mapped, AIRequestError)
205
+ else None,
206
+ retry_after=mapped.retry_after
207
+ if isinstance(mapped, AIRequestError)
208
+ else None,
209
+ ) from exc
210
+ await asyncio.sleep(min(2**attempt, 8) + random.uniform(0, 0.5))
211
+ # 不可达,供类型系统收口
212
+ raise AIRequestError("重试后仍未成功")
213
+
214
+ # ------------------------------------------------------------------
215
+ # 四类能力
216
+ # ------------------------------------------------------------------
217
+
218
+ def _chat_params(
219
+ self,
220
+ messages: list[dict[str, Any]],
221
+ extra_body: JSONObject | None,
222
+ response_format: JSONObject | None,
223
+ temperature: float | None,
224
+ max_tokens: int | None,
225
+ tools: list[dict[str, Any]] | None = None,
226
+ tool_choice: str | dict[str, Any] | None = None,
227
+ ) -> dict[str, Any]:
228
+ params: dict[str, Any] = {
229
+ "model": self._profile.model,
230
+ "messages": messages,
231
+ }
232
+ if temperature is not None:
233
+ params["temperature"] = temperature
234
+ effective_max_tokens = resolve_max_tokens(self._profile, max_tokens)
235
+ if effective_max_tokens is not None:
236
+ params["max_tokens"] = effective_max_tokens
237
+ if response_format is not None:
238
+ params["response_format"] = response_format
239
+ if tools:
240
+ params["tools"] = tools
241
+ if tool_choice is not None:
242
+ params["tool_choice"] = tool_choice
243
+ if extra_body:
244
+ params["extra_body"] = extra_body
245
+ return params
246
+
247
+ async def chat_raw(
248
+ self,
249
+ *,
250
+ messages: list[dict[str, Any]],
251
+ tools: list[dict[str, Any]] | None = None,
252
+ tool_choice: str | dict[str, Any] | None = None,
253
+ extra_body: JSONObject | None = None,
254
+ response_format: JSONObject | None = None,
255
+ temperature: float | None = None,
256
+ max_tokens: int | None = None,
257
+ deadline: float | None = None,
258
+ ) -> ChatReply:
259
+ """非流式对话,返回完整回复(含 ``tool_calls``)。
260
+
261
+ ``tools`` 必须是已包装好的 OpenAI 结构(``type=function`` +
262
+ ``function.{name,description,parameters}``),字段改名由服务层完成。
263
+ """
264
+ params = self._chat_params(
265
+ messages,
266
+ extra_body,
267
+ response_format,
268
+ temperature,
269
+ max_tokens,
270
+ tools=tools,
271
+ tool_choice=tool_choice,
272
+ )
273
+ resp = await self._request(
274
+ lambda: self._client.chat.completions.create(
275
+ **params, timeout=self._profile.timeout
276
+ ),
277
+ deadline=deadline,
278
+ )
279
+ choices = getattr(resp, "choices", None)
280
+ if not choices:
281
+ raise AIResponseError("响应缺少 choices")
282
+ choice = choices[0]
283
+ message = getattr(choice, "message", None)
284
+ if message is None:
285
+ raise AIResponseError("响应缺少 message")
286
+ content = getattr(message, "content", None)
287
+ if content is not None and not isinstance(content, str):
288
+ raise AIResponseError(f"content 类型异常: {type(content).__name__}")
289
+ finish = getattr(choice, "finish_reason", None)
290
+ return ChatReply(
291
+ content=content,
292
+ reasoning=_reasoning_of(message),
293
+ finish_reason=finish if isinstance(finish, str) else None,
294
+ tool_calls=_parse_tool_calls(message),
295
+ )
296
+
297
+ async def chat(
298
+ self,
299
+ *,
300
+ messages: list[dict[str, Any]],
301
+ extra_body: JSONObject | None = None,
302
+ response_format: JSONObject | None = None,
303
+ temperature: float | None = None,
304
+ max_tokens: int | None = None,
305
+ deadline: float | None = None,
306
+ ) -> tuple[str | None, str, str | None]:
307
+ """非流式对话,返回 ``(正文, 推理文本, finish_reason)``。"""
308
+ reply = await self.chat_raw(
309
+ messages=messages,
310
+ extra_body=extra_body,
311
+ response_format=response_format,
312
+ temperature=temperature,
313
+ max_tokens=max_tokens,
314
+ deadline=deadline,
315
+ )
316
+ return reply.content, reply.reasoning, reply.finish_reason
317
+
318
+ async def chat_stream(
319
+ self,
320
+ *,
321
+ messages: list[dict[str, str]],
322
+ extra_body: JSONObject | None = None,
323
+ response_format: JSONObject | None = None,
324
+ temperature: float | None = None,
325
+ max_tokens: int | None = None,
326
+ ) -> AsyncIterator[StreamFrame]:
327
+ """流式对话,逐帧产出 ``(正文增量, 推理增量, finish_reason)``。
328
+
329
+ 流式不重试(半开流重放语义复杂)。异常在首次迭代时抛出,
330
+ 与自研传输一致,便于候选链在首帧前切换。
331
+ """
332
+ params = self._chat_params(
333
+ messages, extra_body, response_format, temperature, max_tokens
334
+ )
335
+ params["stream"] = True
336
+ try:
337
+ stream = await self._client.chat.completions.create(
338
+ **params, timeout=None
339
+ )
340
+ except openai.OpenAIError as exc:
341
+ raise self._map_error(exc) from exc
342
+ try:
343
+ # 用 async with 托管流:业务侧提前 break/取消时也能关闭连接,
344
+ # 否则只能等 GC,长跑进程会堆积半开连接
345
+ async with stream:
346
+ async for chunk in stream:
347
+ choices = getattr(chunk, "choices", None)
348
+ if not choices:
349
+ continue
350
+ choice = choices[0]
351
+ delta = getattr(choice, "delta", None)
352
+ content = (
353
+ getattr(delta, "content", None) if delta is not None else None
354
+ )
355
+ reasoning = _reasoning_of(delta) if delta is not None else ""
356
+ finish = getattr(choice, "finish_reason", None)
357
+ if content or reasoning or finish:
358
+ yield (
359
+ content if isinstance(content, str) else None,
360
+ reasoning or None,
361
+ finish if isinstance(finish, str) and finish else None,
362
+ )
363
+ except openai.OpenAIError as exc:
364
+ raise self._map_error(exc) from exc
365
+
366
+ async def embed(
367
+ self, texts: list[str], *, deadline: float | None = None
368
+ ) -> list[list[float]]:
369
+ """批量向量化,返回与输入等长的向量列表。"""
370
+ resp = await self._request(
371
+ lambda: self._client.embeddings.create(
372
+ model=self._profile.model,
373
+ input=texts,
374
+ encoding_format="float",
375
+ timeout=self._profile.timeout,
376
+ ),
377
+ deadline=deadline,
378
+ )
379
+ items = getattr(resp, "data", None)
380
+ if not isinstance(items, list):
381
+ raise AIResponseError("向量化响应缺少 data")
382
+ vectors: list[list[float]] = []
383
+ for item in items:
384
+ embedding = getattr(item, "embedding", None)
385
+ if not isinstance(embedding, list):
386
+ raise AIResponseError("向量化响应 embedding 非法")
387
+ vectors.append([float(v) for v in embedding])
388
+ return vectors
389
+
390
+ async def image(
391
+ self,
392
+ prompt: str,
393
+ *,
394
+ size: str | None = None,
395
+ n: int = 1,
396
+ extra_body: JSONObject | None = None,
397
+ deadline: float | None = None,
398
+ ) -> tuple[str | None, str | None]:
399
+ """文生图,返回 ``(url, b64)``:两者可能同时有值,至少一个非空。"""
400
+ params: dict[str, Any] = {
401
+ "model": self._profile.model,
402
+ "prompt": prompt,
403
+ "n": n,
404
+ }
405
+ if size is not None:
406
+ params["size"] = size
407
+ if extra_body:
408
+ params["extra_body"] = extra_body
409
+ resp = await self._request(
410
+ lambda: self._client.images.generate(
411
+ **params, timeout=self._profile.timeout
412
+ ),
413
+ deadline=deadline,
414
+ )
415
+ items = getattr(resp, "data", None)
416
+ if not items:
417
+ raise AIResponseError("图像生成响应缺少 data")
418
+ first = items[0]
419
+ raw_url = getattr(first, "url", None)
420
+ raw_b64 = getattr(first, "b64_json", None)
421
+ url = raw_url if isinstance(raw_url, str) and raw_url else None
422
+ b64 = raw_b64 if isinstance(raw_b64, str) and raw_b64 else None
423
+ if url is None and b64 is None:
424
+ raise AIResponseError("图像生成响应缺少 url/b64_json")
425
+ return url, b64
426
+
427
+ async def list_models(self) -> JSONObject:
428
+ """轻探测 ``GET {base_url}/models``:仅验证密钥有效性。
429
+
430
+ 独立 10 秒超时;返回值只表达成功(失败抛异常),统一返回空对象。
431
+ """
432
+ # 探活不重试:失败即返回,避免「10s 超时 × (retries+1)」把配置页拖住
433
+ try:
434
+ await self._client.models.list(timeout=_LIST_MODELS_TIMEOUT)
435
+ except openai.OpenAIError as exc:
436
+ raise self._map_error(exc) from exc
437
+ return {}
438
+
439
+ async def close(self) -> None:
440
+ await self._client.close()
441
+
442
+
443
+ class SdkServiceBase(LoggingServiceBase):
444
+ """SDK 服务基类:统一日志骨架 + ``SdkClient`` 生命周期。"""
445
+
446
+ def __init__(self, profile: ModelProfile) -> None:
447
+ super().__init__(profile)
448
+ self._client: SdkClient = SdkClient(profile)
449
+
450
+ def _debug_payload(self, payload: object) -> None:
451
+ """DEBUG 级别打印请求参数(非 DEBUG 不序列化)。"""
452
+ if not logger.isEnabledFor(logging.DEBUG):
453
+ return
454
+ try:
455
+ dumped = json.dumps(payload, ensure_ascii=False, default=str)
456
+ except (TypeError, ValueError):
457
+ dumped = str(payload)
458
+ if len(dumped) > 2000:
459
+ dumped = f"{dumped[:2000]}…(截断)"
460
+ logger.debug(f"请求参数: {dumped}")
461
+
462
+ async def close(self) -> None:
463
+ await self._client.close()
@@ -0,0 +1,115 @@
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-04
21
+ """AI 服务公共基类:档案属性、生命周期与统一日志骨架。
22
+
23
+ 0.6.10 起不再包含 HTTP 传输与请求体编排:chat / embedding / image 由
24
+ ``SdkClient`` 承担,rerank 由 ``RerankTransport`` 承担。本模块只保留
25
+ 四类服务共用的日志与资源管理能力。
26
+ """
27
+
28
+ import time
29
+ from abc import ABC
30
+ from collections.abc import Iterator
31
+ from contextlib import contextmanager
32
+ from typing import ClassVar
33
+
34
+ from yimo.kit.ai._internal.types import JSONValue
35
+ from yimo.kit.ai.exceptions import AIError, AIResponseError
36
+ from yimo.kit.ai.profiles import ModelProfile
37
+ from yimo.kit.config.log_config import get_default_logger
38
+
39
+ __all__ = ["LoggingServiceBase", "safe_get"]
40
+
41
+ logger = get_default_logger(__name__)
42
+
43
+
44
+ def safe_get(data: JSONValue, *path: str | int) -> JSONValue:
45
+ """按层级路径安全取值,支持 dict 键(str)与 list 索引(int)。
46
+
47
+ Raises:
48
+ AIResponseError: 路径任一环节缺失或类型不符。
49
+ """
50
+ cur: JSONValue = data
51
+ for key in path:
52
+ if isinstance(key, int):
53
+ if not isinstance(cur, list) or key < 0 or key >= len(cur):
54
+ raise AIResponseError(f"响应缺少索引 {path}: {str(data)[:200]}")
55
+ cur = cur[key]
56
+ else:
57
+ if not isinstance(cur, dict) or key not in cur:
58
+ raise AIResponseError(
59
+ f"响应缺少字段 {'.'.join(map(str, path))}: {str(data)[:200]}"
60
+ )
61
+ cur = cur[key]
62
+ return cur
63
+
64
+
65
+ class LoggingServiceBase(ABC):
66
+ """四类模型服务共用的档案属性、日志骨架与异步上下文。"""
67
+
68
+ _LABEL: ClassVar[str] = "模型"
69
+
70
+ def __init__(self, profile: ModelProfile) -> None:
71
+ self._profile: ModelProfile = profile
72
+
73
+ @property
74
+ def profile(self) -> ModelProfile:
75
+ return self._profile
76
+
77
+ def _log_desc(self, *, suffix: str = "") -> str:
78
+ """日志中的「模型及描述」:服务中文名 + 模型标识 + 实例名。"""
79
+ return (
80
+ f"{self._LABEL} {self._profile.model}"
81
+ f"(实例 {self._profile.name}{suffix})"
82
+ )
83
+
84
+ @contextmanager
85
+ def _log_call(self, *, log: bool = True) -> Iterator[None]:
86
+ """统一日志骨架:Start → 成功耗时 / 失败 ERROR。"""
87
+ desc = self._log_desc()
88
+ if log:
89
+ logger.info(f"********** {desc} ********** Start")
90
+ start = time.perf_counter()
91
+ try:
92
+ yield
93
+ except AIError as exc:
94
+ logger.error(
95
+ f"********** {desc} ********** "
96
+ f"耗时 {time.perf_counter() - start:.1f}秒(失败:{exc})"
97
+ )
98
+ raise
99
+ if log:
100
+ logger.info(
101
+ f"********** {desc} ********** 耗时 {time.perf_counter() - start:.1f}秒"
102
+ )
103
+
104
+ async def close(self) -> None:
105
+ """释放底层资源(子类实现)。"""
106
+ raise NotImplementedError
107
+
108
+ async def __aenter__(self) -> "LoggingServiceBase":
109
+ return self
110
+
111
+ async def __aexit__(self, *exc_info: object) -> None:
112
+ await self.close()
113
+
114
+ def __str__(self) -> str:
115
+ return f"{type(self).__name__}({self._profile.name})"
@@ -0,0 +1,28 @@
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
+ """yimo/kit/ai 内部 JSON 类型别名(PEP 695 type 语句,递归 JSON 类型)"""
21
+
22
+ # 递归 JSON 值类型:标量 | 数组 | 对象
23
+ type JSONScalar = str | int | float | bool | None
24
+ type JSONValue = JSONScalar | list[JSONValue] | dict[str, JSONValue]
25
+ # JSON 对象(请求体 / 响应体)
26
+ type JSONObject = dict[str, JSONValue]
27
+
28
+ __all__ = ["JSONObject", "JSONScalar", "JSONValue"]