对接文档补充内容理解接口相关的说明

补充之前两个git commit的注释： `be3f0d4` **Indexer：补齐内容富化链路与批处理能力，完善契约/回归测试** - **新增富化流程**：在 `document_transformer` / `spu_transformer` 中加入面向 SPU 的内容富化（enrich-content）处理与字段组装逻辑。 - **增强增量索引**：`incremental_service` 增加富化相关的处理分支与必要的边界/兼容逻辑。 - **批处理与稳定性**：`process_products` 调整处理节奏/批次边界，降低大批量处理时的失败率与抖动。 - **测试补齐**：新增 CI 级接口契约测试与批处理/富化相关单测，覆盖服务行为与关键路径回归。 --- `9f5994b` **Reranker 微服务：上线与调优文档 + 批处理后端改造 + 性能基准脚本** - **文档体系完善**：补充 `reranker/DEPLOYMENT_AND_TUNING.md`、更新 `reranker/README.md`，沉淀部署、参数选择、性能调优方法。 - **后端能力增强**：新增/完善批处理工具 `batching_utils`，并对 `qwen3_vllm` 后端进行批量推理/吞吐相关优化与适配。 - **压测与报告**：新增 `scripts/benchmark_reranker_1000docs.sh` 与对应 `perf_reports/.../report.md`，可复现实测吞吐与延迟数据。 - **对外/集成入口**：补充 `api/routes/indexer.py` 相关路由能力，为索引/服务侧集成 reranker 提供接口支撑。 - **回归测试**：新增批处理工具相关单测，确保 batching 行为稳定、可回归。

对接文档补充内容理解接口相关的说明
补充之前两个git commit的注释： `be3f0d4` **Indexer：补齐内容富化链路与批处理能力，完善契约/回归测试** - **新增富化流程**：在 `document_transformer` / `spu_transformer` 中加入面向 SPU 的内容富化（enrich-content）处理与字段组装逻辑。 - **增强增量索引**：`incremental_service` 增加富化相关的处理分支与必要的边界/兼容逻辑。 - **批处理与稳定性**：`process_products` 调整处理节奏/批次边界，降低大批量处理时的失败率与抖动。 - **测试补齐**：新增 CI 级接口契约测试与批处理/富化相关单测，覆盖服务行为与关键路径回归。 --- `9f5994b` **Reranker 微服务：上线与调优文档 + 批处理后端改造 + 性能基准脚本** - **文档体系完善**：补充 `reranker/DEPLOYMENT_AND_TUNING.md`、更新 `reranker/README.md`，沉淀部署、参数选择、性能调优方法。 - **后端能力增强**：新增/完善批处理工具 `batching_utils`，并对 `qwen3_vllm` 后端进行批量推理/吞吐相关优化与适配。 - **压测与报告**：新增 `scripts/benchmark_reranker_1000docs.sh` 与对应 `perf_reports/.../report.md`，可复现实测吞吐与延迟数据。 - **对外/集成入口**：补充 `api/routes/indexer.py` 相关路由能力，为索引/服务侧集成 reranker 提供接口支撑。 - **回归测试**：新增批处理工具相关单测，确保 batching 行为稳定、可回归。
tangwang
1 parent be3f0d46
Showing 1 changed file with 35 additions and 5 deletions Show diff stats
docs/搜索API对接指南.md
@@ -1484,7 +1484,7 @@ curl -X POST &quot;http://127.0.0.1:6004/indexer/build-docs-from-db&quot; \
 ### 5.8 内容理解字段生成接口
 - **端点**: `POST /indexer/enrich-content`
-- **描述**: 根据商品标题批量生成 **qanchors**（锚文本）、**semantic_attributes**（语义属性）、**tags**（细分标签），供外部 indexer 在「微服务组合」方式下自行拼装 doc 时使用。内部逻辑与 `indexer.process_products` 一致，支持多语言与 Redis 缓存；单次请求在线程池中执行，避免阻塞其他接口。
+- **描述**: 根据商品内容信息批量生成 **qanchors**（锚文本）、**semantic_attributes**（语义属性）、**tags**（细分标签），供外部 indexer 在「微服务组合」方式下自行拼装 doc 时使用。请求以 `items[]` 传入商品内容字段（必填/可选见下表）。内部逻辑与 `indexer.process_products` 一致，支持多语言与 Redis 缓存；单次请求在线程池中执行，避免阻塞其他接口。
 #### 请求参数
@@ -1492,8 +1492,18 @@ curl -X POST &quot;http://127.0.0.1:6004/indexer/build-docs-from-db&quot; \
 {
   "tenant_id": "170",
   "items": [
-    { "spu_id": "223167", "title": "纯棉短袖T恤 夏季男装" },
-    { "spu_id": "223168", "title": "12PCS Dolls with Bottles" }
+    {
+      "spu_id": "223167",
+      "title": "纯棉短袖T恤 夏季男装",
+      "brief": "夏季透气纯棉短袖，舒适亲肤",
+      "description": "100%棉，圆领版型，适合日常通勤与休闲穿搭。",
+      "image_url": "https://example.com/images/223167.jpg"
+    },
+    {
+      "spu_id": "223168",
+      "title": "12PCS Dolls with Bottles",
+      "image_url": "https://example.com/images/223168.jpg"
+    }
   ],
   "languages": ["zh", "en"]
 }
@@ -1502,9 +1512,23 @@ curl -X POST &quot;http://127.0.0.1:6004/indexer/build-docs-from-db&quot; \
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | `tenant_id` | string | Y | - | 租户 ID，用于缓存隔离 |
-| `items` | array | Y | - | 待分析列表，每项含 `spu_id`、`title`；**单次最多 50 条** |
+| `items` | array | Y | - | 待分析列表；**单次最多 50 条** |
 | `languages` | array[string] | N | `["zh", "en"]` | 目标语言，需在支持范围内：`zh`、`en`、`de`、`ru`、`fr` |
+`items[]` 字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `spu_id` | string | Y | SPU ID，用于回填结果与缓存键 |
+| `title` | string | Y | 商品标题 |
+| `image_url` | string | N | 商品主图 URL（预留：后续可用于图像/多模态内容理解） |
+| `brief` | string | N | 商品简介/短描述（预留） |
+| `description` | string | N | 商品详情/长描述（预留） |
+
+批量请求建议：
+- **全量**：务必按 **20 个 SPU/doc** 攒成一个批次后再请求一次。
+- **增量**：可按时效要求设置时间窗口（例如 **5 分钟**），在窗口内尽可能攒到 **20 个**；达到 20 或窗口到期就发送一次请求。
+
 #### 响应格式
 ```json
@@ -1555,7 +1579,13 @@ curl -X POST &quot;http://localhost:6004/indexer/enrich-content&quot; \
   -d '{
     "tenant_id": "170",
     "items": [
-      { "spu_id": "223167", "title": "纯棉短袖T恤 夏季男装" }
+      {
+        "spu_id": "223167",
+        "title": "纯棉短袖T恤 夏季男装",
+        "brief": "夏季透气纯棉短袖，舒适亲肤",
+        "description": "100%棉，圆领版型，适合日常通勤与休闲穿搭。",
+        "image_url": "https://example.com/images/223167.jpg"
+      }
     ],
     "languages": ["zh", "en"]
   }'