docs

tangwang
1 parent 701ae503
Showing 5 changed files with 311 additions and 266 deletions Show diff stats
docs/PROVIDER_ARCHITECTURE.md
docs/QUICKSTART.md
docs/Usage-Guide.md
docs/基础配置指南.md
main.py
-# Provider 架构与扩展指南
+# Provider 架构（已并入）
-本文档说明如何统一管理翻译、向量化、重排等“能力提供者（provider）”。
+本文档已并入 `docs/QUICKSTART.md`，请直接查看：
-**扩展重排/向量化后端（如新增 Qwen3-Reranker、vLLM 等）**：请同时参阅 [模块扩展规范（MODULE_EXTENSION_SPEC.md）](./MODULE_EXTENSION_SPEC.md)，其中定义了服务内后端协议、统一配置结构与可插拔实现方式。
+- `docs/QUICKSTART.md` -> **3. Provider 架构**
+- `docs/QUICKSTART.md` -> **4. 模块扩展规范（Embedding / Rerank）**
-## 1. 设计目标
-
-- **调用方稳定**：业务代码不关心具体供应商，只调用统一接口。
-- **配置可切换**：通过配置切换 provider，不改业务代码。
-- **单一配置源**：所有 provider 配置在 `config/config.yaml` 的 `services` 块。
-
-## 2. 当前落地状态
-
-### 2.1 统一入口
-
-- **模块**：`providers/`
-- **工厂**：`create_translation_provider()`, `create_rerank_provider()`, `create_embedding_provider()`
-- **配置**：`config/services_config.py` 从 `services` 块加载，env 可覆盖
-
-### 2.2 翻译
-
-- `providers/translation.py`：`direct`（进程内 Translator）、`http`（HTTP 服务）
-- 调用方：`query/query_parser.py`, `indexer/indexing_utils.py`
-
-### 2.3 重排
-
-- `providers/rerank.py`：`http`（vllm 预留）
-- 调用方：`search/rerank_client.py` → `run_rerank()`
-
-### 2.4 向量化
-
-- `providers/embedding.py`：`http`（vllm 预留）
-- 封装 `BgeEncoder` / `CLIPImageEncoder`，URL 来自 `services_config`
-
-## 3. 配置
-
-**单一配置源**：`config/config.yaml` 的 `services` 块。
-
-```yaml
-services:
-  translation:
-    provider: "direct"  # direct | http
-    providers:
-      direct: { model: "qwen" }
-      http: { base_url: "http://127.0.0.1:6006", model: "qwen", timeout_sec: 10.0 }
-  embedding:
-    provider: "http"
-    providers:
-      http: { base_url: "http://127.0.0.1:6005" }
-  rerank:
-    provider: "http"
-    providers:
-      http: { base_url: "http://127.0.0.1:6007" }
-```
-
-**环境变量**（部署态覆盖）：`TRANSLATION_PROVIDER`, `TRANSLATION_SERVICE_URL`, `EMBEDDING_SERVICE_URL`, `RERANKER_SERVICE_URL`
-
-## 4. 新增 provider
-
-1. 在 `providers/<capability>.py` 中实现新 provider 类
-2. 在 `create_*_provider()` 中注册分支
-3. 在 `config/config.yaml` 的 `services.<capability>.providers` 中补充参数
+保留此文件仅用于兼容历史链接，避免重复维护导致内容漂移。
-# 开发者快速上手
+# 开发与配置指南
-新人入口文档：环境、服务、模块、请求示例一页搞定。
+新人入口：环境、服务、模块、请求示例、基础配置、Provider 架构、模块扩展规范，一文档搞定。
-**建议**：首次参与开发请先阅读 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) 建立项目全貌与规范，再使用本页做环境与请求速查。
+**建议**：首次参与开发请先阅读 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) 建立项目全貌与协作规范，再使用本文做环境与配置速查。
-## 1. 环境
+---
+
+## 为什么这样整合
+
+本文已合并并替代以下文档中的核心内容：
+
+- `docs/PROVIDER_ARCHITECTURE.md`
+- `docs/MODULE_EXTENSION_SPEC.md`
+- `docs/基础配置指南.md`
+- 原 `docs/QUICKSTART.md`
+
+关于 `docs/Usage-Guide.md`：保留为**运行/运维手册**更清晰（日志、故障排查、多环境切换、建议索引运行细节），本文只保留开发常用且高频的信息，避免一个文档同时承担“开发规范 + 运维 runbook”导致冗长和混乱。
+
+---
+
+## 目录
+
+1. [快速上手](#1-快速上手)
+2. [基础配置与搜索行为](#2-基础配置与搜索行为)
+3. [Provider 架构](#3-provider-架构)
+4. [模块扩展规范（Embedding / Rerank）](#4-模块扩展规范embedding--rerank)
+5. [验证、日志与常见排障入口](#5-验证日志与常见排障入口)
+6. [相关文档](#6-相关文档)
+
+---
+
+## 1. 快速上手
+
+### 1.1 环境准备
+
+```bash
+source activate.sh
+# 首次推荐：
+./scripts/create_venv.sh
+# 或使用 conda：
+# conda env create -f environment.yml
+```
+
+依赖：Python 3.8+、Elasticsearch 8.x、MySQL、Redis（可选，缓存用途）。
+
+如果需要本地运行 embedding 模型（torch/transformers 等重依赖）：
 ```bash
+INSTALL_ML=1 ./scripts/create_venv.sh
 source activate.sh
-# 首次：./scripts/create_venv.sh 或 conda env create -f environment.yml
 ```
-依赖：Python 3.8+、Elasticsearch 8.x、MySQL、Redis（可选）。详见 `docs/环境配置说明.md`。
+详细环境说明见 `docs/环境配置说明.md`。
-## 2. 服务与端口
+### 1.2 服务与端口
 | 服务 | 端口 | 默认启动 | 说明 |
 |------|-----:|:--------:|------|
-| backend | 6002 | ✓ | 搜索 API |
-| indexer | 6004 | ✓ | 索引 API |
+| backend | 6002 | ✓ | 搜索 API（`/search/*`）+ 管理接口（`/admin/*`） |
+| indexer | 6004 | ✓ | 索引 API（`/indexer/*`） |
 | frontend | 6003 | ✓ | 调试 UI |
-| embedding | 6005 | - | 向量服务 |
-| translator | 6006 | - | 翻译服务 |
-| reranker | 6007 | - | 重排服务 |
+| embedding | 6005 | - | 向量服务（`/embed/text`, `/embed/image`） |
+| translator | 6006 | - | 翻译服务（`/translate`） |
+| reranker | 6007 | - | 重排服务（`/rerank`） |
+
+启动与停止：
 ```bash
 ./run.sh
-# 全功能：START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh
+# 启动全部能力
+START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh
+
 ./scripts/service_ctl.sh status
 ./scripts/stop.sh
 ```
-## 3. 模块与请求
+### 1.3 常用 API 请求示例
-### 3.1 搜索 API（backend 6002）
+#### 搜索 API（backend 6002）
 ```bash
 # 文本搜索
@@ -48,77 +92,285 @@ curl -X POST http://localhost:6002/search/image \
   -H "X-Tenant-ID: 162" \
   -d '{"image_url": "https://example.com/img.jpg", "size": 10}'
-# 建议
-curl "http://localhost:6002/search/suggestions?q=玩&size=5" -H "X-Tenant-ID: 162"
+# Suggestion
+curl "http://localhost:6002/search/suggestions?q=玩&size=5" \
+  -H "X-Tenant-ID: 162"
+
+# 健康与统计
+curl http://localhost:6002/admin/health
+curl http://localhost:6002/admin/stats
 ```
-API 文档：http://localhost:6002/docs
+API 文档：`http://localhost:6002/docs`
-### 3.2 索引 API（indexer 6004）
+#### 索引 API（indexer 6004）
 ```bash
 # 创建租户索引
 ./scripts/create_tenant_index.sh 162
-# 全量索引
+# 全量重建（更新/写入，不删除旧索引）
 curl -X POST http://localhost:6004/indexer/reindex \
   -H "Content-Type: application/json" \
   -d '{"tenant_id": "162", "batch_size": 500}'
-# 构建文档（不写 ES，供上游调用）
+# 增量索引
+curl -X POST http://localhost:6004/indexer/index \
+  -H "Content-Type: application/json" \
+  -d '{"tenant_id": "162", "spu_ids": ["1001", "1002"]}'
+
+# 构建文档（不写 ES）
 curl -X POST http://localhost:6004/indexer/build-docs \
   -H "Content-Type: application/json" \
-  -d '{"tenant_id": "162", "items": [{"spu": {...}, "skus": [...], "options": [...]}]}'
+  -d '{"tenant_id":"162","items":[{"spu":{},"skus":[],"options":[]}]}'
 ```
-### 3.3 向量服务（embedding 6005）
+API 文档：`http://localhost:6004/docs`
+
+#### Embedding 服务（6005）
 ```bash
 ./scripts/start_embedding_service.sh
-# 文本向量
 curl -X POST http://localhost:6005/embed/text \
   -H "Content-Type: application/json" \
   -d '["衣服", "Bohemian Maxi Dress"]'
-# 图片向量（URL 列表）
 curl -X POST http://localhost:6005/embed/image \
   -H "Content-Type: application/json" \
   -d '["https://example.com/img.jpg"]'
 ```
-### 3.4 翻译服务（translator 6006）
+#### Translator 服务（6006）
 ```bash
 ./scripts/start_translator.sh
 curl -X POST http://localhost:6006/translate \
   -H "Content-Type: application/json" \
-  -d '{"text": "商品名称", "target_lang": "en", "source_lang": "zh"}'
+  -d '{"text":"商品名称","target_lang":"en","source_lang":"zh"}'
 ```
-### 3.5 重排服务（reranker 6007）
+#### Reranker 服务（6007）
 ```bash
 ./scripts/start_reranker.sh
 curl -X POST http://localhost:6007/rerank \
   -H "Content-Type: application/json" \
-  -d '{"query": "wireless mouse", "docs": ["logitech mx master", "usb cable"]}'
+  -d '{"query":"wireless mouse","docs":["logitech mx master","usb cable"]}'
+```
+
+### 1.4 配置入口总览
+
+- **搜索行为配置**：`config/config.yaml`
+- **索引结构定义**：`mappings/search_products.json`
+- **provider/服务配置**：`config/config.yaml` 的 `services` 块
+- **环境变量**：`.env`
+
+---
+
+## 2. 基础配置与搜索行为
+
+### 2.1 总体原则
+
+- **统一索引结构**：所有租户使用同一套 mapping（按租户数据分索引名 + 文档内 `tenant_id` 隔离）
+- **SPU 级索引**：每个文档是一个 SPU，包含嵌套 `skus`、`specifications`
+- **配置文件驱动**：搜索权重、搜索域、重排融合、provider 全在 `config/config.yaml`，不再以“硬编码配置”为主
+
+### 2.2 索引结构（Mapping）
+
+文件：`mappings/search_products.json`
+
+核心字段可分为：
+
+- 标识字段：`tenant_id`, `spu_id`
+- 多语言文本：`title.zh/en`, `brief.zh/en`, `description.zh/en`, `vendor.zh/en`, `category_path.zh/en`, `category_name_text.zh/en`
+- 类目过滤：`category1_name`, `category2_name`, `category3_name` 等
+- 规格/变体：`specifications`（nested）、`skus`（nested）
+- 价格库存：`min_price`, `max_price`, `total_inventory` 等
+- 向量：`title_embedding`（dense vector）、`image_embedding`（nested）
+
+### 2.3 查询、权重、排序（`config/config.yaml`）
+
+- `field_boosts`：字段权重（如标题、品牌、类目）
+- `indexes`：搜索域（default/title/vendor/category/tags）
+- `query_config`：语言、embedding 开关、source_fields、knn_boost、翻译提示词等
+- `ranking.expression`：融合表达式（例如 `bm25() + 0.25*text_embedding_relevance()`）
+- `function_score`：ES 层加权函数
+- `rerank`：重排窗口、超时、ES/AI 融合权重
+
+### 2.4 分面与返回字段
+
+- 分面字段通常包括：`category1_name`、`category2_name`、`category3_name`、`specifications.*`
+- `query_config.source_fields` 控制返回字段（`null`=全部，`[]`=不返回 source，列表=指定字段）
+- 多语言返回遵循请求 language 与字段回退策略
+
+### 2.5 修改配置时怎么做
+
+| 修改项 | 操作 |
+|--------|------|
+| 索引结构（mapping） | 修改 `mappings/search_products.json` → `./scripts/create_tenant_index.sh <tenant_id>` → 重新导入 |
+| 搜索域/权重/排序/重排 | 修改 `config/config.yaml` 对应块 |
+| provider 与服务 URL | 修改 `config/config.yaml` 的 `services` 块，或用环境变量覆盖 |
+
+---
+
+## 3. Provider 架构
+
+目标：调用方稳定、配置可切换、单一配置源。
+
+### 3.1 当前代码结构
+
+- 模块：`providers/`
+- 工厂：`create_translation_provider()`、`create_embedding_provider()`、`create_rerank_provider()`
+- 配置解析：`config/services_config.py`
+
+| 能力 | Provider 实现 | 调用方 |
+|------|---------------|--------|
+| translation | `providers/translation.py`（direct/http） | `query/query_parser.py`、索引链路 |
+| embedding | `providers/embedding.py`（http） | 文本/图像编码调用 |
+| rerank | `providers/rerank.py`（http） | `search/rerank_client.py` |
+
+### 3.2 配置与覆盖
+
+统一在 `config/config.yaml`：
+
+```yaml
+services:
+  translation:
+    provider: "direct"
+    providers:
+      direct: { model: "qwen" }
+      http: { base_url: "http://127.0.0.1:6006", model: "qwen", timeout_sec: 10.0 }
+  embedding:
+    provider: "http"
+    providers:
+      http: { base_url: "http://127.0.0.1:6005" }
+  rerank:
+    provider: "http"
+    providers:
+      http: { base_url: "http://127.0.0.1:6007", service_url: "http://127.0.0.1:6007/rerank" }
+```
+
+环境变量覆盖（优先级更高）：
+
+- `TRANSLATION_PROVIDER`
+- `TRANSLATION_SERVICE_URL`
+- `EMBEDDING_SERVICE_URL`
+- `RERANKER_SERVICE_URL`
+- `RERANK_BACKEND`（服务内后端）
+
+### 3.3 新增 provider 的最小步骤
+
+1. 在 `providers/<capability>.py` 实现 provider 类
+2. 在 `create_*_provider()` 注册
+3. 在 `config/config.yaml` 的 `services.<capability>.providers` 新增配置
+
+---
+
+## 4. 模块扩展规范（Embedding / Rerank）
+
+这里重点区分两层：
+
+- **Provider 层（调用方式）**：调用方如何访问能力（http/direct）
+- **Backend 层（推理实现）**：服务进程内部具体模型实现（bge / qwen3_vllm / ...）
+
+### 4.1 Rerank（重排）扩展
+
+调用链：
+
+`search/rerank_client.py` -> `create_rerank_provider()` -> `HttpRerankProvider` -> `POST /rerank`
+
+服务实现：
+
+- `reranker/server.py`
+- `reranker/backends/__init__.py`（工厂）
+- `reranker/backends/bge.py`
+- `reranker/backends/qwen3_vllm.py`
+
+后端协议（服务内）：
+
+- 实现 `score_with_meta(query, docs, normalize) -> (scores, meta)`
+- 返回 `scores` 与输入 `docs` 等长且顺序一致
+
+配置位置：
+
+`config/config.yaml` -> `services.rerank.backend` + `services.rerank.backends.<name>`
+
+### 4.2 Embedding（向量化）扩展
+
+调用链：
+
+`create_embedding_provider()` -> `POST /embed/text` / `POST /embed/image`
+
+服务实现：
+
+- `embeddings/server.py`（文本和图像可独立加载）
+- 文本后端现用 BGE
+- 图像后端支持本地 CLIP 或 clip-as-service
+
+扩展建议：
+
+- 文本后端统一提供批量编码能力（与输入索引对齐）
+- 图像后端实现 `ImageEncoderProtocol`（`encode_image_urls`）
+- 如后续后端增多，建议与 rerank 一样在 `services.embedding.backend(s)` 统一配置
+
+### 4.3 新增后端检查清单（以 `qwen3_vllm` 为例）
+
+1. 实现后端协议（服务内）
+2. 在后端工厂注册（如 `get_rerank_backend`）
+3. 增加 `config/config.yaml` 对应 backend 配置
+4. 提供健康检查中的 backend/model 可观测信息
+5. 保持外部 HTTP 契约不变，调用方无需改造
+
+---
+
+## 5. 验证、日志与常见排障入口
+
+### 5.1 快速健康检查
+
+```bash
+curl http://localhost:6002/health
+curl http://localhost:6002/admin/health
+curl http://localhost:6004/health
+curl http://localhost:6005/health
+curl http://localhost:6006/health
+curl http://localhost:6007/health
+```
+
+### 5.2 常看日志
+
+- `logs/backend.log`
+- `logs/indexer.log`
+- `logs/frontend.log`
+- `logs/embedding.log`
+- `logs/translator.log`
+- `logs/reranker.log`
+- `logs/search_engine.log`
+- `logs/errors.log`
+
+### 5.3 常用排障命令
+
+```bash
+./scripts/service_ctl.sh status
+curl http://localhost:9200
+lsof -i :6002
+lsof -i :6004
 ```
-## 4. 配置
+更完整的运行排障（多环境切换、Suggestion 构建、FAQ）见 `docs/Usage-Guide.md`。
-- **主配置**：`config/config.yaml`（搜索行为、字段权重、分面等）
-- **服务 provider**：`config/config.yaml` 的 `services` 块（翻译/向量/重排的 provider 与 URL）
-- **环境变量**：`.env`（DB、ES、Redis、API Key 等）
+---
-## 5. 延伸阅读
+## 6. 相关文档
 | 文档 | 用途 |
 |------|------|
-| `docs/Usage-Guide.md` | 运维：日志、多环境、故障排查 |
+| `docs/DEVELOPER_GUIDE.md` | 项目全貌、规范、协作方式 |
+| `docs/Usage-Guide.md` | 运行运维手册：日志、多环境、故障排查、Suggestion 运维 |
 | `docs/搜索API速查表.md` | 搜索 API 参数速查 |
 | `docs/搜索API对接指南.md` | 搜索 API 完整说明 |
-| `docs/PROVIDER_ARCHITECTURE.md` | 翻译/向量/重排 provider 扩展 |
 | `indexer/README.md` | 索引模块职责与接口 |
+| `embeddings/README.md` | 向量化服务说明 |
+| `reranker/README.md` | 重排服务说明 |
-# 使用指南 - saas-search
+# 使用指南 - saas-search（运行与运维）
-本文档提供完整的使用指南，包括环境准备、服务启动、配置说明、日志查看等。
+本文档聚焦运行与运维：服务启动/停止、日志查看、多环境切换、故障排查、Suggestion 索引运维。
+
+开发与配置（环境入口、配置体系、Provider 架构、模块扩展规范）请优先阅读 `docs/QUICKSTART.md`。
 ## 目录
@@ -79,15 +81,15 @@ DB_PASSWORD=your_password
 # Elasticsearch配置
 ES_HOST=http://localhost:9200
 ES_USERNAME=essa
-ES_PASSWORD=4hOaLaf41y2VuI8y
+ES_PASSWORD=your_es_password
 # Redis配置（可选，用于缓存）
 REDIS_HOST=localhost
 REDIS_PORT=6479
-REDIS_PASSWORD=BMfv5aI31kgHWtlx
+REDIS_PASSWORD=your_redis_password
 # DeepL翻译API（可选）
-DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
+DEEPL_AUTH_KEY=your_deepl_auth_key
 # 运行环境（用于区分 prod / uat / test / dev）
 RUNTIME_ENV=prod
@@ -263,7 +265,7 @@ python -m http.server 6003
 # Elasticsearch配置
 ES_HOST=http://localhost:9200
 ES_USERNAME=essa
-ES_PASSWORD=4hOaLaf41y2VuI8y
+ES_PASSWORD=your_es_password
 # MySQL配置
 DB_HOST=120.79.247.228
@@ -275,10 +277,10 @@ DB_PASSWORD=your_password
 # Redis配置（可选，用于缓存）
 REDIS_HOST=localhost
 REDIS_PORT=6479
-REDIS_PASSWORD=BMfv5aI31kgHWtlx
+REDIS_PASSWORD=your_redis_password
 # DeepL翻译API
-DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
+DEEPL_AUTH_KEY=your_deepl_auth_key
 # API服务配置
 API_HOST=0.0.0.0
-# 基础配置指南
+# 基础配置指南（已并入）
-## 概述
+本文档内容已并入 `docs/QUICKSTART.md`，请直接查看：
-搜索引擎采用**统一硬编码配置**方案，所有租户共享相同的索引结构和查询配置，无需单独配置。
+- `docs/QUICKSTART.md` -> **2. 基础配置与搜索行为**
-## 核心特性
+说明：
-- **统一索引结构**: 所有租户共享 `search_products` 索引
-- **硬编码配置**: 索引 mapping 和查询配置直接硬编码在代码中，无需配置文件
-- **SPU级别索引**: 每个ES文档代表一个SPU，包含嵌套的 `skus` 和 `specifications` 数组
-- **租户隔离**: 通过 `tenant_id` 字段实现数据隔离
-- **多语言支持**: 文本字段支持中英文双语，后端根据 `language` 参数自动选择
+- 历史版本中“统一硬编码配置”的描述已过时。
+- 当前搜索行为与 provider 配置以 `config/config.yaml` 为主，索引结构在 `mappings/search_products.json`。
-## 索引结构
-
-### Mapping 文件位置
-
-`mappings/search_products.json`
-
-### 主要字段
-
-#### 基础标识
-- `tenant_id` (keyword) - 租户ID（必需，用于隔离）
-- `spu_id` (keyword) - SPU ID
-- `create_time`, `update_time` (date) - 时间字段
-
-#### 多语言文本字段
-- `title.zh`, `title.en` (text) - 标题（中英文）
-- `brief.zh`, `brief.en` (text) - 短描述（中英文）
-- `description.zh`, `description.en` (text) - 详细描述（中英文）
-- `vendor.zh`, `vendor.en` (text) - 供应商/品牌（中英文，含keyword子字段）
-- `category_path.zh`, `category_path.en` (text) - 类目路径（中英文）
-- `category_name_text.zh`, `category_name_text.en` (text) - 类目名称（中英文）
-
-#### 类目字段
-- `category_id` (keyword) - 类目ID
-- `category_name` (keyword) - 类目名称
-- `category_level` (integer) - 类目层级
-- `category1_name`, `category2_name`, `category3_name` (keyword) - 多级类目
-
-#### 规格和选项
-- `specifications` (nested) - 规格列表（name, value, sku_id）
-- `option1_name`, `option2_name`, `option3_name` (keyword) - 选项名称
-
-#### 价格和库存
-- `min_price`, `max_price`, `compare_at_price` (float) - 价格字段
-- `sku_prices` (float) - SKU价格列表（数组）
-- `sku_weights` (long) - SKU重量列表（数组）
-- `sku_weight_units` (keyword) - SKU重量单位列表（数组）
-- `total_inventory` (long) - 总库存
-
-#### 嵌套字段
-- `skus` (nested) - SKU详细信息数组
-- `image_embedding` (nested) - 图片向量（仅用于搜索）
-
-#### 其他
-- `tags` (keyword) - 标签列表（数组）
-- `image_url` (keyword, index: false) - 主图URL
-- `title_embedding` (dense_vector) - 标题向量（仅用于搜索，不返回）
-
-## 查询配置
-
-### 文本召回字段
-
-默认同时搜索以下字段（中英文都包含）：
-- `title.zh^3.0`, `title.en^3.0`
-- `brief.zh^1.5`, `brief.en^1.5`
-- `description.zh^1.0`, `description.en^1.0`
-- `vendor.zh^1.5`, `vendor.en^1.5`
-- `category_path.zh^1.5`, `category_path.en^1.5`
-- `category_name_text.zh^1.5`, `category_name_text.en^1.5`
-- `tags^1.0`
-
-### 查询架构
-
-**结构**: `filters AND (text_recall OR embedding_recall)`
-
-- **filters**: 前端传递的过滤条件（永远起作用）
-- **text_recall**: 文本相关性召回（同时搜索中英文字段）
-- **embedding_recall**: 向量召回（KNN，使用 `title_embedding`），根据 query_tokens 自适应调整 k、num_candidates、boost（详见 `docs/相关性检索优化说明.md` 3.6 节）
-- **function_score**: 包装召回部分，支持提权字段
-
-### Function Score 配置
-
-位置: `search/query_config.py` 中的 `FUNCTION_SCORE_CONFIG`
-
-支持的类型：
-- `filter_weight`: 条件权重（如新品提权）
-- `field_value_factor`: 字段值因子（如销量因子）
-- `decay`: 衰减函数（如时间衰减）
-
-## 分面配置
-
-### 默认分面字段
-
-- `category1_name` - 一级类目
-- `category2_name` - 二级类目
-- `category3_name` - 三级类目
-- `specifications` - 规格分面（嵌套聚合，按name分组，然后按value聚合）
-
-### 规格分面说明
-
-`specifications` 使用特殊的嵌套聚合：
-- 按 `specifications.name` 分组（如"color"、"size"）
-- 每个 `name` 下按 `specifications.value` 聚合（如"white"、"black"）
-
-返回格式：
-```json
-{
-  "field": "specifications.color",
-  "label": "color",
-  "type": "terms",
-  "values": [
-    {"value": "white", "count": 50},
-    {"value": "black", "count": 30}
-  ]
-}
-```
-
-## 返回字段映射
-
-后端根据请求的 `language` 参数（`zh` 或 `en`）自动选择对应的中英文字段：
-
-- `language="zh"`: 优先返回 `*_zh` 字段，如果为空则回退到 `*_en` 字段
-- `language="en"`: 优先返回 `*_en` 字段，如果为空则回退到 `*_zh` 字段
-
-映射规则：
-- `title.zh/en` → `title`
-- `brief.zh/en` → `brief`
-- `description.zh/en` → `description`
-- `vendor.zh/en` → `vendor`
-- `category_path.zh/en` → `category_path`
-- `category_name_text.zh/en` → `category_name`
-
-## 配置修改
-
-### 修改索引结构
-
-编辑 `mappings/search_products.json`，然后：
-1. 重建租户索引结构: `./scripts/create_tenant_index.sh <tenant_id>`
-2. 重新导入数据: `POST /indexer/reindex`
-
-### 修改查询配置
-
-编辑 `search/query_config.py`:
-- `DEFAULT_MATCH_FIELDS`: 文本召回字段列表
-- `FUNCTION_SCORE_CONFIG`: Function score 配置
-- `DEFAULT_FACETS`: 默认分面字段
-
-### 修改返回字段
-
-编辑 `search/query_config.py` 中的 `SOURCE_FIELDS` 列表。
-
-## 注意事项
-
-1. **无需配置文件**: 所有配置都是硬编码的，不需要为每个租户创建配置文件
-2. **统一结构**: 所有租户共享相同的索引结构和查询逻辑
-3. **多租户隔离**: 所有查询必须包含 `tenant_id` 过滤条件
-4. **向量字段**: `title_embedding` 和 `image_embedding` 仅用于搜索，不会返回给前端
-
-## 相关文档
-
-- `索引字段说明v2.md` - 详细的字段说明
-- `搜索API对接指南.md` - API使用说明
-- `mappings/search_products.json` - 索引 mapping 定义
+保留此文件仅用于兼容历史链接。
@@ -30,7 +30,7 @@ def cmd_serve(args):
     os.environ['ES_HOST'] = args.es_host
     print("Starting API service (multi-tenant)...")
-    print(f"  Host: {args.host}:{args.port} (search + indexer routes)")
+    print(f"  Host: {args.host}:{args.port} (search + admin routes)")
     print(f"  Elasticsearch: {args.es_host}")
     uvicorn.run(