在医院查询里搜“骨科”返回的total可能远超预期名称里带骨科的、简介里提到骨科的、科室列表里有骨科但医院本身是综合医院的都可能被召回。要不要全都要取决于搜索框放在哪个页面。为了把流程讲具体本文用数据鱼API的「全国医院查询」接口做演示分支为「全文搜索」GET /v1/api/hospital/search。关键词搜索医院。scope 决定召回范围GET /v1/api/hospital/search的必填参数是key和keywordkeyword最大 128 字符。scope有三个值name搜名称和别名intro搜简介和科室all是默认值范围最广。limit默认 20最大 20。名称搜索适合顶部搜索框用户输入什么就想找叫什么的地方。简介和科室搜索适合症状或科室导航页此时用户关心的是“哪家医院有这个科”而不是名字里有没有这个词。范围选错结果就会显得又杂又少。scope的选择还会影响total的含义。name 模式下的total是名称匹配数intro 模式下可能包含大量科室描述命中的记录两者不可直接比较。做数据看板时要把scope作为维度记录下来否则趋势图会失真。过滤条件都是精确匹配province、city、district、level、type、operation_mode、insurance七个过滤参数全部是精确匹配。传“安徽”不会命中“安徽省”传“三甲”不会命中“三级甲等”值必须和字典或数据里的写法一致。这也是很多人觉得搜索结果不对的原因关键词没问题过滤条件却把结果筛空了。上线前先用省份列表、级别列表、类型列表把值对齐再联调搜索。过滤条件之间是 AND 关系叠加越多结果越少。用户连续勾选省份、城市、等级、类型后结果为空很常见。页面应该提供清除筛选入口并在空结果时提示是哪个条件过窄而不是只显示一个空列表。relevance 什么时候有返回里的data.list[].relevance是相关度得分文档说明只有全文检索模式返回。data.mode会标明本次是fulltext还是like。关键词只有一个字时检索会退化成模糊匹配此时没有relevance排序逻辑要能兜底。不要假设relevance的数值范围固定它适合做相对排序不适合直接展示给用户也不适合跨关键词比较。relevance只适合在同一批结果里比较。不同关键词、不同scope下的分数没有可比性不要拿它做跨查询的阈值判断例如“分数低于 5 就丢弃”这类规则在不同数据集上表现差异很大。curl -s -G $API_BASE/v1/api/hospital/search \ --data-urlencode key$API_KEY \ --data-urlencode keyword骨科 \ --data-urlencode scopename \ --data-urlencode province安徽省 \ --data-urlencode limit20{ code: 200, msg: success, data: { list: [ {id: 3, name: 宁国市骨科医院, province: 安徽省, city: 宣城市, type: 专科医院, relevance: 9.8} ], mode: fulltext, total: 331 } }def search_hospitals(keyword, provinceNone, scopename): params {key: API_KEY, keyword: keyword, scope: scope, limit: 20} if province: params[province] province data requests.get(f{API_BASE}/v1/api/hospital/search, paramsparams, timeout5).json()[data] rows data[list] if data[mode] fulltext: rows.sort(keylambda x: x.get(relevance, 0), reverseTrue) return rows, data[total]几个坑单字关键词会走 like 模式relevance缺失如果代码直接读这个字段会报错。scopeintro会把科室里提到关键词的医院也召回只想按名称找就用name。limit最大 20接口没有分页参数想要更多结果只能加过滤条件缩小范围。insurance的取值没有独立字典接口以实际数据为准不要自己发明“有医保”“无医保”这类值。搜索入口和scope对齐过滤值和字典对齐这两件事做好结果就不会太离谱。搜索接口没有分页参数结果集最多 20 条做统计时只能以total为参考不能把当前页的分布当成整体分布如果要做全院分布统计应该用分页列表按地区逐个拉取。另外搜索结果的顺序会随数据更新变化做对比分析时要在同一时间段内取样。做结果页时把scope和mode一起写进调试信息排查召回问题时不用重新猜参数。示例接口来自数据鱼API的「全国医院查询」接口文档接口行为可能随版本调整接入前以最新文档为准。