ai-saas / saas-search

issue.md 27.4 KB

项目 TODO 清单

CLAUDE.md需要更新

核心搜索功能优化

2.1 意图识别模块

增加款式意图识别模块
意图类型：颜色，尺码（目前只需要支持这两种）
意图召回层：每种意图，有一个召回词集合对query（包括原始query、各种翻译query 都做匹配）
以颜色意图为例：有一个词表，每一行都逗号分割，互为同义词，行内第一个为标准化词 query匹配了其中任何一个词，都认为，具有颜色意图匹配规则：用细粒度、粗粒度分词，看是否有在词表中的。原始query分词、和每种翻译的分词，都要用。
意图判断：暂时留空，直接返回true。目前没有模型，即只要召回了（词表匹配了），即认为有该维度款式需求。（以后考虑建设fasttext/bert系列多分类模型）
意图使用：我们第一阶段，使用参与ES提权。
一、参与ES提权
二、参与reranker
如果有：先做sku筛选，然后把最优的拼接到名称中，参与reranker。
现在在reranker、分页之后、做填充的时候，已经有做sku的筛选。需要优化：现在是，先做包含的判断，找到第一个 option_value被query包含的，则直接认为匹配。改为
1. 第一轮：遍历完，如果有且仅有一个被query包含，那么认为匹配。
2. 第二轮：如果有多个符合（被query包含），跳到3。如果没有，对每个词都走泛化词表进行匹配。
3. 第三轮：如果有多个，那么对这多个，走embedding相关性取最高的。如果一个也没有，则对所有的走embedding相关性取最高的这个sku筛选也需要提取为一个独立的模块。
另外：现在是reranker、分页之后做sku筛选，要改为：
1. 有款式意图的时候，才做sku筛选
2. sku筛选的时机，改为在reranker之前，对所有内容做sku筛选，然后
3. 从仅 option1 扩展到多个维度，识别的意图，包含意图的维度名（color）和维度名的泛化词list（color、颜色、colour、olors、、、、），遍历option1_name,option2_name,option3_name，看哪个能匹配上意图的维度名list，哪个匹配上了，则在这个维度筛选。
4. Rerank doc （有款式意图的时候）要带上属性后缀，拼接到title后面。在调用 run_rerank 前，对每条 hit 生成「用于重排的 doc 文本」（标题 + 可选后缀）
5. TODO ：还有一个问题。目前，sku只返回一个维度（店铺主维度。默认应该是option1，不是所有维度的sku信息都返回的。所以，如果有款式意图，但是主维度是颜色，那么拿不到全的款式sku）
筛选SKU：先只筛选第一个维度，但考虑到用户搜索词可能带了尺码，所以第二、三个维度也要考虑

当前项目功能已经较多，但是有清晰的框架，请务必基于现有框架进行改造，不要进行补丁式的修改，避免代码逻辑分叉。请一步一步来，先设计意图识别模块，仔细思考需求，意图识别模块需要提供哪些内容，用于返回数据接口的定义，深度思考，定义一个合理的接口后，再给出合理的模块设计。

2.3 向量检索与融合

把knn跟文本相关性的融合方式修改为 "rank": {"rrf": {} }需要licence，可以帮我修改源码支持吗？

knn_boost: 2.0

{ "query": { ...全文检索... }, "knn": { ...向量检索... }, "rank": { "rrf": {} } }

融合打分（已完成，2026-03）

以下已经完成：

fuse_scores_and_resort 已改为乘法融合，并通过 matched_queries 提取：
- base_query
- base_query_trans_*
- fallback_original_query_*
- knn_query
文本相关性大分不再依赖 phrase_query / keywords_query，这两类查询已清理。
当前融合策略：
- text_score = primary(weighted_source, weighted_translation, weighted_fallback) + 0.25 * support
- fused_score = (rerank_score + 0.00001) * (text_score + 0.1) ** 0.35 * (knn_score + 0.6) ** 0.2
track_scores 与 include_named_queries_score 已接入，调试字段与评估方法已同步到：
- docs/相关性检索优化说明.md
- docs/搜索API对接指南-01-搜索接口.md（分册；原单文件已拆分）
- docs/Usage-Guide.md
未完成的：（归一化、次序融合？还乘法公式？） RRF：先把多路召回稳妥融合 linear + minmax：让你能精调 knn 和文本的权重 reranker：对前面召回出来的 top-k 再做“最后一刀”

