面向 LLM 的程序设计 3：LLM-Friendly 的响应结构：扁平键、稳定字段与类型标注

在满足能力端点与确定性契约之后响应长什么样仍会直接影响模型能不能「读对结果、少误解、少编造字段」。本系列继续围绕「让 AI 更好理解、更好调用」讨论如何把 JSON 响应设计成对模型和后续工具链都更友好键名稳定、层次尽量扁平、数组与对象的语义一眼能读懂并用明确的标量类型整数金额的分、布尔库存等减少歧义。本篇为系列第三篇前两篇分别谈了能力端点与JSON Schema 硬契约本篇聚焦响应体形态——在契约已成立的前提下仍要避免「能校验却难理解」的嵌套与命名让解析与链式调用更省心。摘要深层嵌套、缩写键名、同一语义多种字段名、金额与布尔用字符串承载都会增加模型解析负担与幻觉风险。采用扁平或浅层结构、稳定且可预期的 snake_case 全名、与业务语义一致的类型如price_cents: integer、in_stock: boolean并在顶层保留response_type等判别字段可显著提升 LLM 与程序化下游的消费体验。本文说明原则与正反对照并给出可运行对比示例。关键词LLM-Friendly APIJSON 响应设计扁平结构稳定字段类型标注源代码链接面向 LLM 的程序设计 3LLM-Friendly 的响应结构源代码1 为什么「有 Schema」还不够即便请求与响应都通过了 JSON Schema 校验仍可能出现层次过深结果藏在data.payload.result.items之下模型在多步推理中容易数错层级或把兄弟字段张冠李戴。键名不稳定或过于简略r、d、list这类缩写对人可读性差对模型也缺少语义锚点不同接口分别用id/productId/pid表示同一概念时跨工具拼接容易混用。标量类型语义模糊金额用19.99字符串、in_stock用yes模型可能输出与下游不一致的格式整数分 货币码、「真假的布尔」更利于确定性处理。数组项形状不一致有的元素是对象、有的嵌套多一层 wrapper会给「取第 i 个元素的某字段」这类操作埋下错误种子。可以把响应想象成给另一位工程师的交接单Schema 保证「字段合法」而LLM-Friendly 结构保证「一眼知道每格写什么、少翻层、少猜缩写」。2 设计原则小结原则含义 理解要点扁平优先重要结论放在顶层或浅层避免无信息增量的深套娃像目录页先见到「有几条、是什么类型」再展开列表键名稳定、可读全词、snake_case、同一概念全局同名如始终product_id避免同一文档多种命名风格混用类型即语义钱用整数最小单位 currency是否库存用boolean减少「字符串里的数字」带来的二次解析列表元素同质数组内对象字段集合一致少用「有时对象有时字符串」便于模型写循环与下游代码复用顶层判别可用response_type或等价枚举区分不同成功形态便于分支逻辑与少误读字段实际例子搜索商品接口的成功体可设计为response_type: product_search、product_count: 3、products: [{ product_id, title, price_cents, currency, in_stock }]而不是d: { r: { l: [...] } }且金额为12.50字符串。3 反例与正例概念对照反例仍可能过校验但难理解深层路径body.data.results.items[].product.meta.title缩写键p、amt、flg金额19.99string库存1string正例契约 友好顶层response_type、product_count、products单项product_id、title、price_centsint、currency如CNY、in_stockbool可选统一分页next_cursorstring | null与 Schema 对齐避免魔法嵌套完整字段定义见配套 demo 中的 Pydantic 模型与 OpenAPI。4 本示例在做什么配套demo用同一套内存里的 mock 商品例如sku_1001无线鼠标、sku_1002机械键盘含原价整数分、币种、是否有货经同一个过滤条件生成两种响应两端都走 FastAPI PydanticOpenAPI/docs里能看到两套不同的响应 Schema但都满足校验。共同请求POST请求体 JSON 为ProductSearchRequest字段只有query字符串可空。服务端对MOCK_PRODUCTS做标题子串匹配不区分大小写query为空则返回全部商品query非空则只保留title中含该子串的项。main.py里固定发送{query: 键盘}因此只会命中「机械键盘」一条便于两份响应在「条数相同」的前提下纯粹对比形状。1POST /examples/nested-legacy反例响应根上是缩写键d其下为r→l表示 data / result / list列表元素为i商品 id与mmeta。标题与价格在m里缩写为t、amt其中amt是字符串由内部price_cents格式化成类似99.00的小数字符串故意丢掉「整数分 币种」的确定性表达。若要用自然语言描述取一条商品的标题需要走路径大致如d.r.l[0].m.tid 为d.r.l[0].i。不建议在生产照搬这一形状。2POST /examples/flat-llm-friendly正例顶层依次给出response_type本 demo 固定为product_search用于多态判别、product_count整数条数、products数组。数组元素是同质对象product_id、title、price_cents整数最小货币单位、currency三字母如CNY、in_stock布尔。与同一条 mock 数据源对齐但不再把价格压成无币种的字符串。如何对照先uvicorn server_api:app --reload --port 8312再在项目目录运行python main.py终端会先后打印两次美化后的 JSON。读者可以数一下反例从根到「第一条商品标题」经过几层键名、正例是否一眼能读到products[0].title并打开http://127.0.0.1:8312/docs展开两个 POST对照自动生成的响应 Schema 与字段说明。启动服务后再在另外一个terminal中运行python main.pyterminal中返回 1. 反模式POST /examples/nested-legacy 请求: {query: 键盘} 响应 JSON美化: { d: { r: { l: [ { i: sku_1002, m: { t: 机械键盘, amt: 459.00 } } ] } } } 2. LLM-FriendlyPOST /examples/flat-llm-friendly 请求: {query: 键盘} 响应 JSON美化: { response_type: product_search, product_count: 1, products: [ { product_id: sku_1002, title: 机械键盘, price_cents: 45900, currency: CNY, in_stock: false } ] }5 完整代码与文档运行与架构README_运行与架构.md完整方案README_完整方案.md在项目目录下执行pip install -r requirements.txt启动uvicorn server_api:app --reload --port 8312后另开终端运行python main.py。