ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

SurfSense Google Maps 子代理深度解析:基于实时地图数据的本地商家与评论结构化采集

SurfSense Google Maps 子代理深度解析:基于实时地图数据的本地商家与评论结构化采集 SurfSense Google Maps 子代理深度解析基于实时地图数据的本地商家与评论结构化采集【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense导读本篇文章聚焦 SurfSense 多代理聊天系统multi-agent chat中内置的google_maps子代理subagent它是一台专门从 Google Maps 采集结构化数据的实时地图情报站既能按搜索词可限定地理位置发现商家也能把 Maps URL / place ID 解析成完整的商家详情名称、地址、类别、电话、官网、评分、评论数、坐标、营业时间还能抓取某商家的全部评论作者、正文、星级、商家回复、日期并支持与对话中此前获取的地图数据进行对比。读完本文你将掌握该子代理的职责边界、触发方式、google_maps_scrape与google_maps_reviews两个核心工具的完整参数语义、底层执行链路、输出数据结构与计费规则可直接在自己的 SurfSense 会话中复现找咖啡店查某家店评分这家店口碑如何等真实场景。子代理定位多代理系统中的地图专家SurfSense 的多代理聊天采用 supervisor 子代理的协作架构。每个内置子代理负责一类数据源由deepagents框架按描述路由任务。google_maps子代理在 子代理注册表 中以google_maps: build_google_maps_subagent注册其构建逻辑位于 agent.py从description.md即本文所讲解的文档读取路由描述从 system_prompt.md 读取系统提示词通过 tools/index.py 加载两个能力工具并以Ruleset(origingoogle_maps, rules[])声明该子代理的权限来源。description.md对该子代理的定位给出了精确定义从 Google Maps 拉取结构化数据核心能力包括四件事按搜索词找商家——search_queries支持任意地图搜索词可选location将搜索范围限定到具体城市/地区URL / place ID 解析详情——把google.com/maps链接或已知 place ID 解析为商家详情名称、地址、类别、电话、官网、评分、评论数、坐标、营业时间抓取商家评论——包括作者、正文、星级、商家回复与日期对比早前发现——把新抓取的地图数据与本次会话中此前的查询结果做对比输出具体的差异新增、移除、旧值 → 新值。触发场景与边界description.md明确列出了该子代理应被激活trigger的任务形态find business type near/in X找 X 附近的某类商家get details for this place获取该商家详情phone/address/hours/rating of X查 X 的电话/地址/营业时间/评分how many reviews有多少条评论get the reviews for this place获取该商家评论what are people saying about this business大家怎么评价这家店对比类请求——针对会话中此前的 Maps 结果进行差异比较。同时也划定了明确的排除边界out-of-scope普通网页不属于本子代理应交给 web crawling specialistYouTube 相关内容交给 YouTube specialist。从源码看这一边界不仅在描述中声明还落实到了system_prompt.md的out_of_scope段并在agent.py的 fallback 描述中再次强调Pulls structured data from Google Maps — places and their reviews. 这种描述即路由契约的设计让 supervisor 可以在多代理之间精准派发任务。两个核心能力工具子代理的全部能力由两个 capability 动词组成见 tools/index.py通过build_capability_tools注入工具集工具名capability 注册名用途计费单元注册文件google_maps_scrapegoogle_maps.scrape抓取商家、详情、评论与照片GOOGLE_MAPS_PLACE每商家scrape/definition.pygoogle_maps_reviewsgoogle_maps.reviews抓取评论作者、评分、正文、商家回复GOOGLE_MAPS_REVIEW每评论reviews/definition.py两者均注册了docs_url/docs/connectors/native/google-maps说明这一能力与 SurfSense 的原生 Google Maps 连接器共享同一套底层数据管道。google_maps_scrape商家发现与详情解析输入契约定义在 scrape/schemas.py 的ScrapeInput核心参数如下参数类型默认值说明search_querieslist[str][]地图搜索词如coffee shops、dentist每个词最多返回max_places条结果。与urls、place_ids三选一至少提供其一urlslist[HttpUrlStr][]Google Maps 链接——商家页/maps/place/...或搜索结果页 URLplace_idslist[str][]已知的 Google place ID形如ChIJ...locationstr \| NoneNone限定search_queries的地理范围如New York, USA、Austin, USAmax_placesint10每个搜索词最多返回的商家数范围 1–1000languagestren结果语言代码如en、frinclude_detailsboolFalse是否额外抓取每个商家的详情页营业时间、热门时段、更多联系信息更慢、请求更多max_reviewsint0每个商家附带多少条评论0 不附带范围 0–100000max_imagesint0每个商家附带多少张图片0 不附带输入校验由model_validator保证三个来源字段search_queries/urls/place_ids必须至少提供一个否则抛出ValueError。同时每次调用的来源总数被MAX_MAPS_SOURCES 20硬性封顶目的是约束单次同步请求的扇出规模见 scrape/schemas.py。模型还提供两个预算估算属性estimated_units最坏情况的计费商家数 len(search_queries) * max_places len(urls) len(place_ids)estimated_review_units最坏情况附带评论数 estimated_units * max_reviews。这两个属性配合双计量dual-metered计费设计scrape按GOOGLE_MAPS_MICROS_PER_PLACE每商家GOOGLE_MAPS_MICROS_PER_REVIEW每附带评论双重计价ScrapeOutput中的billable_units返回的商家数与attached_review_count内联附带评论总数分别对应两个计量器。google_maps_reviews定向评论抓取输入契约定义在 reviews/schemas.py 的ReviewsInput参数类型默认值说明urlslist[HttpUrlStr][]商家页 URL 列表与place_ids至少提供一个place_idslist[str][]已知 place ID 列表max_reviewsint20每个商家最多返回的评论数范围 1–100000sort_byLiteralnewest评论排序newest/mostRelevant/highestRanking/lowestRankinglanguagestren评论语言代码start_datestr \| NoneNone只取该 ISO 日期如2024-01-01当天及之后的评论同样有MAX_MAPS_REVIEW_SOURCES 20的单次来源封顶以及至少一个来源的校验。estimated_units的估算为(len(urls) len(place_ids)) * max_reviews对应预检门pre-flight gate的计费拦截逻辑ReviewsOutput.billable_units则以实际返回的评论数为准实现按量计费。底层执行链路从动词到 Apify 爬虫google_maps子代理的工具并非自研爬虫而是包装了 SurfSense 的 proprietary Google Maps 平台能力。执行链路为子代理工具层load_tools→build_capability_tools见 capabilities/core/access/agent.py把 capability 注册表中的GOOGLE_MAPS_SCRAPE、GOOGLE_MAPS_REVIEWS实例化为可调用工具Executor 层以 scrape/executor.py 为例execute(payload)把ScrapeInput映射为底层GoogleMapsScrapeInput——字段一一对应search_queries → searchStringsArray、urls → startUrls[{url: ...}]、place_ids → placeIds、location → locationQuery、max_places → maxCrawledPlacesPerSearch、include_details → scrapePlaceDetailPage、max_reviews → maxReviews、max_images → maxImages执行与异常映射执行前后通过emit_progress(starting/done, ...)上报进度以place为单位若底层爬虫抛出SignInRequiredError需要 Google 登录则转换为ForbiddenError错误码GOOGLE_SIGNIN_REQUIREDProprietary 平台层真正的抓取由scrape_places完成输出直接复用 Apify Google Maps Scraper 的PlaceItem结构见 proprietary/platforms/google_maps/schemas.py。这意味着子代理拿到的是已经规范化、结构化的地图数据而不是原始 HTML——这正是它能以稳定 JSON 输出 证据引用方式被 supervisor 合成答案的基础。输出数据结构PlaceItem 与 ReviewItemScrapeOutput.items的元素为PlaceItem字段按语义分为多组均可选未抓取到默认None/[]/{}且extraallow保持契约开放溯源searchString触发搜索词、rank排名、searchPageUrl、isAdvertisement是否为广告位身份title、subTitle、description、price、categoryName/categories、placeId、fid/cid/kgmid地址/位置address、neighborhood、street、city、postalCode、state、countryCode、location含经纬度坐标、plusCode、locatedIn、parentPlaceUrl联系website、phone/phoneUnformatted、menu、servicesLink评分/状态totalScore评分、reviewsCount评论数、reviewsDistribution、permanentlyClosed/temporarilyClosed关店状态图片imageUrl、imagesCount、images含作者与上传时间、imageUrls详情页字段仅include_detailstrue时填充openingHours营业时间、peopleAlsoSearch、reviewsTags、additionalInfo、questionsAndAnswers、bookingLinks、reserveTableUrl、restaurantData等内联评论仅max_reviews 0时填充reviews[]元素为ReviewFields。ReviewItemreviews工具的独立输出继承ReviewFields并与商家字段合并形成一条评论一条记录的扁平结构字段覆盖name作者、text正文、textTranslated翻译文本、stars星级、rating、publishAt/publishedAtDate日期、likesCount点赞、responseFromOwnerText/responseFromOwnerDate商家回复内容与时间、reviewId/reviewUrl/reviewerId/reviewerUrl、isLocalGuide是否本地向导、visitedIn、originalLanguage/translatedLanguage等见 schemas.py。实战子代理的调用剧本Playbooksystem_prompt.md中给出了该子代理面对具体任务时的标准操作顺序配合description.md的能力描述可归纳为如下实战剧本找某类商家调用google_maps_scrape传search_queries并用location限定范围——例如coffee shops Austin, USA已知链接/ID 查详情把链接放进urls或把 ID 放进place_ids调用google_maps_scrape要更丰富信息营业时间、热门时段、额外联系方式设置include_detailstrue查评论/口碑针对具体商家调用google_maps_reviews传urls或place_ids批量优先把多个查询词、URL 或 place ID合并进一次调用而不是逐个发小请求受 20 个来源的上限约束对比请求先取当前值与会话中此前的工具结果对比报告具体差异新增/移除/旧值 → 新值且只报告能在证据中找到的差异。剧本中还包含两条重要的判定规则体现于system_prompt.md的playbook排除标准从严任务排除了某类别或某品牌时任何名称、网站域名或类别命中的商家都必须剔除——某连锁品牌的分店/卫星点仍属于该连锁不得变通为可接受缺口应通过更多或更宽的查询补齐网站域名即所有权信号某商家的官网若挂在母公司域名下政府门户、连锁官网、医疗系统或加盟商域名则该商家归属于母公司——包含/排除判定应针对母公司进行多个共享同一母公司域名的地点视为同一组织。这两条规则直接服务于description.md提到的对比早前发现能力保证对比与归并的正确性。输出契约与失败策略子代理的输出被严格约束为单一 JSON 对象不允许 markdown 或散文契约如下{ status: success | partial | blocked | error, action_summary: string, evidence: { findings: [string], sources: [string], confidence: high | medium | low }, next_step: string | null, missing_fields: [string | null], assumptions: [string | null] }其中路由专属规则route-specific rules为evidence.findings最多 10 条每条一句话陈述一个独立事实或差异禁止粘贴原始载荷evidence.sources最多 10 个 URL有对应发现时一条一源每个 URL 只列一次。失败处理策略failure_policy同样严谨请求信息不足没有可用的搜索词、URL 或 place ID→ 返回statusblocked并附上缺失字段工具失败 → 返回statuserror并给出简洁的恢复建议next_step无有效证据 → 返回statusblocked附上更窄的查询词或仍需要的 URL/ID。配合tool_policy的两条铁律——只用可用工具、status不为success的条目视为无数据绝不虚构以及safety中的证据不完整或冲突时明确报告不确定性绝不把未经证实的说法当作事实——整个子代理在事实性与可审计性上被严格约束。这与description.md反复强调的结构化数据定位一脉相承supervisor 拿到的是一份可引用、可核验的证据包而非自由生成的文本。总结google_maps子代理是 SurfSense 多代理系统中实时地理数据这一垂直领域的专职专家。它以 description.md 为路由契约通过google_maps_scrape与google_maps_reviews两个能力动词将搜索词、Maps URL、place ID 三种输入统一转化为规范的PlaceItem/ReviewItem结构化数据并以严格的 JSON 输出契约向 supervisor 交付带证据引用的发现。其底层由 capability 注册、executor 映射、proprietary 爬虫三层构成具备双重计费、来源上限、进度上报与登录异常映射等工程化设计。理解该子代理的触发边界、参数语义与输出结构即可在 SurfSense 中精确复用这一地图情报能力并将其与 Web 抓取、YouTube 等其他专职子代理协同构建覆盖开放互联网的复合研究流程。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表