2.4 文本相关性优化

调研： Princeton WordNet — 英文同义词底库 Shopify Product Taxonomy — 电商品类标准 Querqy — 电商搜索规则框架 gensimpson/elasticsearch-synonyms — ES 同义词规则落地
tags字段使用的优化：现在是keyword，在搜索中，不太好使用（目前主要用于suggest）。可以考虑也拆分多语言，配合analyzer使用（和qanchors一样）
是否需要：当「源语言不在 index_languages」且「某些目标语言的翻译缺失」时，ES 里会额外加一层用「原始 query 字符串」去撞缺失语种字段
检索相关性优化：原始搜索词和翻译的词，都需要有对应的主干分析这个主干可以根据词性简单提取名词即可在搜索时，原始词和主干都成对地出现，原始词和trunk_keywords一起组成一个或查询。有一种方案是把原始词和主干词拼接起来。但是bm25要调tf系数。

2.5 图片相关性与向量字段调整

"image_embedding": { "type": "nested", "properties": { "vector": { "type": "dense_vector", "dims": 1024, "index": true, "similarity": "dot_product", "element_type": "bfloat16" }, "url": { "type": "text" } } }, 去掉 image_embedding_512 image_embedding改为，一个spu有多个sku向量，每个向量内部properties：除了vector url还应该包括，该图片是对应哪些sku "image_embedding": { "type": "nested", "properties": { "vector": { "type": "dense_vector", "dims": 1024, "index": true, "similarity": "dot_product", "element_type": "bfloat16" }, "url": { "type": "text" } } },
引入图片的相关性：图片的向量最好做SKU维度，用 SPU 维度还是 SKU 维度？
1. SKU维度（主款式，option1维度），如果用户搜索“蓝色 T恤”，这种图片相关性会比较有价值。
2. 我不考虑颜色的差异，其余的款式一般是大小之类的。这些图片，embedding细分到 SKU 维度，可能价值不大，性价比偏低
属性的筛选：训练一个bert/transformer多分类模型，分类：颜色、尺寸、材质等等。但是要注意一些属性的值不规范、非常多，要考虑是不是做规范化，如何规范化。

2.6 无结果重查与翻译缺失处理

无结果重查稀有语言，翻译可能超时（因为zh-en互译之外的翻译耗时更长）

模型与推理服务优化

3.1 大模型API与本地部署

外部需求：
1. 对推理能力要求很低、对耗时要求很高的大模型API（或者本地部署一个7b Q4量化的大模型），prompt大概30-50个token，首token响应要求500ms以内
2. ES支持reranker pipline？
本地部署一个7b Q4量化的大模型

3.2 Embedding服务优化

先阅读文本embedding相关的代码： @embeddings/README.md @embeddings/server.py @docs/搜索API对接指南-07-微服务接口（Embedding-Reranker-Translation）.md @embeddings/text_encoder.py 目前有TEXT_MAX_INFLIGHT / IMAGE_MAX_INFLIGHT 准入限制，超限返回过载状态码。
文本embedding服务，要支持 priority 查询参数，priority > 0：不计入上述 inflight、不会因准入被拒绝（图片embedding不需要支持，因为只有离线需要用到图片embedding） priority == 0（默认，适合做索引之类的离线任务）：仍走原有 TEXT_MAX_INFLIGHT / IMAGE_MAX_INFLIGHT 准入；超限返回过载状态码。 priority > 0（或者==1）（适合在线请求）：不会因准入被拒绝，但是仍然需要占用inflight，这样保证在线请求不被限制，并且在线请求很多的时候可以拒绝掉离线的请求。
除了限制规则的修改，更进一步的，也需要保证这种请求是优先处理的（priority=1的相比=0的更优先被处理）。关于技术方案，有Worker + 双队列、PriorityMutex等等，除此之外，也请你思考合适的方案。成熟稳定、不带来复杂度、性能、稳定性方面的副作用，是最重要的。请先了解代码、需求，深度思考解决方案
向量的缓存

3.3 Reranker优化

