文档更新

tangwang
1 parent 465f90e1
Showing 12 changed files with 63 additions and 45 deletions Show diff stats
CLAUDE.md
README.md
docs/DEVELOPER_GUIDE.md
docs/QUICKSTART.md
docs/Usage-Guide.md
docs/issue.md
docs/issue.txt
docs/工作总结-微服务性能优化与架构.md
indexer/ANCHORS_AND_SEMANTIC_ATTRIBUTES.md
scripts/benchmark_translation_longtext_single.py
scripts/perf_api_benchmark.py
translation/README.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**:
 ```
@@ -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 鍏ュ彛锛坰earch/admin/indexer app锛
-- `search/`锛氬彫鍥炪佹帓搴忋佺粨鏋滅粍缁
+- `search/`锛氬彫鍥炪佸垎灞傛帓搴忎笌缁撴灉缁勭粐锛圗S 鍙洖 鈫 `coarse_rank` 铻嶅悎鏂囨湰/KNN 鈫 鍙 `fine_rank` 杞婚噺绮炬帓 鈫 `rerank` 铻嶅悎妯″瀷鍒嗕笌 ES 淇″彿锛沗debug=true` 鏃惰繑鍥炲悇闃舵 rank / fusion 璋冭瘯瀛楁锛
 - `query/`锛氭煡璇㈣В鏋愩佸璇█澶勭悊銆佹敼鍐
 - `indexer/`锛歁ySQL 琛屾暟鎹 -> 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鈥.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-绱㈠紩鎺ュ彛锛圛ndexer锛.md` | 绱㈠紩涓 `build-docs` / `enrich-content` 绛 |
+| `鎼滅储API瀵规帴鎸囧崡-06-绠＄悊鎺ュ彛锛圓dmin锛.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 宸ュ巶
 - 浼樺厛鍑忓皯閲嶅瀹炵幇锛屽鐢ㄧ幇鏈夎浆鎹㈤摼璺笌閰嶇疆瑙ｆ瀽鍏ュ彛
@@ -44,8 +44,9 @@
  
 - [QUICKSTART.md](./QUICKSTART.md) 鈥 鐜銆佹湇鍔°佹ā鍧椼佽姹傜ず渚嬶紱搂2鈥撀 鍚熀纭閰嶇疆涓 Provider/妯″潡鎵╁睍
 - [缈昏瘧妯″潡璇存槑.md](./缈昏瘧妯″潡璇存槑.md) 鈥 translator service銆乧apability 閰嶇疆銆佹湰鍦版ā鍨嬮儴缃蹭笌鎺ュ彛濂戠害
