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

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

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

{sdpy_kit-0.6.7 → sdpy_kit-0.6.8}/README.md

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

{sdpy_kit-0.6.7 → sdpy_kit-0.6.8}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.6.7"
+__version__ = "0.6.8"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.6.7 → sdpy_kit-0.6.8}/kit/ai/base_service.py

@@ -140,6 +140,15 @@ class BaseAIService[RequestT, ResponseT](ABC):
     def _parse_response(self, data: JSONObject) -> ResponseT:
         """将 JSON 响应体解析为业务结果。"""
 
+    def _collect_meta(self, data: JSONObject, request: RequestT) -> None:
+        """收尾元信息钩子（默认无操作）。
+
+        在 :meth:`_parse_response` **之前**调用：解析可能抛错（如输出被截断到
+        没有正文），元信息（``finish_reason`` 等）需先落地；子类可写入
+        ``request.stats``。
+        """
+        return None
+
     async def _call(
         self, request: RequestT, *, deadline: float | None = None
     ) -> ResponseT:
@@ -162,6 +171,7 @@ class BaseAIService[RequestT, ResponseT](ABC):
         start = time.perf_counter()
         try:
             data = await self._client.post_json(payload, deadline=deadline)
+            self._collect_meta(data, request)
             result = self._parse_response(data)
         except AIError as exc:
             logger.error(