多reranker：改 reranker 服务，一次请求返回多路分服务启动时加载多个 backend（或按请求懒加载），/rerank 响应扩展为例如 scores: [...]（兼容主后端）+ scores_by_backend: { "bge": [...], "qwen3_vllm": [...] }。搜索侧解析多路分，再融合或只透传 debug。优点：搜索侧仍只调一个 URL。缺点：单进程多大模型显存压力很大；
融合层要注意的一点 fuse_scores_and_resort 目前只消费一条 rerank_scores 序列，并写入 rerank_score 多 backend 之后需要rerankscores 都参与融合
必要性：见 qwen3-reranker和bge-m3的严重badcase 不一定是要多reranker的方式，但是一定会需要解决方案。
reranker 补充：nvidia/llama-nemotron-rerank-1b-v2 https://huggingface.co/nvidia/llama-nemotron-rerank-1b-v2 后端推理也建议使用vLLM 注意搜索相关资料，挖掘我的特斯拉 T4 GPU 的性能，充分挖掘性能你有充足的自由度进行实验 encoder架构。比较新。性能更好。亚马逊电商搜索数据集比qwen-reranker-4b更好。支持vLLM。
Qwen3-Reranker-4B-GGUF https://modelscope.cn/models/dengcao/Qwen3-Reranker-4B-GGUF/summary
1. 要确定选择哪种量化方式
2. 确定提示词
qwen3-embedding、qwen3-reranker （done）选一个推理引擎，相比于我自己直接调 sentence-transformers，主要是多进程和负载均衡、连续批处理，比较有用当前结论：embedding 场景优先 TEI；vLLM 更偏向生成式与 rerank 场景。
rerank 性能优化

3.4 翻译模型优化

翻译，增加facebook/nllb-200-distilled-600M https://blog.csdn.net/qq_42746084/article/details/154947534 https://huggingface.co/facebook/nllb-200-distilled-600M
店铺的语言：英语能占到80%，所以专门增加一个en-zh的 https://huggingface.co/Helsinki-NLP/opus-mt-zh-en https://huggingface.co/Helsinki-NLP/opus-mt-en-zh
opus-mt-zh-en

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM model_name = "./models/opus-mt-en-zh" tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForSeq2SeqLM.from_pretrained(model_name) data = 'test' encoded = tokenizer([data], return_tensors="pt") translation = model.generate(**encoded) result = tokenizer.batch_decode(translation, skip_special_tokens=True)[0] print(result)

nllb-200-distilled-600M性能优化已完成（2026-03）
- CTranslate2 迁移 + float16 转换
- 扩展压测报告：perf_reports/20260318/translation_local_models_ct2/README.md
- T4 聚焦调优报告：perf_reports/20260318/translation_local_models_ct2_focus/README.md
- NLLB T4 商品标题专项报告：perf_reports/20260318/nllb_t4_product_names_ct2/README.md
- 当前结论：
- NLLB 在线默认推荐：ct2_inter_threads=4 + ct2_max_queued_batches=32 + ct2_batch_type=examples + ct2_decoding_length_mode=source(+8,min=32)
- opus-mt-zh-en 维持保守默认更稳
- opus-mt-en-zh 如追求离线吞吐可继续做单独 profile
请搜索nllb-200-distilled-600M这类seq2seq、transformer架构的模型，有哪些性能优化方案，提高线上翻译服务的吞吐量、降低耗时，搜索相关的在线推理服务方案，找到高性能的服务化方法
查看翻译的缓存情况

3.5 其他模型优化

cnclip的性能优化

性能优化与超时配置

4.1 超时配置

Query 分析阶段等待翻译/embedding 的硬超时配置文件位置：config/config.yaml 配置项：query_config.async_wait_timeout_ms: 80 代码生效点：query/query_parser.py 使用该值换算成秒传给 wait(...)

Embedding HTTP 调用超时（Text/Image）不再使用任何环境变量覆盖（之前提到的 EMBEDDING_HTTP_TIMEOUT_SEC 已不采用）配置文件位置：config/config.yaml 配置项：services.embedding.providers.http.timeout_sec（已在 YAML 里补了示例默认 60）代码生效点： embeddings/text_encoder.py：requests.post(..., timeout=self.timeout_sec) embeddings/image_encoder.py：requests.post(..., timeout=self.timeout_sec)

4.2 生成式服务优化（Partial Mode）