-- [绯荤粺璁捐鏂囨。.md](./绯荤粺璁捐鏂囨。.md) 鈥 绱㈠紩缁撴瀯銆佹暟鎹祦銆侀氱敤鍖栬璁
-- [鎼滅储API瀵规帴鎸囧崡.md](./鎼滅储API瀵规帴鎸囧崡.md) 鈥 鎼滅储/绱㈠紩/绠＄悊鎺ュ彛瀹屾暣璇存槑
+- 绱㈠紩涓庢暟鎹祦锛歔绱㈠紩鏂规.md](./绱㈠紩鏂规.md)銆乕绱㈠紩瀛楁璇存槑v2.md](./绱㈠紩瀛楁璇存槑v2.md)銆乕MySQL鍒癊S鏂囨。鏄犲皠璇存槑.md](./MySQL鍒癊S鏂囨。鏄犲皠璇存槑.md)
+- [鎼滅储API瀵规帴鎸囧崡-00-鎬昏涓庡揩閫熷紑濮.md](./鎼滅储API瀵规帴鎸囧崡-00-鎬昏涓庡揩閫熷紑濮.md) 鈥 鎼滅储/绱㈠紩/绠＄悊/寰湇鍔 API锛堝垎鍐屽叆鍙ｏ紱鍒嗗唽鍒楄〃瑙 README锛
+- [鎼滅储API瀵规帴鎸囧崡-閫熸煡琛.md](./鎼滅储API瀵规帴鎸囧崡-閫熸煡琛.md) 鈥 鎼滅储 API 鍙傛暟閫熸煡
 - [QUICKSTART.md](./QUICKSTART.md) 搂1.4鈥.8 鈥 绯荤粺瑕佹眰銆丳ython 鐜銆佸閮ㄦ湇鍔′笌鐢熶骇鍑瘉銆佸簵鍖犳暟鎹簮
 - [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锛堟寜绉熸埛绱㈠紩锛歴earch_products_tenant_<id>锛
-    鈫 鎼滅储 API锛圦ueryParser 鈫 Searcher锛屽彲閫夌炕璇/鍚戦噺/閲嶆帓锛
+    鈫 鎼滅储 API锛圦ueryParser 鈫 Searcher锛氱矖鎺 coarse_rank 鈫 鍙夌簿鎺 fine_rank 鈫 閲嶆帓 rerank锛
     鈫 鍓嶇 / 涓婃父涓氬姟
 ```
  
 - **绱㈠紩渚**锛欽ava 鎴栬剼鏈喅瀹氣滃鍝簺 SPU 鍋氱储寮曗濓紱Python indexer 璐熻矗鈥滃崟鏉/鎵归噺 SPU 鈫 ES 鏂囨。鈥濈殑瀹屾暣閫昏緫锛屾垨閫氳繃 `/indexer/build-docs` 浠呰繑鍥 doc銆佺敱璋冪敤鏂瑰啓 ES銆
-- **鎼滅储渚**锛氳姹傜粡 QueryParser锛堣В鏋愩佹敼鍐欍佺炕璇戙佸悜閲忓寲锛夆啋 Searcher锛圗S 鏌ヨ銆佸彲閫夐噸鎺掞級鈫 缁撴灉鏍煎紡鍖 鈫 杩斿洖銆
+- **鎼滅储渚**锛氳姹傜粡 QueryParser锛堣В鏋愩佹敼鍐欍佺炕璇戙佸悜閲忓寲锛夆啋 Searcher锛圗S 鍙洖涓庢煡璇㈡瀯寤恒乣coarse_rank` 铻嶅悎鏂囨湰/KNN銆佸彲閫 `fine_rank`銆乣rerank` 涓庡垎鏁拌瀺鍚堬級鈫 缁撴灉鏍煎紡鍖 鈫 杩斿洖銆
  
 ### 3.2 鏈嶅姟鎷撴墤涓庣鍙
  
@@ -109,7 +110,7 @@ api/                 # FastAPI 搴旂敤锛氭悳绱㈣矾鐢便佺鐞嗚矾鐢便佺储寮曡矾
 config/              # 閰嶇疆鍔犺浇涓庤В鏋愶細config.yaml銆乻ervices銆乪nv
 indexer/             # MySQL 鈫 ES 绠￠亾锛歮apping銆乼ransformer銆乥ulk銆佸閲忋乥uild-docs
 query/               # 鏌ヨ瑙ｆ瀽锛氳鑼冨寲銆佹敼鍐欍佺炕璇戙乪mbedding 璋冪敤銆佽瑷璁″垝鐢熸垚
-search/              # 鎼滅储鎵ц锛氬璇█鏌ヨ鏋勫缓銆丼earcher銆侀噸鎺掑鎴风銆佸垎鏁拌瀺鍚
+search/              # 鎼滅储鎵ц锛氬璇█鏌ヨ鏋勫缓銆丼earcher銆佺矖鎺/绮炬帓/閲嶆帓涓庡垎鏁拌瀺鍚
 embeddings/          # 鍚戦噺鍖栵細鏈嶅姟绔紙server锛夈佹枃鏈/鍥惧儚鍚庣銆佸崗璁笌閰嶇疆
 reranker/            # 閲嶆帓锛氭湇鍔＄锛坰erver锛夈佸悗绔紙backends锛夈侀厤缃
 providers/           # 鑳藉姏鎻愪緵鑰咃細鍚戦噺/閲嶆帓鐨勫鎴风鎶借薄涓庡伐鍘
@@ -144,7 +145,7 @@ docs/                # 鏂囨。锛堝惈鏈寚鍗楋級
  
 - **鑱岃矗**锛氬皢 MySQL 琛屾垨涓婃父浼犲叆鐨 SPU/SKU/options 杞负绗﹀悎 `mappings/search_products.json` 鐨 ES 鏂囨。锛涘惈澶氳瑷缁勭粐銆佺炕璇戣皟鐢ㄣ佸悜閲忕敓鎴愩佽鏍/SKU 鑱氬悎銆佺被鐩矾寰勭瓑锛涙敮鎸佸叏閲/澧為噺鍐欏叆 ES锛屼互鍙婁粎杩斿洖 doc锛坆uild-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鍒癊S鏂囨。鏄犲皠璇存槑.md](./MySQL鍒癊S鏂囨。鏄犲皠璇存槑.md)銆
  
 ### 4.4 query
  
@@ -153,8 +154,8 @@ docs/                # 鏂囨。锛堝惈鏈寚鍗楋級
  
 ### 4.5 search
  
-- **鑱岃矗**锛氭瀯寤哄璇█ ES 鏌ヨ銆佹墽琛屾绱€佸彲閫夐噸鎺掋佸垎鏁拌瀺鍚堛佺粨鏋滄牸寮忓寲锛涘垎闈€佽繃婊ゃ佹帓搴忋丼KU 缁村害绛涢夌瓑銆
-- **鍘熷垯**锛氶噸鎺掗氳繃 `search/rerank_client.py` 璋冪敤 `create_rerank_provider()`锛屼笉鍏冲績閲嶆帓鏈嶅姟鍐呮槸 BGE 杩樻槸 Qwen3锛涗笌 ES 鐨勪氦浜掑皝瑁呭湪 Searcher 鍐咃紝渚夸簬 mock 涓庢祴璇曘
+- **鑱岃矗**锛氭瀯寤哄璇█ ES 鏌ヨ銆佹墽琛屾绱€佸垎灞傛帓搴忥紙`coarse_rank` 鈫 鍙 `fine_rank` 鈫 `rerank`锛変笌鍒嗘暟铻嶅悎銆佺粨鏋滄牸寮忓寲锛涘垎闈€佽繃婊ゃ佹帓搴忋丼KU 缁村害绛涢夌瓑銆
+- **鍘熷垯**锛氱簿鎺/閲嶆帓閫氳繃 `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鈥撀佹湰鎸囧崡 搂7 |
-| 绱㈠紩缁撴瀯銆佹暟鎹祦銆侀氱敤鍖栬璁 | [绯荤粺璁捐鏂囨。.md](./绯荤粺璁捐鏂囨。.md) |
-| 鎼滅储/绱㈠紩 API 瀹屾暣璇存槑 | [鎼滅储API瀵规帴鎸囧崡.md](./鎼滅储API瀵规帴鎸囧崡.md) |
+| 绱㈠紩缁撴瀯銆佸瓧娈点丮ySQL鈫扙S 鏄犲皠 | [绱㈠紩鏂规.md](./绱㈠紩鏂规.md)銆乕绱㈠紩瀛楁璇存槑v2.md](./绱㈠紩瀛楁璇存槑v2.md)銆乕MySQL鍒癊S鏂囨。鏄犲皠璇存槑.md](./MySQL鍒癊S鏂囨。鏄犲皠璇存槑.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鈥.8 |
 | 杩愮淮銆佹棩蹇椼佸鐜銆佹晠闅 | [Usage-Guide.md](./Usage-Guide.md) |
 | 绱㈠紩妯″潡鑱岃矗涓 Java 瀵规帴 | [indexer/README.md](../indexer/README.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 &quot;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 模式、排障） |
@@ -647,7 +647,7 @@ curl -X POST &quot;http://localhost:6004/indexer/reindex&quot; \
  
 两套环境的搜索 / 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
@@ -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/&lt;env&gt;.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`。
  
@@ -132,9 +132,6 @@ tags字段使用的优化：
  
  
  
-
-
-
 是否需要：
 当「源语言不在 index_languages」且「某些目标语言的翻译缺失」时，ES 里会额外加一层 用「原始 query 字符串」去撞缺失语种字段 
  
@@ -319,7 +316,7 @@ config/environments/&lt;env&gt;.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`
  
 未完成的：
@@ -99,13 +99,13 @@ instruction: &quot;Given a shopping query, rank product titles by relevance&quot;
  
 **具体内容**：
 - **接口**：`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 路由）。
  
 ---
  
@@ -411,5 +411,5 @@ def create_prompt(products: List[Dict[str, str]], target_lang: str = &quot;zh&quot;) -&gt; 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 查询。 
  
@@ -31,7 +31,7 @@ def parse_args() -&gt; 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)
@@ -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
@@ -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`）