diff --git a/app.py b/app.py index 81df70d..0640246 100644 --- a/app.py +++ b/app.py @@ -321,7 +321,7 @@ def display_product_card_from_item(product: ProductItem) -> None: if product.price is not None: st.caption(f"¥{product.price:.2f}") - label_style = "⭐" if product.match_label == "完美匹配" else "✦" + label_style = "⭐" if product.match_label == "Highly Relevant" else "✦" st.caption(f"{label_style} {product.match_label}") @@ -330,25 +330,25 @@ def render_search_result_block(result: SearchResult) -> None: Render a full search result block in place of a [SEARCH_REF:xxx] token. Shows: - - A styled header with query text + quality verdict + match counts - - A grid of product cards (perfect matches first, then partial; max 6) + - A styled header with query + match counts + quality_summary (if any) + - A grid of product cards (Highly Relevant first, then Partially Relevant; max 6) """ - verdict_icon = {"优质": "✅", "一般": "〰️", "较差": "⚠️"}.get(result.quality_verdict, "🔍") + summary_line = f'  · {result.quality_summary}' if result.quality_summary else '' header_html = ( f'
' f'' f'🔍 {result.query}' - f'  {verdict_icon} {result.quality_verdict}' - f' · 完美匹配 {result.perfect_count} 件' - f' · 相关 {result.partial_count} 件' + f' · Highly Relevant {result.perfect_count} 件' + f' · Partially Relevant {result.partial_count} 件' + f'{summary_line}' f'
' ) st.markdown(header_html, unsafe_allow_html=True) # Perfect matches first, fall back to partials if none - perfect = [p for p in result.products if p.match_label == "完美匹配"] - partial = [p for p in result.products if p.match_label == "部分匹配"] + perfect = [p for p in result.products if p.match_label == "Highly Relevant"] + partial = [p for p in result.products if p.match_label == "Partially Relevant"] to_show = (perfect + partial)[:6] if perfect else partial[:6] if not to_show: diff --git a/app/agents/shopping_agent.py b/app/agents/shopping_agent.py index ce3b119..033e62c 100644 --- a/app/agents/shopping_agent.py +++ b/app/agents/shopping_agent.py @@ -33,26 +33,21 @@ logger = logging.getLogger(__name__) # 1. Guides multi-query search planning with explicit evaluate-and-decide loop # 2. Forbids re-listing product details in the final response # 3. Mandates [SEARCH_REF:xxx] inline citation as the only product presentation mechanism -SYSTEM_PROMPT = """角色定义 -你是一名专业的服装电商导购，是一个善于倾听、主动引导、懂得搭配的“时尚顾问”，通过有温度的对话，给用户提供有价值的信息，包括需求引导、方案推荐、搜索结果推荐，最终促成满意的购物决策或转化行为。 - -一些原则： -1. 你是一个真人导购，是一个贴心、专业的销售，保持灵活，根据上下文，基于常识灵活的切换策略，在合适的上下文询问合适的问题、给出有价值的方案和搜索结果的呈现。 -2. 商品搜索结果推荐与信息收集： - 1. 根据上下文、用户诉求，灵活的切换侧重点，何时需要进行搜索、何时要引导客户完善需求，你需要站在用户角度进行思考。比如已经有较为清晰的意图，则以搜索、方案推荐为主，有必要的时候，思考该方向下重要的决策因素，进行提议和问题收集，让用户既得到相关信息、又得到下一步的方向引导、同时也有机会修正或者细化诉求。如果存在重大的需求方向缺口，主动通过1-2个关键问题进行引导，并提供初步方向。 - 2. 适时的提供有价值的信息，如商品推荐、穿搭建议、趋势信息，在推荐方向上有需求缺口、需要明确的重要信息时，要适时的做“信息收集”，引导式的帮助用户更清晰的呈现需求、提高商品发现的效率，形成“提供-反馈”的良性循环。 - 3. 对于复杂需求时，要能基于上下文，将导购任务进行合理拆解。 -3. 引导或者收集需求时，需要站在用户立场，比如询问用户期待的效果或感觉、使用的场合、偏好的风格等用户立场需，而不是询问具体的款式或参数，你需要将用户立场的需求理解/翻译/转化为具体的搜索计划，最后筛选产品、结合需求+结果特性组织推荐理由、呈现方案。 -4. 如何使用search_products：在需要搜索商品的时候，可以将需求分解为 2-4 个搜索查询，每个 query 聚焦一个明确的商品子类或搜索角度。每次调用 search_products 后，工具会返回以下内容，你需要决策是否要调整搜索策略，比如结果质量太差，可能需要调整搜索词、或者加大试探的query数量（不要超过3-5个）。可以进行多轮搜索，但是要适时的总结和反馈信息避免用户等待过长时间： - - 各层级数量：完美匹配 / 部分匹配 / 不相关 的条数 - - 整体质量判断：优质 / 一般 / 较差 - - 简短质量说明 - - 结果引用标识：[SEARCH_REF:xxx] -5. 撰写最终回复的时候，使用 [SEARCH_REF:xxx] 内联引用 - 1. 用自然流畅的语言组织回复，将 [SEARCH_REF:xxx] 嵌入叙述中 - 2. 系统会自动在 [SEARCH_REF:xxx] 位置渲染对应的商品卡片列表 - 3. 禁止在回复文本中列出商品名称、ID、价格、分类、规格等字段 - 4. 禁止用编号列表逐条复述搜索结果中的商品 +SYSTEM_PROMPT = """ 角色定义 + 你是我们店铺的一名专业的电商导购，是一个善于倾听、主动引导、懂得搭配的“时尚顾问”，通过有温度的对话，给用户提供有价值的信息，包括需求引导、方案推荐、搜索结果推荐，最终促成满意的购物决策或转化行为。 + 作为我们店铺的一名专业的销售，除了本店铺的商品的推荐，你可以给用户提供有帮助的信息，但是不要虚构商品、提供本商店搜索结果以外的商品。 + + 一些原则： + 1. 价值提供与信息收集的原则： + 1. 优先价值提供：适时的提供有价值的信息，如商品推荐、穿搭建议、趋势信息，在推荐方向上有需求缺口、需要明确的重要信息时，要适时的做“信息收集”，引导式的澄清需求、提高商品发现的效率，形成“提供-反馈”的良性循环。 + 2. 缺口大（比如品类或者使用人群都不能确定）→ 给出方案推荐 + 1-2个关键问题让用户选择；缺口小→直接检索+方案呈现，根据情况，可以考虑该方向下重要的决策因素，进行提议和问题收集，让用户既得到相关信息、又得到下一步的方向引导、同时也有机会修正或者细化诉求。 + 3. 选项驱动式澄清：推荐几个清晰的方向，呈现方案或商品搜索结果，再做澄清 + 4. 单轮对话最好只提一个问题，最多两个，禁止多问题堆叠。 + 5. 站在用户立场思考：比如询问用户期待的效果或感觉、使用的场合、想解决的问题，而不是询问具体的款式、参数，你需要将用户表达的需求翻译为具体可检索的商品特征（版型、材质、设计元素、风格标签等），并据此筛选商品、组织推荐逻辑。 + 2. 如何使用make_search_products_tool： + 1. 可以生成多个query进行搜索：在需要搜索商品的时候，可以将需求分解为 2-4 个搜索查询，每个 query 聚焦一个明确的商品子类或搜索角度。 + 2. 可以根据搜索结果调整搜索策略：每次调用 search_products 后，工具会返回搜索结果的相关性的判断、以及搜索结果的topN的title，你需要决策是否要调整搜索策略，比如结果质量太差，可能需要调整搜索词、或者加大试探的query数量（不要超过3-5个）。 + 3. 使用 [SEARCH_REF:xxx] 内联引用搜索结果：搜索工具会返回一个结果引用标识[SEARCH_REF:xxx]，撰写最终答复的时候可以直接引用将 [SEARCH_REF:xxx] ，系统会自动在该位置渲染对应的商品卡片列表，无需复述搜索结果。 """ diff --git a/app/search_registry.py b/app/search_registry.py index 861be0e..48ffc3d 100644 --- a/app/search_registry.py +++ b/app/search_registry.py @@ -27,8 +27,8 @@ class ProductItem: vendor: Optional[str] = None image_url: Optional[str] = None relevance_score: Optional[float] = None - # LLM-assigned label: "完美匹配" | "部分匹配" | "不相关" - match_label: str = "部分匹配" + # LLM-assigned label: "Highly Relevant" | "Partially Relevant" | "Not Relevant" + match_label: str = "Partially Relevant" tags: list = field(default_factory=list) specifications: list = field(default_factory=list) @@ -40,7 +40,7 @@ class SearchResult: Identified by ref_id (e.g. 'sr_3f9a1b2c'). Stores the query, LLM quality assessment, and the curated product list - (only "完美匹配" and "部分匹配" items — "不相关" are discarded). + (only "Highly Relevant" and "Partially Relevant" items — "Not Relevant" are discarded). """ ref_id: str @@ -55,9 +55,8 @@ class SearchResult: partial_count: int irrelevant_count: int - # LLM overall quality verdict - quality_verdict: str # "优质" | "一般" | "较差" - quality_summary: str # one-sentence LLM explanation + # LLM-written short summary: what the results mainly contain, whether they meet intent, match degree + quality_summary: str # Curated product list (perfect + partial only) products: list # list[ProductItem] diff --git a/app/tools/search_tools.py b/app/tools/search_tools.py index 4c364e2..eae9878 100644 --- a/app/tools/search_tools.py +++ b/app/tools/search_tools.py @@ -1,16 +1,9 @@ """ Search Tools for Product Discovery -Key design: -- search_products is created via a factory (make_search_products_tool) that - closes over (session_id, registry), so each agent session has its own tool - instance pointing to the shared registry. -- After calling the search API, an LLM quality-assessment step labels every - result as 完美匹配 / 部分匹配 / 不相关 and produces an overall verdict. -- The curated product list is stored in the registry under a unique ref_id. -- The tool returns ONLY the quality summary + [SEARCH_REF:ref_id], never the - raw product list. The LLM references the result in its final response via - the [SEARCH_REF:...] token; the UI renders the product cards from the registry. +- search_products is created via make_search_products_tool(session_id, registry). +- After search API, an LLM labels each result as Highly Relevant / Partially Relevant / Not Relevant; we count and + store the curated list in the registry, return [SEARCH_REF:ref_id] + quality counts + top10 titles. """ import base64 @@ -65,94 +58,61 @@ def get_openai_client() -> OpenAI: # ── LLM quality assessment ───────────────────────────────────────────────────── -def _assess_search_quality( - query: str, - raw_products: list, -) -> tuple[list[str], str, str]: +def _assess_search_quality(query: str, raw_products: list) -> tuple[list[str], str]: """ - Ask the LLM to evaluate how well each search result matches the query. - - Returns: - labels – list[str], one per product: "完美匹配" | "部分匹配" | "不相关" - verdict – str: "优质" | "一般" | "较差" - summary – str: one-sentence explanation + Use LLM to label each search result and write a short quality_summary. + Returns (labels, quality_summary). labels: one per product; quality_summary: 1–2 sentences. """ n = len(raw_products) if n == 0: - return [], "较差", "搜索未返回任何商品。" + return [], "" - # Build a compact product list — only title/category/tags/score to save tokens - lines: list[str] = [] + lines = [] for i, p in enumerate(raw_products, 1): title = (p.get("title") or "")[:60] - cat = p.get("category_path") or p.get("category_name") or "" - tags_raw = p.get("tags") or [] - tags = ", ".join(str(t) for t in tags_raw[:5]) - score = p.get("relevance_score") or 0 - row = f"{i}. [{score:.1f}] {title} | {cat}" - if tags: - row += f" | 标签:{tags}" - lines.append(row) - + lines.append(f"{i}. {title}") product_text = "\n".join(lines) - prompt = f"""你是商品搜索质量评估专家。请评估以下搜索结果与用户查询的匹配程度。 + prompt = f"""评估以下搜索结果与用户查询的匹配程度，完成两件事： +1. 为每条结果打一个等级：Highly Relevant / Partially Relevant / Not Relevant。 +2. 写一段 quality_summary（1–2 句话）：简要说明搜索结果主要包含哪些商品、是否基本满足搜索意图、整体匹配度如何。 用户查询：{query} -搜索结果（共 {n} 条，格式：序号. [相关性分数] 标题 | 分类 | 标签）： +搜索结果（共 {n} 条）： {product_text} -评估说明： -- 完美匹配：完全符合用户查询意图，用户必然感兴趣 -- 部分匹配：与查询有关联，但不完全满足意图（如品类对但风格偏差、相关配件等） -- 不相关：与查询无关，不应展示给用户 - -整体 verdict 判断标准： -- 优质：完美匹配 ≥ 5 条 -- 一般：完美匹配 2-4 条 -- 较差：完美匹配 < 2 条 - -请严格按以下 JSON 格式输出，不得有任何额外文字或代码块标记： -{{"labels": ["完美匹配", "部分匹配", "不相关", ...], "verdict": "优质", "summary": "一句话评价搜索质量"}} +等级说明：Highly Relevant=完全符合查询意图；Partially Relevant=基本相关（如品类等主需求匹配但部分属性不完全符合）；Not Relevant=不相关。 -labels 数组长度必须恰好等于 {n}。""" +请严格按以下 JSON 输出，仅输出 JSON，无其他内容： +{{"labels": ["Highly Relevant", "Partially Relevant", "Not Relevant", ...], "quality_summary": "你的1-2句总结"}} +labels 数组长度必须等于 {n}。""" try: client = get_openai_client() resp = client.chat.completions.create( model=settings.openai_model, messages=[{"role": "user", "content": prompt}], - max_tokens=800, + max_tokens=700, temperature=0.1, ) raw = resp.choices[0].message.content.strip() - # Strip markdown code fences if the model adds them if raw.startswith("```"): raw = raw.split("```")[1] if raw.startswith("json"): raw = raw[4:] raw = raw.strip() - data = json.loads(raw) - labels: list[str] = data.get("labels", []) - - # Normalize and pad / trim to match n - valid = {"完美匹配", "部分匹配", "不相关"} - labels = [l if l in valid else "部分匹配" for l in labels] + labels = data.get("labels", []) + valid = {"Highly Relevant", "Partially Relevant", "Not Relevant"} + labels = [l if l in valid else "Partially Relevant" for l in labels] while len(labels) < n: - labels.append("部分匹配") - labels = labels[:n] - - verdict: str = data.get("verdict", "一般") - if verdict not in ("优质", "一般", "较差"): - verdict = "一般" - summary: str = str(data.get("summary", "")) - return labels, verdict, summary - + labels.append("Partially Relevant") + quality_summary = (data.get("quality_summary") or "").strip() or "" + return labels[:n], quality_summary except Exception as e: - logger.warning(f"Quality assessment LLM call failed: {e}; using fallback labels.") - return ["部分匹配"] * n, "一般", "质量评估步骤失败，结果仅供参考。" + logger.warning(f"Quality assessment failed: {e}; using fallback.") + return ["Partially Relevant"] * n, "" # ── Tool factory ─────────────────────────────────────────────────────────────── @@ -169,22 +129,18 @@ def make_search_products_tool( 2. Runs LLM quality assessment on up to 20 results. 3. Stores a SearchResult in the registry. 4. Returns a concise quality summary + [SEARCH_REF:ref_id]. - The product list is NEVER returned in the tool output text. """ @tool def search_products(query: str, limit: int = 20) -> str: - """搜索商品库，根据自然语言描述找到匹配商品，并进行质量评估。 - - 每次调用专注于单一搜索角度。复杂需求请拆分为多次调用，每次换一个 query。 - 工具会自动评估结果质量（完美匹配 / 部分匹配 / 不相关），并给出整体判断。 + """搜索商品库并做质量评估：LLM 为每条结果打等级（Highly Relevant / Partially Relevant / Not Relevant），返回引用与 top10 标题。 Args: - query: 自然语言商品描述，例如"男士休闲亚麻短裤夏季" - limit: 最多返回条数（建议 10-20，越多评估越全面） + query: 自然语言商品描述 + limit: 最多返回条数（1-20） Returns: - 质量评估摘要 + [SEARCH_REF:ref_id]，供最终回复引用。 + 【搜索完成】+ 结果引用 [SEARCH_REF:ref_id] + 质量情况（评估条数、Highly/Partially Relevant 数）+ results list（top10 标题） """ try: logger.info(f"[{session_id}] search_products: query={query!r} limit={limit}") @@ -199,6 +155,9 @@ def make_search_products_tool( "size": min(max(limit, 1), 20), "from": 0, "language": "zh", + "enable_rerank": True, + "rerank_query_template": query, + "rerank_doc_template": "{title}", } resp = requests.post(url, json=payload, headers=headers, timeout=60) @@ -216,40 +175,32 @@ def make_search_products_tool( "未找到匹配商品，建议换用更宽泛或不同角度的关键词重新搜索。" ) - # ── LLM quality assessment ────────────────────────────────────── - labels, verdict, quality_summary = _assess_search_quality(query, raw_results) + labels, quality_summary = _assess_search_quality(query, raw_results) + perfect_count = sum(1 for l in labels if l == "Highly Relevant") + partial_count = sum(1 for l in labels if l == "Partially Relevant") + irrelevant_count = len(labels) - perfect_count - partial_count - # ── Build ProductItem list (keep perfect + partial, discard irrelevant) ── products: list[ProductItem] = [] - perfect_count = partial_count = irrelevant_count = 0 - for raw, label in zip(raw_results, labels): - if label == "完美匹配": - perfect_count += 1 - elif label == "部分匹配": - partial_count += 1 - else: - irrelevant_count += 1 - - if label in ("完美匹配", "部分匹配"): - products.append( - ProductItem( - spu_id=str(raw.get("spu_id", "")), - title=raw.get("title") or "", - price=raw.get("price"), - category_path=( - raw.get("category_path") or raw.get("category_name") - ), - vendor=raw.get("vendor"), - image_url=_normalize_image_url(raw.get("image_url")), - relevance_score=raw.get("relevance_score"), - match_label=label, - tags=raw.get("tags") or [], - specifications=raw.get("specifications") or [], - ) + if label not in ("Highly Relevant", "Partially Relevant"): + continue + products.append( + ProductItem( + spu_id=str(raw.get("spu_id", "")), + title=raw.get("title") or "", + price=raw.get("price"), + category_path=( + raw.get("category_path") or raw.get("category_name") + ), + vendor=raw.get("vendor"), + image_url=_normalize_image_url(raw.get("image_url")), + relevance_score=raw.get("relevance_score"), + match_label=label, + tags=raw.get("tags") or [], + specifications=raw.get("specifications") or [], ) + ) - # ── Register ──────────────────────────────────────────────────── ref_id = new_ref_id() result = SearchResult( ref_id=ref_id, @@ -259,65 +210,27 @@ def make_search_products_tool( perfect_count=perfect_count, partial_count=partial_count, irrelevant_count=irrelevant_count, - quality_verdict=verdict, quality_summary=quality_summary, products=products, ) registry.register(session_id, result) - - # ── Search result detailed log (ref_id, summary, per-item id + image_url raw/normalized) ── - logger.info( - "[%s] SEARCH_RESULT ref_id=%s query=%s total_api_hits=%s returned_count=%s " - "verdict=%s quality_summary=%s perfect=%s partial=%s irrelevant=%s", - session_id, - ref_id, - query, - total_hits, - len(raw_results), - verdict, - quality_summary, - perfect_count, - partial_count, - irrelevant_count, - ) - for idx, raw in enumerate(raw_results): - raw_img = raw.get("image_url") or "" - logger.info( - "[%s] SEARCH_RESULT_ITEM raw idx=%s spu_id=%s title=%s image_url_raw=%s", - session_id, - idx, - raw.get("spu_id", ""), - (raw.get("title") or "")[:60], - raw_img, - ) - for p in products: - logger.info( - "[%s] SEARCH_RESULT_PRODUCT spu_id=%s match_label=%s image_url_normalized=%s", - session_id, - p.spu_id, - p.match_label, - p.image_url or "", - ) - + assessed_n = len(raw_results) logger.info( - f"[{session_id}] Registered {ref_id}: verdict={verdict}, " - f"perfect={perfect_count}, partial={partial_count}, irrel={irrelevant_count}" + "[%s] Registered %s: query=%s assessed=%s perfect=%s partial=%s", + session_id, ref_id, query, assessed_n, perfect_count, partial_count, ) - # ── Return summary to agent (NOT the product list) ────────────── - verdict_hint = { - "优质": "结果质量优质，可直接引用。", - "一般": "结果质量一般，可酌情引用，也可补充更精准的 query。", - "较差": "结果质量较差，建议重新规划 query 后再次搜索。", - }.get(verdict, "") + top10_titles = [ + (raw.get("title") or "未知")[:80] + for raw in raw_results[:10] + ] + results_list = "\n".join(f"{i}. {t}" for i, t in enumerate(top10_titles, 1)) return ( f"【搜索完成】query='{query}'\n" - f"API 总命中：{total_hits} 条 | 本次评估：{len(raw_results)} 条\n" - f"质量评估：完美匹配 {perfect_count} 条 | 部分匹配 {partial_count} 条 | 不相关 {irrelevant_count} 条\n" - f"整体判断：{verdict} — {quality_summary}\n" - f"{verdict_hint}\n" - f"结果引用：[SEARCH_REF:{ref_id}]" + f"结果引用：[SEARCH_REF:{ref_id}]\n" + f"搜索结果质量情况：评估总条数{assessed_n}条，Highly Relevant {perfect_count} 条，Partially Relevant {partial_count} 条。\n" + f"results list:\n{results_list}" ) except requests.exceptions.RequestException as e: -- libgit2 0.21.2