product_enrich : Partial Mode : done https://help.aliyun.com/zh/model-studio/partial-mode?spm=a2c4g.11186623.help-menu-2400256.d_0_3_0_7.74a630119Ct6zR 需在messages 数组中将最后一条消息的 role 设置为 assistant，并在其 content 中提供前缀，在此消息中设置参数 "partial": true。messages格式如下： [ { "role": "user", "content": "请补全这个斐波那契函数，勿添加其它内容" }, { "role": "assistant", "content": "def calculate_fibonacci(n):\n if n

Elasticsearch相关

es需要licence的两个功能，如果费用低，开通下licence，或者改es源码定制开发下，支持 rank.rrf，reranker

{ "query": { ...全文检索... }, "knn": { ...向量检索... }, "rank": { "rrf": {} } }

配置体系重构 Referring to @docs/config-system-review-and-redesign.md , most of the modifications have been completed. Could you conduct a review to check what else needs improvement in the configuration documentation system? Are there any outstanding issues?

一、仍然存在大量通过环境变量获取配置的地方 SERVICE_KIND = (os.getenv("EMBEDDING_SERVICE_KIND", "all") or "all").strip().lower() if SERVICE_KIND not in {"all", "text", "image"}: raise RuntimeError( f"Invalid EMBEDDING_SERVICE_KIND={SERVICE_KIND!r}; expected all, text, or image" ) TEXT_ENABLED_BY_ENV = os.getenv("EMBEDDINGENABLE_TEXTMODEL", "true").lower() in ("1", "true", "yes") IMAGE_ENABLED_BY_ENV = os.getenv("EMBEDDING_ENABLE_IMAGE_MODEL", "true").lower() in ("1", "true", "yes") open_text_model = _TEXT_ENABLEDBY_ENV and SERVICE_KIND in {"all", "text"} open_image_model = _IMAGEENABLED_BY_ENV and _SERVICE_KIND in {"all", "image"}

text_encode_lock = threading.Lock() _imageencode_lock = threading.Lock()

TEXT_MICROBATCH_WINDOW_SEC = max( 0.0, float(os.getenv("TEXT_MICROBATCH_WINDOW_MS", "4")) / 1000.0 ) TEXT_REQUEST_TIMEOUT_SEC = max( 1.0, float(os.getenv("TEXT_REQUEST_TIMEOUT_SEC", "30")) ) TEXT_MAX_INFLIGHT = max(1, int(os.getenv("TEXT_MAX_INFLIGHT", "32"))) _IMAGEMAX_INFLIGHT = max(1, int(os.getenv("IMAGEMAX_INFLIGHT", "1"))) OVERLOAD_STATUS_CODE = int(os.getenv("EMBEDDING_OVERLOAD_STATUS_CODE", "503")) _LOGPREVIEW_COUNT = max(1, int(os.getenv("EMBEDDINGLOG_PREVIEW_COUNT", "3"))) LOG_TEXT_PREVIEW_CHARS = max(32, int(os.getenv("EMBEDDING_LOG_TEXT_PREVIEW_CHARS", "120"))) LOG_IMAGE_PREVIEW_CHARS = max(32, int(os.getenv("EMBEDDINGLOG_IMAGE_PREVIEW_CHARS", "180"))) _VECTORPREVIEW_DIMS = max(1, int(os.getenv("EMBEDDING_VECTOR_PREVIEW_DIMS", "6"))) CACHE_PREFIX = str(REDIS_CONFIG.get("embedding_cacheprefix", "embedding")).strip() or "embedding"

还有这些写死的地址 @embedding/config.py

self.TEI_BASE_URL = str(text_backend.get("base_url") or "http://127.0.0.1:8080") self.TEI_TIMEOUT_SEC = int(text_backend.get("timeout_sec", 60))

self.USE_CLIP_AS_SERVICE = services.image_backend == "clip_as_service" self.CLIP_AS_SERVICE_SERVER = str(image_backend.get("server") or "grpc://127.0.0.1:51000")

看起来似乎并没有完全遵循这些原则？

重新设计的设计原则重新设计应遵循以下规则。

4.1 单一逻辑配置系统可以有多个文件，但不能有多个职责重叠的加载器。必须有一个加载器管道，能够生成一个类型化的 AppConfig 对象。

