准备 Claude Certified Architect 前置能力的人通常会在 API 调用上卡一下。不是模型回答质量不行而是输入输出格式没设计好。Part 9 把 XML 单独拿出来讲我一开始也觉得奇怪Claude API 本质是文本接口XML 又不像 JSON 那样是默认数据格式为什么要专门学实际跑过几个项目后才发现XML 在这类 API 场景里的价值不是传输而是结构。它非常适合用来给 Claude 传递带层级关系的提示词模板让模型严格按节点返回结果也为后续的日志解析、配置复用和自动化编排打基础。这篇就按我自己的实测顺序把 Claude API 中的 XML 输入构造、返回解析、报错排查和适用边界完整拆一遍。1. 先搞清楚Claude API 里为什么要单独讲 XML1.1 XML 不是 API 的必选格式而是提示词结构很多人听到“Claude API 与 XML”时第一反应是“API 不是用 JSON 请求吗”。这个理解没有错。Claude API 的请求和响应在传输层确实是 JSON 格式但问题是你发给模型的内容本身是放在 JSON 的某个字符串字段里的。也就是说API 接口长什么样和模型接收到的文本长什么样是两回事。XML 在这里发挥的作用是提示词的组织语言。比如你要让 Claude 从一篇长文本里提取订单信息自然语言写法通常是“请从下面的文本中提取订单号、商品列表、总金额分别放到对应字段里。”这种写法模型能听懂但任务一多、字段一多就很容易漏。使用 XML 标签后指令和数据之间的边界就会清晰很多request task从订单文本中提取结构化信息/task data 用户张三购买了两台显示器单价为1999元订单号是20240615A。 /data output 根节点为 order包含 order_id、items、total 三个子节点。 /output /request对 Claude 来说task、data、output就像三个抽屉模型能更快判断哪些内容是任务说明哪些是待处理数据哪些是输出要求。很多同学反馈“提示词已经写得很细了模型还是会乱”我建议优先检查一下结构而不是继续堆字。在 API 场景里用 XML 还有一个隐性好处日志可读。请求和响应都会经过日志系统如果是纯自然语言你需要从大量文本里定位某一段如果外层有 XML 标签不管是人看还是脚本过滤都会轻松不少。1.2 输出端用 XML 做结构化比 JSON 更稳的场景Claude 这类大模型在输出 JSON 时偶尔会出现多余的反引号、注释或者把字段名拼错。XML 同样有风险但只要你把根节点和闭合标签写清楚解析时的容错空间会更大。因为 XML 的结构是成对标签即使模型漏了一个字段你也能通过缺哪个闭标签快速定位而不是像 JSON 一样因为一个逗号就整体解析失败。我并不是说 XML 全面优于 JSON。JSON 在程序里转字典、转对象太方便了绝大多数接口都应该优先返回 JSON。但下面几类场景我个人会更倾向 XML需要把一段文本拆成多层级结构且层级关系很重要时。需要给节点加属性比如item id001 currencyCNY这种带元信息的数据。输出内容要直接对接旧系统、配置文件或流程引擎而这些系统本身就用 XML。希望日志里保留可读的区块方便人工复查时快速定位。Claude API 对文本内容没有强制要求用 XML。你可以按自己的习惯来但如果你正在做批量文档抽取或者自动化流程XML 的标签边界确实能减少很多“模型漏了一个字段”的情况。2. 环境准备先把 Claude Code 和 API 请求链路跑通2.1 安装 Claude Code 时最容易踩的命令识别问题网络上有不少人在安装 Claude Code 后执行claude命令时遇到“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”之类的报错或者在 Windows 下提示“不是内部或外部命令”。这个问题的原因通常不是工具没装好而是命令没有被系统找到。排查顺序建议是这样先确认安装是否完成。如果使用包管理器安装安装输出最后一般会有“successfully installed”字样。安装过程中如果出现权限、网络中断需要重新安装。检查执行命令的终端是否重启。Windows 下新配置的系统环境变量不会自动同步到已经打开的终端关掉重开通常能解决一大部分问题。查看命令实际所在位置。Windows 可以用where claudemacOS 或 Linux 可以用which claude。能输出路径说明命令存在问题在 PATH 配置。如果是在 VSCode 里使用记得在 VSCode 的集成终端里重新加载窗口或者直接在系统终端测试一次。确认 Node.js 环境正常。很多类似工具依赖 Node.js版本太旧可能导致命令安装一半就失败。我还见过一种情况用户同时装了多个版本旧版本在 PATH 里排在前面导致新命令没生效。这个问题很隐蔽因为表面看起来只是“命令不对”实际上是路径优先级的问题。检查 PATH 时可以把所有相关目录都列出来不只看第一个。2.2 API 调用前必须确认的三个基础配置环境跑通之后真正调用 Claude API 前我会先确认三件事。第一API Key 是否存在且有效。不要把 Key 写死在代码里建议放到环境变量或.env文件中。示例ANTHROPIC_API_KEYyour-api-key代码里只负责读取避免密钥被提交到版本库。第二模型名称是否可用。不同模型名称对应的上下文长度、计费和能力都不同。你不一定需要记住全部模型名但要确认你调用的模型名在当前账号、当前 API 版本下是存在的。如果模型名写错通常会收到类似“The supported api model names are ...”的提示。遇到这种提示不要怀疑网络先检查模型名拼写和可用列表。第三上下文长度和max_tokens是否匹配。模型对单次请求的总 token 数有限制。即使你只发送很短的内容如果系统提示词、历史消息、XML 模板、输出要求加在一起超过限制也会报错。这是后面常遇到的 400 错误的原因之一。环境配置阶段不要急着写复杂业务先用一个最小请求确认输入、输出、日志都正常再往后加 XML 结构。3. 用 Claude API 发送包含 XML 的请求3.1 构造 XML 输入根节点、子节点、属性怎么设计XML 输入设计得好不好直接影响 Claude 的理解和输出质量。我一般遵循几个原则。根节点只保留一个。一个请求里最好只有一个根节点比如request不要同时出现多个独立根节点。模型在解析时会更明确输出也更容易对齐。任务指令和业务数据分开。task里放你要让模型做什么data里放原始内容output里放输出要求。混在一起时模型经常分不清哪些字段需要提取哪些是给它的指令。标签命名要见名知意。像a、b这种短标签虽然省 token但在复杂任务里很容易让模型误解。使用order_id、product_name这样的命名更稳妥。属性适合放“分类信息”或“元信息”。比如item categoryelectronics name显示器/name quantity2/quantity price1999/price /item属性不要滥用。如果一个字段后续会被当作普通文本来处理就放到节点文本里如果它只是用于标记类型或归类的信息再考虑属性。还有一个容易忽略的点XML 里的特殊字符。如果你的业务数据中包含、、直接放进 XML 会导致结构解析出现问题。稳妥做法是用lt;、gt;、amp;转义或者把整段内容放到 CDATA 区块中。在 Claude API 场景下最安全的方式是在拼提示词时先对业务数据进行转义不要让特殊字符破坏标签结构。3.2 在提示词里告诉 Claude 解析规则和返回格式模型不是解析器它不会自动知道你要什么 XML。你必须在提示词里把输出规则说清楚。我通常会加这样一段“请只返回 XML不要使用 markdown 代码块不要添加注释不要输出额外解释。根节点必须为 order。”这段要求很重要。如果你不说明“不要使用 markdown 代码块”很多模型会自动把返回内容包在xml里。虽然这只是三个反引号但脚本解析时还得额外处理一层很容易踩坑。另外建议在模板中列出期望的节点结构甚至给出一个空节点模板order order_id/order_id items/items total/total /order模型看到这种结构后通常会按字段顺序补全内容。比只写“提取订单信息”要稳定得多。如果你需要描述“输出字段名为 order”不要在提示词里直接写order这个容易和自我闭合标签混淆的东西。可以写“根节点为 order”或者用转义写法。否则模型可能把字段名当成实际标签的一部分返回结果会出现多余嵌套。3.3 一个最小可运行的 Python 示例下面是一个调用 Claude API 的最小示例里面用到 XML 作为提示词结构。以官方 Python SDK 为例具体方法名以你安装的版本为准import anthropic client anthropic.Anthropic( api_keyyour-api-key ) xml_prompt request task从下面的订单文本中提取结构化信息/task data 用户张三购买了两台显示器单价为1999元订单号是20240615A。 /data output 请返回 XML根节点为 order包含 order_id、items、total 三个子节点。 不要使用 markdown 代码块不要添加额外解释。 /output /request resp client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens1024, messages[ {role: user, content: xml_prompt} ] ) print(resp.content[0].text)说明几个点。模型名这里写的是示例实际要以你账号可用的模型为准不确定的话去查 API 文档或错误提示。max_tokens是允许输出的最大 token 数不是总上下文所以不要把它设置成超过模型上限。你先用这个小样例跑通确认能拿到文本输出再替换成真实业务数据。如果返回结果不是预期 XML先看两样东西一是 API 返回的原始文本二是提示词里的 XML 有没有被转义或被模型误解。很多问题都不是代码没过而是 prompt 里的结构表达不准确。4. 返回结果里的 XML解析和验证4.1 正确处理 XML 输出不要直接当普通文本拼接Claude 返回的内容本质上还是字符串。即使你在提示词里要求“不要 markdown 代码块”也不能完全保证每次输出都干净。所以拿到输出后第一步是清理第二步才是解析。常见的清理操作是定位根节点。比如要求根节点是order那么可以这样做raw resp.content[0].text start raw.find(order) end raw.rfind(/order) len(/order) xml_text raw[start:end]这段代码不是万能的但它能处理大部分“前面有解释文字后面有补充说明”的情况。如果返回内容里有 XML 声明?xml version1.0 encodingUTF-8?那find(order)依然能找到根节点不影响截取。如果根节点带命名空间比如order xmlns...你的字符串匹配逻辑就要改成按结尾标签判断或者统一用解析库处理。不要直接把原始返回文本拼到日志或数据库里。一方面模型可能输出反引号、注释另一方面原始文本可能包含多余的上下文不利于下游使用。4.2 验证 XML 合法性和内容一致性的方法清理完之后建议用 Python 标准库xml.etree.ElementTree验证 XML 是否合法。示例import xml.etree.ElementTree as ET try: root ET.fromstring(xml_text) except ET.ParseError as e: print(XML 解析失败:, e)只要 XML 不合法这个步骤一定会抛出异常。解析失败时先看错误信息里的行列号再回头检查闭合标签和特殊字符。合法性通过后还要验证内容一致性。比如订单号字段是否为空金额是否为数字商品列表是否为空。模型可能生成一个结构合法但字段内容缺失的 XML这时候程序不会报错但业务会出问题。建议提取节点后做基础校验order_id root.findtext(order_id) total root.findtext(total) if not order_id: print(缺少 order_id)如果字段很多可以把校验规则写成一个函数逐个节点检查。最好在批量任务开始前先用五到十条样例验证一遍确认所有关键字段都能被正确填充再放大规模。4.3 很多“XML解析错误”其实是浏览器样式信息和编码问题有些人把 Claude 返回的 XML 存成.xml文件后用浏览器打开会看到类似 “This XML file does not appear to have any style information associated with it” 的提示。这句话的意思是浏览器没有找到 XSL 样式表所以直接按纯文本展示了 XML 内容。这并不代表 XML 文件损坏也不代表 Claude 输出有问题只是一种正常提示。真正要注意的是编码问题。如果 XML 包含中文文件头需要声明 UTF-8保存时也要用 UTF-8 编码。Windows 下偶尔默认保存成 GBK 或 ANSI打开时就会出现中文乱码或解析异常。用 Python 读写文件时建议显式指定编码with open(output.xml, w, encodingutf-8) as f: f.write(xml_text)另外如果模型输出里包含nbsp;这样的实体而你的解析器不认识也会报错。标准 XML 只内置少量实体其他实体需要先在 DTD 中声明。遇到这种情况最好在写提示词时就要求模型不要输出特殊实体或者在后处理时把常见实体替换掉。5. 常见报错排查从 529 到 400 再到本地命令问题5.1 API Error 529服务端过载应该等多久、重试几次529 是一个比较常见的 API 错误提示信息大致是“overloaded. This is a server-side issue, usually temporary”。意思是服务端当前负载过高问题不在你的代码不在 API Key也不在 XML 格式。这种错误通常是临时的。我一般会采用指数退避重试第一次等 1 秒第二次等 2 秒第三次等 4 秒最多重试 5 次左右。如果持续报 529说明并发请求可能太集中可以降低并发数或者错峰提交。不要把 529 当成 bug 去反复调试。先看时间窗口内是否有大量请求发出如果是批量任务给每批请求之间留一点间隔如果只是单条请求等几秒再试。5.2 API Error 400最大上下文长度超限怎么办网络热词里有一条很典型api error: 400 this models maximum context length is 1048576 tokens。这类报错表示你发送的 prompt 加上输出预留的总 token 数超过了模型支持的上下文长度。很多人以为是单条消息太长其实上下文长度包含了好几部分系统提示词多轮对话里全部历史消息当前请求里的 XML 模板和业务数据输出预留的max_tokens可能存在的工具定义或结构化输出限制解决办法不是只调一个参数而是按顺序处理先压缩历史消息只保留必要上下文。再检查 XML 数据去掉不用的节点或者把大文本拆分。降低max_tokens但要注意别把输出空间压得太小导致内容被截断。换个支持更长上下文的模型以实际可用的模型为准。如果任务本身需要很长的数据不要一次全塞进去。可以先把文档切块分别让 Claude 提取局部信息再汇总。XML 在这时候不是帮倒忙它反而能让你每个切块都有固定结构方便后续合并。5.3 Claude 命令无法识别PATH 与安装方式检查前文提到过 Windows 下claude命令无法识别的问题。实际排查时我建议按这个顺序看在相同终端里直接执行claude --version如果还是报“不是内部或外部命令”说明命令不在 PATH。执行where claude看能否找到命令路径。找不到就说明安装位置没有被系统索引。检查安装工具是否正常。如果是通过 Node 生态安装的执行node -v确认 Node 可用。确认安装命令确实执行成功。有些安装输出会在最后提示“运行以下命令设置 PATH”很多人都忽略了。重启终端或者重启 VSCode 窗口再试一次。这类问题最大难点是环境差异。你的系统、终端、包管理器、权限都不一样直接套别人的命令不一定适用。最稳妥的方式是安装后立即查看安装日志里的提示按提示补 PATH。6. 实战边界XML 方案什么时候适用什么时候该换回 JSON6.1 适合 XML 的典型任务如果你正在准备 Claude Certified Architect 相关的项目实践可以重点看这几类任务第一类是文档抽取。合同、简历、发票、简历这类文本层级明显用 XML 模板比自然语言描述更清晰。你可以让 Claude 按预设节点返回再用 XML 解析器入库。第二类是配置模板生成。把一段配置要求写成 XML让 Claude 按节点填充。后续程序可以直接读取 XML 配置不需要额外做格式转换。第三类是日志标注和指令编排。一个任务里可能包含多个步骤用 XML 把步骤和数据分开模型在响应时就不容易把步骤说明当成数据处理。这类任务之所以适合 XML是因为它们都需要“边界”和“层级”。XML 的标签恰好能提供这两样东西。6.2 不适合 XML 的场合XML 不是万能药。很多场景用 JSON 反而更省事。如果你的下游系统只接受 JSON那就不要为了用 XML 而用 XML。Claude API 完全能直接输出 JSON只要你在提示词里明确字段和格式即可。如果业务数据是大量数组比如一个订单里有 100 个商品XML 会变得非常冗长。JSON 数组在这种场景下更简洁转 Python 对象也更容易。如果团队对接口要求严格类型校验比如字段必须是数字、布尔值JSON Schema 的生态更成熟。XML 虽然也有 XSD但很多开发团队不熟悉维护成本会高一些。还有一类安全场景要注意如果 XML 来源不可信解析时不要启用外部实体。历史上有过通过外部实体读取本地文件的安全问题。在 Claude API 场景里解析模型返回的 XML 通常风险较低但如果你把 XML 数据再传给其他系统就要严格关闭外部实体支持。6.3 给认证学习和项目落地的一句话建议我个人的建议是先把单条 XML 请求跑稳再设计批量流程。不要一上来就想着“所有任务都用 XML”。你先选一个结构简单、字段固定的任务比如从一条订单文本里提取三个字段跑通之后再扩展到更复杂的层级。同时把 XML 模板当作代码来管理。模板改动会影响所有下游解析逻辑所以最好有版本记录。批量任务开始前先用小样本验证字段完整性、XML 合法性和运行耗时。日志里要能清楚看到每次请求的原始输出这样出了问题才能定位是模型回答的问题还是提示词结构的问题还是解析代码的问题。整套流程踩过几次之后你会发现很多报错并不是 Claude 能力不够而是环境、格式、上下文和重试策略没处理好。把 XML 这块准备扎实后面做复杂自动化流程会省很多事。