Administrator
Published on 2026-11-21 / 4 Visits
0
0

搜索 API 返回成功,为什么 Agent 留下的相关词却是空对象?

搜索接口返回了十条结果,程序也没有报错,但留给下一步 Agent 的相关搜索词是这样:[{}, {}, {}]。应该换搜索服务,还是说明这个题目没人搜?

这次问题出在更靠近自己的地方:响应中的词放在 query,归档时允许保留的字段却没有它。程序把有内容的记录变成了空对象,随后仍把整次查询记成成功。这是本次博客管线改造中实际发现的缺陷。下面把它缩成一个不含凭据的例子。

先找出哪一步还看得到这个词

这一条公开响应字段就足以重现问题:

{"relatedSearches": [{"query": "MCP vs CLI vs API"}]}

如果归一化代码只允许保留 title、link、snippet、question 和 searchTerm,输入并不会引发异常。逐项过滤后的记录恰好是空字典。

可以沿着三个位置比较同一个字段:接口返回后、本地归一化后、写入归档再读出后。第一个位置有词、第二个位置没有,就先检查适配器;前两个都有、归档中没有,再查保存和读取。这样定位比反复换关键词更直接。

Serper 把搜索结果提供为结构化响应,公开示例中也能看到不同结果块。本文说的 query 来自本轮实际响应,不能推定其他服务、其他端点永远采用相同字段。Serper 官方入口

为什么请求和 JSON 都成功,数据仍然没用?

JSON 解码回答的是文本能不能变成对象。它不会判断适配器留下的字段够不够下一步使用。Python JSON 文档

搜索接口的正常结果也不能替相关词分支作保证。旧回归样例覆盖了请求与主要结果处理,却没有覆盖 relatedSearches[].query 能否在归一化后保留。于是其他检查通过,这个分支仍然丢了数据。

这里需要补的断言很具体:给适配器一条含 query 的相关词记录,产物中应当还有这个词。列表非空不够,因为 [{}] 同样是非空列表。

空结果至少要问清四种情况

响应没有 relatedSearches,只能说明这次没有提供该块。明确返回 relatedSearches: [],表示该响应块没有条目。两种情况都不能证明市场上没人搜这个问题。

如果这个字段本应是数组却变成对象,或数组里有不含有效 query 的记录,则是格式或适配规则需要检查。把这些情况全部过滤成 [],虽然省去了异常,却也可能把下一次字段变化掩盖成正常空结果。

本次生产修复做了两件事:保留公开的 query 字段,丢弃过滤后为空的对象。它修复了已经观察到的数据丢失,但还没有提供上述四种状态的完整业务接口。下方例子是更严格的教学版本:缺字段返回 None,明确空数组返回 [],不符合预期的类型或记录报错。

用一个小样例阻止同样的遗漏

def related_queries(payload):
    if not isinstance(payload, dict):
        raise ValueError('response must be an object')
    if 'relatedSearches' not in payload:
        return None
    rows = payload['relatedSearches']
    if not isinstance(rows, list):
        raise ValueError('relatedSearches must be an array')
    result = []
    for row in rows:
        if not isinstance(row, dict) or not isinstance(row.get('query'), str) or not row['query'].strip():
            raise ValueError('related search needs a nonempty query')
        result.append({'query': row['query'].strip()})
    return result

先测正常条目中的词能保留、额外字段不会被带出;再测缺字段与空数组;最后测错误容器和坏记录会明确失败。unittest 可以用固定输入检查这些结果,不需要每次拿真实密钥请求服务。Python unittest 文档

本轮对上述严格示例运行了四个测试方法,覆盖这些分支。它们验证的是给定样例的处理方式,不代表搜索质量、所有上游响应或 PV 效果都已验证。

接入别的搜索服务时,先替换成它真实的脱敏响应,再调整字段规则。下一次看到 Agent 说“没有相关问题”,可以先追问:上游真的没有返回,还是内容在我们手里消失了?

进一步阅读:结构化输出为什么还需要语义验证。那篇讨论结果满足格式后是否满足业务条件;这里检查更早的一步:信息在适配器中有没有被保留下来。


Comment