4.2 配置文件负责声明，解析代码负责解释，环境变量负责运行时注入职责应明确如下：配置文件声明非敏感的目标行为和可部署的非敏感设置解析逻辑加载、合并、验证、规范化并暴露类型化的配置绝不发明隐藏的业务行为环境变量承载密钥和少量运行时/进程相关的值不随意地重新定义业务行为

4.3 整个系统采用单一的优先级规则除非明确豁免，否则每个配置类别都应遵循相同的合并模型。

4.4 业务行为不得有静默的隐式后备在启动时，如果必需的配置缺失或无效，应快速失败。不要静默地回退到诸如硬编码语言列表之类的遗留行为。

4.5 有效配置必须可观测每个服务都应能够展示：配置版本或哈希值加载的源文件环境名称经过清理的有效配置

推荐的目标设计

5.1 边界模型使用三个清晰的层级。层级 1：代码仓库管理的静态配置目的：搜索行为租户行为提供商/后端注册表非敏感的服务拓扑默认值功能开关示例：字段权重查询策略重排序融合参数租户语言方案翻译能力注册表嵌入后端选择默认值

层级 2：特定环境的层叠配置目的：按环境区分的非敏感差异按环境区分的服务端点按环境区分的资源大小默认值开发/测试/生产环境的运维差异示例：本地嵌入 URL 与生产环境嵌入 URL 开发环境重排序后端与生产环境重排序后端本地开发环境中较低的并发度

层级 3：环境变量目的：密钥绑定主机/端口外部基础设施凭证容器编排器的最后一步注入示例： ES_HOST, ES_USERNAME, ES_PASSWORD DB_HOST, DB_USERNAME, DB_PASSWORD REDIS_HOST, REDIS_PASSWORD DASHSCOPE_API_KEY, DEEPL_AUTH_KEY API_HOST, API_PORT, INDEXER_PORT, TRANSLATION_PORT 规则：环境变量不应成为选择业务行为（如翻译模型、嵌入后端或租户语言策略）的常规途径如果允许对非敏感字段进行环境变量覆盖，则必须将其明确列出并记录为运维覆盖手段，而非隐藏的约定

5.2 统一的优先级推荐的优先级顺序：代码中的模式（schema）默认值 config/base.yaml config/environments/.yaml 来自 config/tenants/ 的租户层叠配置针对明确允许的运行时键的环境变量仅适用于当前进程的命令行标志重要规则：只能有一个模块实现此合并逻辑任何业务模块不得直接调用 os.getenv() 来获取配置

二、cursor（composer2）帮我审查的

配置文档系统审查

这是对配置文档系统的简要审查，对照 <code>docs/config-system-review-and-redesign.md</code> 和当前代码库进行。

实现已匹配的部分

代码库已朝着重新设计的目标迈进了很大一步：

单一类型化根节点：AppConfig 位于 <code>config/schema.py</code>，通过 <code>config/loader.py</code> 和 <code>get_app_config()</code> 加载。
精简的 services_config：<code>config/services_config.py</code> 委托给 get_app_config()（解决了服务层的发现 A）。
租户目录：<code>config/tenant_config_loader.py</code> 使用 get_app_config().tenants。
重写资产路径：config/dictionaries/query_rewrite.dict 已存在（解决了发现 E 中的文件名不匹配问题）。
可观测性：<code>GET /admin/config</code> 返回经过脱敏处理的有效配置树；<code>GET /admin/config/meta</code> 暴露环境信息、config_hash、loaded_files、deprecated_keys（涵盖了 §5.10 的意图；文档中提议的是 /admin/config/effective，但实际实现位于 /admin/config）。

因此，"单一加载器 + 有效配置可见性" 的故事在代码中已基本实现；文档尚未完全跟上。

文档问题（影响最大）

1. 管理 API 文档中关于 `/admin/config` 的描述错误

<code>docs/搜索API对接指南-06-管理接口（Admin）.md</code>（原单文件 搜索API对接指南.md 已拆分为分册）仍将 /admin/config 描述为按租户的 JSON（包含 tenant_id、es_index_name、supported_languages 等字段）。实际实现返回的是 AppConfig.sanitized_dict()（完整的应用配置，敏感信息已脱敏），而不是租户摘要字段。

这些指南中还缺少： GET /admin/config/meta。

