接入 AI Agent 之后，格式选错才开始疼

今年做 RAG 和 Agent 的项目多起来，同一个搜索端点，被三种完全不同的调用方在用：后台报表、爬虫补数、大模型读页面。

一开始我都用默认的 json。后来发现喂给模型的场景里，模型要的是干净正文，json 里那一堆嵌套结构反而成了噪音；而补数的场景又需要原始页面里的链接，json 只给摘要不够用。

SerpBase 的网页搜索支持三种返回格式，价格一样，都是 1 credit，差别在拿到的东西。

三种格式返回的到底是什么

format	返回内容	结构
json（默认）	结构化结果	带信封：status、request_id、elapsed_ms、credits_charged，加 organic 等模块
raw	真实页面 HTML	页面原样，链接已解析成真实地址
markdown	正文的 Markdown	直接给 text/markdown，适合喂模型

同样一次请求，同样扣 1 credit，但拿到的东西完全不同——这不是版本差异，是设计上的分工。

同一句话，三种格式的差别

import os
import requests

KEY = os.getenv("SERPBASE_API_KEY", "")

def fetch(query: str, fmt: str) -> requests.Response:
    return requests.post(
        "https://api.serpbase.dev/google/search",
        headers={"Content-Type": "application/json", "X-API-Key": KEY},
        json={"q": query, "gl": "us", "hl": "en", "device": "pc", "format": fmt},
        timeout=(5, 30),
    )

for fmt in ("json", "markdown", "raw"):
    r = fetch("espresso machine maintenance", fmt)
    print(fmt, r.headers.get("Content-Type"), len(r.content))

json 返回的是可解析对象，能直接取字段；markdown 返回的是文本，长度和页面正文相关；raw 返回的是整页 HTML，体积最大，但包含了页面上所有可见信息。

三者互不替代：想要字段就 json，想要正文就 markdown，想要页面里 json 没覆盖的部分才用 raw。

我用 markdown 做监控，丢了 request_id

有一个项目图省事，全部换成 markdown，理由是这样模型能直接读，不用写解析。

跑了一个月，做成本核对时卡住了：markdown 没有信封，request_id 和 credits_charged 都不在里面。要按天对账、要追某次异常调用，只能回去翻网关日志。

更麻烦的是排错。有一次某个词的结果明显不对，我想确认是哪次调用返回的，没有 request_id，只能按时间戳去猜。

现在的分工是固定的：所有进入数据管道的请求一律用 json，落盘时保留完整信封；需要喂给模型的内容，在本地用 json 里的字段重新拼，或者对同一个页面单独发一次 markdown 请求。

后一种方式多花 1 credit，但省掉了「模型输出和原始数据对不上」这类扯皮。

选型规则：谁用谁取

按调用方分工，比按习惯选格式靠谱：

后台报表、监控、对账——json。需要 status 判断结果是否有效，需要 credits_charged 做成本核算，需要 request_id 做链路追踪。

内容入库、喂给模型——markdown。省掉一套 HTML 清洗逻辑，正文干净，token 也省。

页面结构分析、抓取 json 未覆盖的部分——raw。链接已经解析过，不用自己处理跳转。

参数与格式说明以 SerpBase 文档 为准。