From bc54124ca4289b685b811b92914875d62082a345 Mon Sep 17 00:00:00 2001 From: tangwang Date: Sun, 8 Mar 2026 16:26:56 +0800 Subject: [PATCH] docs --- docs/PROVIDER_ARCHITECTURE.md | 65 +++++------------------------------------------------------------ docs/QUICKSTART.md | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------ docs/Usage-Guide.md | 18 ++++++++++-------- docs/基础配置指南.md | 168 +++++++----------------------------------------------------------------------------------------------------------------------------------------------------------------- main.py | 2 +- 5 files changed, 311 insertions(+), 266 deletions(-) diff --git a/docs/PROVIDER_ARCHITECTURE.md b/docs/PROVIDER_ARCHITECTURE.md index 7752ed3..ebc9054 100644 --- a/docs/PROVIDER_ARCHITECTURE.md +++ b/docs/PROVIDER_ARCHITECTURE.md @@ -1,63 +1,8 @@ -# 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/.py` 中实现新 provider 类 -2. 在 `create_*_provider()` 中注册分支 -3. 在 `config/config.yaml` 的 `services..providers` 中补充参数 +保留此文件仅用于兼容历史链接，避免重复维护导致内容漂移。 diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 1e4e594..a81dc8d 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -1,39 +1,83 @@ -# 开发者快速上手 +# 开发与配置指南 -新人入口文档：环境、服务、模块、请求示例一页搞定。 +新人入口：环境、服务、模块、请求示例、基础配置、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 ` → 重新导入 | +| 搜索域/权重/排序/重排 | 修改 `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/.py` 实现 provider 类 +2. 在 `create_*_provider()` 注册 +3. 在 `config/config.yaml` 的 `services..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.` + +### 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` | 重排服务说明 | diff --git a/docs/Usage-Guide.md b/docs/Usage-Guide.md index 6e1d8a1..8b985e4 100644 --- a/docs/Usage-Guide.md +++ b/docs/Usage-Guide.md @@ -1,6 +1,8 @@ -# 使用指南 - 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 diff --git a/docs/基础配置指南.md b/docs/基础配置指南.md index 979569e..84907b5 100644 --- a/docs/基础配置指南.md +++ b/docs/基础配置指南.md @@ -1,166 +1,12 @@ -# 基础配置指南 +# 基础配置指南（已并入） -## 概述 +本文档内容已并入 `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 ` -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 定义 +保留此文件仅用于兼容历史链接。 diff --git a/main.py b/main.py index a1a65a6..8a8c936 100755 --- a/main.py +++ b/main.py @@ -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( -- libgit2 0.21.2