健康检查：拆分指南中的示例包含了 <code>HealthResponse</code> 中不存在的字段（只有 status 和 elasticsearch）。

对于任何仅根据文档进行 API 集成的人来说，这是最明显的"未解决问题"。

2. 面向开发者的指南仍将 `services_config` 作为"配置解析器"的核心

<code>docs/DEVELOPER_GUIDE.md</code> §5.2 仍说搜索配置由 ConfigLoader 加载，服务由 config/services_config "解析"。§6.2 仍将 config/services_config.py 列为主要的"解析入口"。<code>docs/QUICKSTART.md</code> §3.1 仍说"配置解析：config/services_config.py"。

文档中准确的说法应该是：规范入口是 config/loader.py + get_app_config()；<code>config/config_loader.py</code> 中的 ConfigLoader 包装了统一加载器；services_config 是现有调用点的兼容性外观。

3. 重新设计文档本身不是"活的"状态文档

<code>docs/config-system-review-and-redesign.md</code> 读起来仍是纯粹的问题陈述 + 目标，没有简短的"已实现 vs 剩余"部分。这很容易让人假设什么都没做，或者重复工作。添加一个小附录（或一页 config/README.md —— 见下文）可以解决这个问题。

4. 缺少 `config/README.md`（§5.3 中推荐）

仍然没有专门的 config/README.md 来描述：加载器入口点、高级优先级、字典存放位置、指向 /admin/config + /admin/config/meta 的链接，以及重新设计文档的链接。这是重新设计中明确的交付物，可以锚定"文档系统"。

5. 轻微的文档整洁问题

<code>docs/QUICKSTART.md</code> §1.9 环境变量项目后的行有一个多余字符：---·（可能是打字错误）。
<code>docs/DEVELOPER_GUIDE.md</code> §10 文档索引没有列出 config-system-review-and-redesign.md 或未来的 config/README.md。

重新设计目标与当前代码之间的差距（文档不应声称"已完成"）

这些影响文档的诚实度：

主题	状态
`config dump` CLI（§5.10）	`main.py` 中不存在；运维人员依赖 HTTP 或临时脚本。
隐藏的 `["en", "zh"]` 回退（阶段 3 / 发现 D）	仍在 <code>indexer/document_transformer.py</code>、<code>suggestion/builder.py</code> 等中使用。
加载器外的 `os.getenv`（规则 1–2）	仍在例如 <code>embeddings/server.py</code>、<code>reranker/server.py</code>、<code>api/app.py</code> 中使用 —— 文档声称"仅加载器"将是夸大其词。
拆分 `base.yaml` / `environments/` / `tenants/*.yaml`（阶段 5）	未采用；仍是单一的 <code>config/config.yaml</code>。
遗留租户标志（阶段 6 / 发现 H）	<code>indexer/README.md</code> 仍描述上游 MySQL 的 `translate_to_en` / `translate_to_zh`（这可能作为上游模式文档保留；需与 Python `tenant_config` 模型区分开来）。

GITLAB

ai-saas / saas-search

配置文档系统审查

实现已匹配的部分

文档问题（影响最大）

1. 管理 API 文档中关于 `/admin/config` 的描述错误

2. 面向开发者的指南仍将 `services_config` 作为"配置解析器"的核心

3. 重新设计文档本身不是"活的"状态文档

4. 缺少 `config/README.md`（§5.3 中推荐）

5. 轻微的文档整洁问题

重新设计目标与当前代码之间的差距（文档不应声称"已完成"）

推荐的后续步骤（仅文档，按优先级排序）

配置文档系统审查

实现已匹配的部分

文档问题（影响最大）

1. 管理 API 文档中关于 /admin/config 的描述错误

2. 面向开发者的指南仍将 services_config 作为"配置解析器"的核心

3. 重新设计文档本身不是"活的"状态文档

4. 缺少 config/README.md（§5.3 中推荐）

5. 轻微的文档整洁问题

重新设计目标与当前代码之间的差距（文档不应声称"已完成"）

推荐的后续步骤（仅文档，按优先级排序）

1. 管理 API 文档中关于 `/admin/config` 的描述错误

2. 面向开发者的指南仍将 `services_config` 作为"配置解析器"的核心

4. 缺少 `config/README.md`（§5.3 中推荐）