From 413452717fc1bea25b97c9748040edad6f94589d Mon Sep 17 00:00:00 2001 From: tangwang Date: Thu, 2 Apr 2026 19:46:27 +0800 Subject: [PATCH] 文档更新 --- CLAUDE.md | 2 +- README.md | 34 ++++++++++++++++++++++++++-------- docs/DEVELOPER_GUIDE.md | 25 +++++++++++++------------ docs/QUICKSTART.md | 6 +++--- docs/Usage-Guide.md | 18 ++++++++++-------- docs/issue.md | 4 ++-- docs/issue.txt | 7 ++----- docs/工作总结-微服务性能优化与架构.md | 4 ++-- indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md | 2 +- scripts/benchmark_translation_longtext_single.py | 2 +- scripts/perf_api_benchmark.py | 2 +- translation/README.md | 2 +- 12 files changed, 63 insertions(+), 45 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e00769a..1e67aad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -413,7 +413,7 @@ bm25() + 0.2*text_embedding_relevance() - **Application Layer**: Performance-optimized filtering outside ES - **Use Case**: Display one SKU per variant combination (e.g., one per color) -### API Architecture & Usage (from 搜索API对接指南.md) +### API Architecture & Usage（见 `docs/搜索API对接指南-00-总览与快速开始.md` 及分册 `-01`…`-10`） **Core API Endpoints**: ``` diff --git a/README.md b/README.md index a41ce5c..f579ae7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ README 用于给后续开发者建立统一认知：**系统框架、模块边 ## 1) 项目目标与边界 -- **目标**：在统一架构下支持关键词检索、语义检索、分面过滤、多语言、重排、图片检索。 +- **目标**：在统一架构下支持关键词检索、语义检索、分面过滤、多语言、分层排序（粗排 / 可选精排 fine rank / 重排）、图片检索。 - **边界**：本仓库负责搜索核心能力与服务编排；业务方通过标准 HTTP API 对接。 - **核心约束**： - 调用方稳定（API/Provider 契约优先） @@ -47,9 +47,10 @@ source activate.sh - `6004` indexer（`/indexer/*`） - `6003` frontend - `6010` eval-web（搜索评估 UI，`./scripts/service_ctl.sh` 服务名 `eval-web`） -- `6005` embedding（可选） +- `6005` embedding-text（可选，`POST /embed/text`；常见后端为 TEI，默认 `8080`） +- `6008` embedding-image（可选，`POST /embed/image` 等） - `6006` translator（可选） -- `6007` reranker（可选） +- `6007` reranker（可选，`POST /rerank`；精排可与主重排分 `service_profile`，见 `config.yaml` → `fine_rank` / `services.rerank`） 更完整示例见 `docs/QUICKSTART.md`。 @@ -58,7 +59,7 @@ source activate.sh ## 3) 总体架构（开发者视角） - `api/`：统一 API 入口（search/admin/indexer app） -- `search/`：召回、排序、结果组织 +- `search/`：召回、分层排序与结果组织（ES 召回 → `coarse_rank` 融合文本/KNN → 可选 `fine_rank` 轻量精排 → `rerank` 融合模型分与 ES 信号；`debug=true` 时返回各阶段 rank / fusion 调试字段） - `query/`：查询解析、多语言处理、改写 - `indexer/`：MySQL 行数据 -> ES 文档的转换与索引流程 - `providers/`：能力调用抽象（embedding/rerank） @@ -92,12 +93,28 @@ source activate.sh | 0. 全局规范（首读） | `docs/DEVELOPER_GUIDE.md` | | 1. 开发与配置 | `docs/QUICKSTART.md` | | 2. 运行与排障 | `docs/Usage-Guide.md` | -| 3. API 详细说明 | `docs/搜索API对接指南.md` | -| 4. 快速参数速查 | `docs/搜索API速查表.md` | +| 3. 搜索 API（已拆分为多篇，从总览进入） | `docs/搜索API对接指南-00-总览与快速开始.md` | +| 4. 快速参数速查 | `docs/搜索API对接指南-速查表.md` | | 5. 翻译专项 | `docs/翻译模块说明.md` | | 6. 首次环境搭建、生产凭证 | `docs/QUICKSTART.md` §1.4–1.8 | | 7. TEI 文本向量专项 | `docs/TEI_SERVICE说明文档.md` | | 8. CN-CLIP 图片向量专项 | `docs/CNCLIP_SERVICE说明文档.md` | +| 9. 相关性检索与融合（含 fine rank / rerank） | `docs/相关性检索优化说明.md` | +| 10. 调参与评估工作流 | `docs/检索调参与LTR工作流.md` | +| 11. 微服务性能与架构摘要 | `docs/工作总结-微服务性能优化与架构.md` | + +**搜索 API 拆分目录**（与总览中列表一致，按需查阅）： + +| 分册 | 内容 | +|------|------| +| `搜索API对接指南-01-搜索接口.md` | `POST /search/` 请求与响应 | +| `搜索API对接指南-02-搜索建议与即时搜索.md` | 建议 / 即时搜索 | +| `搜索API对接指南-03-获取文档.md` | `GET /search/{doc_id}` | +| `搜索API对接指南-05-索引接口（Indexer）.md` | 索引与 `build-docs` / `enrich-content` 等 | +| `搜索API对接指南-06-管理接口（Admin）.md` | `/admin/*` | +| `搜索API对接指南-07-微服务接口（Embedding-Reranker-Translation）.md` | 6005/6006/6007/6008 等直连说明 | +| `搜索API对接指南-08-数据模型与字段速查.md` | 字段与数据模型 | +| `搜索API对接指南-10-接口级压测脚本.md` | 压测脚本与用法 | --- @@ -122,12 +139,13 @@ python -m pytest tests/ci -q --- -## 7) 代码质量与持续继承要求 +## 7) 代码质量与持续集成要求 - 新增功能必须补最小测试（至少覆盖 1 条成功路径 + 1 条参数异常路径） - 修改公共协议时必须同步更新： - `docs/QUICKSTART.md` - - 对应服务 README / API 文档 + - 对应分册：`docs/搜索API对接指南-*.md`（及速查表） + - 对应服务 README / 专项文档 - `tests/ci` 契约用例 - 禁止新增“临时分支逻辑”绕过 provider/backend 工厂 - 优先减少重复实现，复用现有转换链路与配置解析入口 diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md index 0992ca8..2c70b2e 100644 --- a/docs/DEVELOPER_GUIDE.md +++ b/docs/DEVELOPER_GUIDE.md @@ -44,8 +44,9 @@ - [QUICKSTART.md](./QUICKSTART.md) — 环境、服务、模块、请求示例；§2–§4 含基础配置与 Provider/模块扩展 - [翻译模块说明.md](./翻译模块说明.md) — translator service、capability 配置、本地模型部署与接口契约 -- [系统设计文档.md](./系统设计文档.md) — 索引结构、数据流、通用化设计 -- [搜索API对接指南.md](./搜索API对接指南.md) — 搜索/索引/管理接口完整说明 +- 索引与数据流：[索引方案.md](./索引方案.md)、[索引字段说明v2.md](./索引字段说明v2.md)、[MySQL到ES文档映射说明.md](./MySQL到ES文档映射说明.md) +- [搜索API对接指南-00-总览与快速开始.md](./搜索API对接指南-00-总览与快速开始.md) — 搜索/索引/管理/微服务 API（分册入口；分册列表见 README） +- [搜索API对接指南-速查表.md](./搜索API对接指南-速查表.md) — 搜索 API 参数速查 - [QUICKSTART.md](./QUICKSTART.md) §1.4–1.8 — 系统要求、Python 环境、外部服务与生产凭证、店匠数据源 - [Usage-Guide.md](./Usage-Guide.md) — 运维、日志、多环境、故障排查 @@ -57,7 +58,7 @@ - **产品形态**：面向跨境独立站（如店匠 Shoplazza）的**多租户可配置搜索 SaaS**，提供搜索后端与索引富化能力。 - **核心交付**： - - **搜索服务**：文本搜索、图片搜索、建议（suggestions）、过滤、分面、排序、可选重排。 + - **搜索服务**：文本搜索、图片搜索、建议（suggestions）、过滤、分面、排序、分层粗排/可选精排（fine rank）/重排。 - **索引服务**：将 MySQL 中的店匠标准表（SPU/SKU）富化为符合 ES mapping 的文档（多语言、翻译、向量、规格聚合等），支持全量/增量及“仅构建 doc、由上游写 ES”的对接方式。 - **支撑服务**：向量服务（embedding）、翻译服务（translator）、重排服务（reranker），可独立部署、通过配置切换。 @@ -78,12 +79,12 @@ MySQL (店匠 SPU/SKU) → Indexer（富化：多语言、翻译、向量、规格聚合） → Elasticsearch（按租户索引：search_products_tenant_） - → 搜索 API（QueryParser → Searcher，可选翻译/向量/重排） + → 搜索 API（QueryParser → Searcher：粗排 coarse_rank → 可选精排 fine_rank → 重排 rerank） → 前端 / 上游业务 ``` - **索引侧**：Java 或脚本决定“对哪些 SPU 做索引”；Python indexer 负责“单条/批量 SPU → ES 文档”的完整逻辑，或通过 `/indexer/build-docs` 仅返回 doc、由调用方写 ES。 -- **搜索侧**：请求经 QueryParser（解析、改写、翻译、向量化）→ Searcher（ES 查询、可选重排）→ 结果格式化 → 返回。 +- **搜索侧**：请求经 QueryParser（解析、改写、翻译、向量化）→ Searcher（ES 召回与查询构建、`coarse_rank` 融合文本/KNN、可选 `fine_rank`、`rerank` 与分数融合）→ 结果格式化 → 返回。 ### 3.2 服务拓扑与端口 @@ -109,7 +110,7 @@ api/ # FastAPI 应用：搜索路由、管理路由、索引路 config/ # 配置加载与解析：config.yaml、services、env indexer/ # MySQL → ES 管道：mapping、transformer、bulk、增量、build-docs query/ # 查询解析：规范化、改写、翻译、embedding 调用、语言计划生成 -search/ # 搜索执行：多语言查询构建、Searcher、重排客户端、分数融合 +search/ # 搜索执行：多语言查询构建、Searcher、粗排/精排/重排与分数融合 embeddings/ # 向量化：服务端（server）、文本/图像后端、协议与配置 reranker/ # 重排：服务端（server）、后端（backends）、配置 providers/ # 能力提供者：向量/重排的客户端抽象与工厂 @@ -144,7 +145,7 @@ docs/ # 文档（含本指南） - **职责**：将 MySQL 行或上游传入的 SPU/SKU/options 转为符合 `mappings/search_products.json` 的 ES 文档；含多语言组织、翻译调用、向量生成、规格/SKU 聚合、类目路径等；支持全量/增量写入 ES，以及仅返回 doc（build-docs）供上游写 ES。 - **对接**：调用方通过 `providers` 获取翻译、向量等能力；索引名通过 `indexer/mapping_generator.get_tenant_index_name(tenant_id)` 与 `ES_INDEX_NAMESPACE` 一致。 -- **详见**：`indexer/README.md`、[系统设计文档.md](./系统设计文档.md)。 +- **详见**：`indexer/README.md`、[索引方案.md](./索引方案.md)、[索引字段说明v2.md](./索引字段说明v2.md)、[MySQL到ES文档映射说明.md](./MySQL到ES文档映射说明.md)。 ### 4.4 query @@ -153,8 +154,8 @@ docs/ # 文档（含本指南） ### 4.5 search -- **职责**：构建多语言 ES 查询、执行检索、可选重排、分数融合、结果格式化；分面、过滤、排序、SKU 维度筛选等。 -- **原则**：重排通过 `search/rerank_client.py` 调用 `create_rerank_provider()`，不关心重排服务内是 BGE 还是 Qwen3；与 ES 的交互封装在 Searcher 内，便于 mock 与测试。 +- **职责**：构建多语言 ES 查询、执行检索、分层排序（`coarse_rank` → 可选 `fine_rank` → `rerank`）与分数融合、结果格式化；分面、过滤、排序、SKU 维度筛选等。 +- **原则**：精排/重排通过 `search/rerank_client.py` 与配置中的 `service_profile` 区分调用；与 ES 的交互封装在 Searcher 内，便于 mock 与测试。参数见 `config/config.yaml` 的 `coarse_rank` / `fine_rank` / `rerank`。 ### 4.6 embeddings @@ -446,10 +447,10 @@ services: | 新人上手、环境与请求示例 | [QUICKSTART.md](./QUICKSTART.md) | | 框架全貌与规范（本文） | 本指南 | | Provider 与基础配置、模块扩展（协议与后端） | [QUICKSTART.md](./QUICKSTART.md) §2–§4、本指南 §7 | -| 索引结构、数据流、通用化设计 | [系统设计文档.md](./系统设计文档.md) | -| 搜索/索引 API 完整说明 | [搜索API对接指南.md](./搜索API对接指南.md) | +| 索引结构、字段、MySQL→ES 映射 | [索引方案.md](./索引方案.md)、[索引字段说明v2.md](./索引字段说明v2.md)、[MySQL到ES文档映射说明.md](./MySQL到ES文档映射说明.md) | +| 搜索/索引 API（分册入口） | [搜索API对接指南-00-总览与快速开始.md](./搜索API对接指南-00-总览与快速开始.md) | | 翻译模块与本地模型 | [翻译模块说明.md](./翻译模块说明.md) | -| 搜索 API 参数速查 | [搜索API速查表.md](./搜索API速查表.md) | +| 搜索 API 参数速查 | [搜索API对接指南-速查表.md](./搜索API对接指南-速查表.md) | | 首次部署、新机器环境、生产凭证 | [QUICKSTART.md](./QUICKSTART.md) §1.4–1.8 | | 运维、日志、多环境、故障 | [Usage-Guide.md](./Usage-Guide.md) | | 索引模块职责与 Java 对接 | [indexer/README.md](../indexer/README.md) | diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 886ed23..9000ff7 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -314,7 +314,7 @@ saas-search 以 MySQL 中的店匠标准表为权威数据源： - `shoplazza_product_spu`：SPU 商品主表 - `shoplazza_product_sku`：SKU 变体表 -**shoplazza_product_sku 字段节选**：`id`, `spu_id`, `shop_id`, `title`, `sku`, `price`, `compare_at_price`, `option1/2/3`, `inventory_quantity`, `image_src`, `tenant_id`, `create_time`, `update_time`, `deleted` 等。完整字段与 ES 对应关系见 `INDEX_FIELDS_DOCUMENTATION.md`（若有）。 +**shoplazza_product_sku 字段节选**：`id`, `spu_id`, `shop_id`, `title`, `sku`, `price`, `compare_at_price`, `option1/2/3`, `inventory_quantity`, `image_src`, `tenant_id`, `create_time`, `update_time`, `deleted` 等。完整字段与 ES 对应关系见 `docs/索引字段说明v2.md`、`docs/MySQL到ES文档映射说明.md`。 ### 1.8 相关脚本 @@ -586,8 +586,8 @@ python -c "from transformers import BertTokenizer; import transformers as t; pri |------|------| | `docs/DEVELOPER_GUIDE.md` | 项目全貌、规范、协作方式 | | `docs/Usage-Guide.md` | 运行运维手册：日志、多环境、故障排查、Suggestion 运维 | -| `docs/搜索API速查表.md` | 搜索 API 参数速查 | -| `docs/搜索API对接指南.md` | 搜索 API 完整说明 | +| `docs/搜索API对接指南-速查表.md` | 搜索 API 参数速查 | +| `docs/搜索API对接指南-00-总览与快速开始.md` | 搜索 API 分册总览（其余见 `搜索API对接指南-01`…`-10`） | | `indexer/README.md` | 索引模块职责与接口 | | `embeddings/README.md` | 向量化服务说明 | | `docs/TEI_SERVICE说明文档.md` | TEI 专项（安装、部署、GPU/CPU 模式、排障） | diff --git a/docs/Usage-Guide.md b/docs/Usage-Guide.md index 9686d11..5873680 100644 --- a/docs/Usage-Guide.md +++ b/docs/Usage-Guide.md @@ -647,7 +647,7 @@ curl -X POST "http://localhost:6004/indexer/reindex" \ 两套环境的搜索 / suggestion API 调用完全一致，只是连接到各自的后端 / ES。 -接口返回结构详见 `docs/搜索API对接指南.md` 的“3.7 搜索建议接口”章节。 +接口返回结构详见 `docs/搜索API对接指南-02-搜索建议与即时搜索.md` 的「3.7 搜索建议接口」章节。 --- @@ -737,13 +737,15 @@ curl -X POST http://localhost:6002/search/ \ ## 相关文档 -- **测试数据构造文档**: `TEST_DATA_GUIDE.md` - 如何构造和导入测试数据 -- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南 -- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明 -- **设计文档**: `设计文档.md` - 系统架构和设计说明 -- **README**: `README.md` - 项目概述和快速开始 +- **项目概述与文档索引**: 仓库根目录 `README.md` +- **搜索 API（分册）**: `docs/搜索API对接指南-00-总览与快速开始.md`（导航）；各分册 `docs/搜索API对接指南-01`…`-10-*.md` +- **搜索 API 速查**: `docs/搜索API对接指南-速查表.md` +- **开发与规范**: `docs/DEVELOPER_GUIDE.md` +- **环境与排障**: `docs/QUICKSTART.md` +- **测试数据**: `scripts/mock_data.sh` 与 `docs/QUICKSTART.md` 中数据/ingest 相关章节 +- **索引字段**: `docs/索引字段说明v2.md`、`mappings/search_products.json` --- -**文档版本**: v2.0 -**最后更新**: 2024-12 +**文档版本**: v2.1 +**最后更新**: 2026-04 diff --git a/docs/issue.md b/docs/issue.md index 21311e0..2180025 100644 --- a/docs/issue.md +++ b/docs/issue.md @@ -80,7 +80,7 @@ query匹配了其中任何一个词，都认为，具有颜色意图 - fused_score = (rerank_score + 0.00001) * (text_score + 0.1) ** 0.35 * (knn_score + 0.6) ** 0.2 4. track_scores 与 include_named_queries_score 已接入，调试字段与评估方法已同步到： - docs/相关性检索优化说明.md - - docs/搜索API对接指南.md + - docs/搜索API对接指南-01-搜索接口.md（分册；原单文件已拆分） - docs/Usage-Guide.md 未完成的： @@ -489,7 +489,7 @@ config/environments/.yaml ### 1. 管理 API 文档中关于 `/admin/config` 的描述错误 -[`docs/搜索API对接指南.md`](docs/搜索API对接指南.md)（管理部分附近）和 [`docs/搜索API对接指南-06-管理接口（Admin）.md`](docs/搜索API对接指南-06-管理接口（Admin）.md) 仍将 `/admin/config` 描述为按租户的 JSON（包含 `tenant_id`、`es_index_name`、`supported_languages` 等字段）。实际实现返回的是 `AppConfig.sanitized_dict()`（完整的应用配置，敏感信息已脱敏），而不是租户摘要字段。 +[`docs/搜索API对接指南-06-管理接口（Admin）.md`](docs/搜索API对接指南-06-管理接口（Admin）.md)（原单文件 `搜索API对接指南.md` 已拆分为分册）仍将 `/admin/config` 描述为按租户的 JSON（包含 `tenant_id`、`es_index_name`、`supported_languages` 等字段）。实际实现返回的是 `AppConfig.sanitized_dict()`（完整的应用配置，敏感信息已脱敏），而不是租户摘要字段。 这些指南中还缺少： `GET /admin/config/meta`。 diff --git a/docs/issue.txt b/docs/issue.txt index 96fce8e..4fe7fb0 100644 --- a/docs/issue.txt +++ b/docs/issue.txt @@ -132,9 +132,6 @@ tags字段使用的优化： - - - 是否需要： 当「源语言不在 index_languages」且「某些目标语言的翻译缺失」时，ES 里会额外加一层 用「原始 query 字符串」去撞缺失语种字段 @@ -319,7 +316,7 @@ config/environments/.yaml ### 1. 管理 API 文档中关于 `/admin/config` 的描述错误 -[`docs/搜索API对接指南.md`](docs/搜索API对接指南.md)（管理部分附近）和 [`docs/搜索API对接指南-06-管理接口（Admin）.md`](docs/搜索API对接指南-06-管理接口（Admin）.md) 仍将 `/admin/config` 描述为**按租户**的 JSON（包含 `tenant_id`、`es_index_name`、`supported_languages` 等字段）。实际实现返回的是 **`AppConfig.sanitized_dict()`**（完整的应用配置，敏感信息已脱敏），而不是租户摘要字段。 +[`docs/搜索API对接指南-06-管理接口（Admin）.md`](docs/搜索API对接指南-06-管理接口（Admin）.md)（原单文件 `搜索API对接指南.md` 已拆分为分册）仍将 `/admin/config` 描述为**按租户**的 JSON（包含 `tenant_id`、`es_index_name`、`supported_languages` 等字段）。实际实现返回的是 **`AppConfig.sanitized_dict()`**（完整的应用配置，敏感信息已脱敏），而不是租户摘要字段。 **这些指南中还缺少：** `GET /admin/config/meta`。 @@ -503,7 +500,7 @@ https://help.aliyun.com/zh/model-studio/partial-mode?spm=a2c4g.11186623.help-men - `fused_score = (rerank_score + 0.00001) * (text_score + 0.1) ** 0.35 * (knn_score + 0.6) ** 0.2` 4. `track_scores` 与 `include_named_queries_score` 已接入，调试字段与评估方法已同步到： - `docs/相关性检索优化说明.md` - - `docs/搜索API对接指南.md` + - `docs/搜索API对接指南-01-搜索接口.md`（分册；原单文件已拆分） - `docs/Usage-Guide.md` 未完成的： diff --git a/docs/工作总结-微服务性能优化与架构.md b/docs/工作总结-微服务性能优化与架构.md index 472790c..debd48e 100644 --- a/docs/工作总结-微服务性能优化与架构.md +++ b/docs/工作总结-微服务性能优化与架构.md @@ -99,13 +99,13 @@ instruction: "Given a shopping query, rank product titles by relevance" **具体内容**： - **接口**：`POST /indexer/enrich-content`（Indexer 服务端口 **6004**）。请求体为 `items` 数组，每项含 `spu_id`、`title`（必填）及可选多语言标题等；单次请求最多 **50 条**，建议批量调用。响应 `results` 与 `items` 一一对应，每项含 `spu_id`、`qanchors`（按语言键，如 `qanchors.zh`、`qanchors.en`，逗号分隔短语）、`enriched_attributes`、`tags`。 --- **索引侧**：微服务组合方式下，调用方先拿不含 qanchors/tags 的 doc，再调用本接口补齐后写入 ES 的 `qanchors.{lang}` 等字段；索引 transformer（`indexer/document_transformer.py`、`indexer/product_enrich.py`）内也可在构建 doc 时调用内容理解逻辑，写入 `qanchors.{lang}`。 +- **索引侧**：微服务组合方式下，调用方先拿不含 qanchors/tags 的 doc，再调用本接口补齐后写入 ES 的 `qanchors.{lang}` 等字段；索引 transformer（`indexer/document_transformer.py`、`indexer/product_enrich.py`）内也可在构建 doc 时调用内容理解逻辑，写入 `qanchors.{lang}`。 - **Suggest 侧**：`suggestion/builder.py` 从 ES 商品索引读取 `_source: ["id", "spu_id", "title", "qanchors"]`，对 `qanchors.{lang}` 用 `_split_qanchors` 拆成词条，以 `source="qanchor"` 加入候选，排序时 `qanchor` 权重大于纯 title（`add_product("qanchor", ...)`）；suggest 配置中 `sources: ["query_log", "qanchor"]` 表示候选来源包含 qanchor。 - **实现与依赖**：内容理解内部使用大模型（需 `DASHSCOPE_API_KEY`），支持多语言与 Redis 缓存（如 `product_anchors`）；逻辑与 `indexer/product_enrich` 一致。 **状态**：内容理解字段已接入索引与 suggest 链路；依赖内容理解（qanchors/tags）的**全量数据尚未全部完成一轮**，后续需持续跑满并校验效果。 -详见：`indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md`、`docs/搜索API对接指南.md`（内容理解接口）、`api/routes/indexer.py`（enrich-content 路由）。 +详见：`indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md`、`docs/搜索API对接指南-05-索引接口（Indexer）.md`（`enrich-content` 等）、`api/routes/indexer.py`（enrich-content 路由）。 --- diff --git a/indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md b/indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md index 65329b5..ca9c0c0 100644 --- a/indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md +++ b/indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md @@ -411,5 +411,5 @@ def create_prompt(products: List[Dict[str, str]], target_lang: str = "zh") -> st - 可以在 `dim_keys` 中新增维度名（如 `style`, `benefit` 等），只要在 prompt 与解析逻辑中增加对应列即可； - 可以为 `enriched_attributes` 增加额外字段（如 `confidence`、`source`），用于更精细的控制（当前 mapping 为简单版）。 -如需在查询层面增加基于 `enriched_attributes` 的统一 DSL（类似 `specifications` 的过滤/分面规则），推荐在 `docs/搜索API对接指南.md` 中新增一节，并在 `search/es_query_builder.py` 里封装构造逻辑，避免前端直接拼 nested 查询。 +如需在查询层面增加基于 `enriched_attributes` 的统一 DSL（类似 `specifications` 的过滤/分面规则），推荐在 `docs/搜索API对接指南-01-搜索接口.md` 或 `docs/搜索API对接指南-08-数据模型与字段速查.md` 中新增一节，并在 `search/es_query_builder.py` 里封装构造逻辑，避免前端直接拼 nested 查询。 diff --git a/scripts/benchmark_translation_longtext_single.py b/scripts/benchmark_translation_longtext_single.py index 334faa8..ba48d56 100644 --- a/scripts/benchmark_translation_longtext_single.py +++ b/scripts/benchmark_translation_longtext_single.py @@ -31,7 +31,7 @@ def parse_args() -> argparse.Namespace: parser.add_argument("--source-lang", default="zh") parser.add_argument("--target-lang", default="en") parser.add_argument("--scene", default="sku_name") - parser.add_argument("--source-md", default="docs/搜索API对接指南.md") + parser.add_argument("--source-md", default="docs/DEVELOPER_GUIDE.md") parser.add_argument("--paragraph-min-chars", type=int, default=250) parser.add_argument("--target-doc-chars", type=int, default=4500) parser.add_argument("--min-doc-chars", type=int, default=2400) diff --git a/scripts/perf_api_benchmark.py b/scripts/perf_api_benchmark.py index f334734..4795f2e 100755 --- a/scripts/perf_api_benchmark.py +++ b/scripts/perf_api_benchmark.py @@ -2,7 +2,7 @@ """ API-level performance test script for search stack services. -Default scenarios (aligned with docs/搜索API对接指南.md): +Default scenarios (aligned with docs/搜索API对接指南 分册，如 -01 / -02 / -07): - backend_search POST /search/ - backend_suggest GET /search/suggestions - embed_text POST /embed/text diff --git a/translation/README.md b/translation/README.md index 33ef0c1..b2c9b37 100644 --- a/translation/README.md +++ b/translation/README.md @@ -871,4 +871,4 @@ NLLB 性能优化经验： - [`docs/翻译模块说明.md`](/data/saas-search/docs/翻译模块说明.md)（已收口到本 README，保留为跳转页） - [`docs/QUICKSTART.md`](/data/saas-search/docs/QUICKSTART.md) - [`docs/DEVELOPER_GUIDE.md`](/data/saas-search/docs/DEVELOPER_GUIDE.md) -- [`docs/搜索API对接指南.md`](/data/saas-search/docs/搜索API对接指南.md) +- [`docs/搜索API对接指南-00-总览与快速开始.md`](/data/saas-search/docs/搜索API对接指南-00-总览与快速开始.md)（分册导航；微服务见 `-07`） -- libgit2 0.21.2