Claude Citations API 实战：让模型自动标注引用来源，RAG 准确率提升 15%

Claude Citations API 实战让模型自动标注引用来源RAG 准确率提升 15%做 RAG检索增强生成的工程师都遇到过这种灵魂提问“你这个回答到底是从哪段文档里得出来的”这个问题之所以致命是因为模型会自信地引用一段根本不存在的原文。在法律、医疗、金融、合规审计这些场景引用错了不只是难看可能直接出事故。过去大家的解法是在 prompt 里写请用方括号标注你引用了哪段文字然后正则解析。这种方式至少有三个问题模型会编造看似真实但实际不存在的引用编号直接输出原文片段output token 飙升导致成本翻倍解析逻辑脆弱模型偶尔不按格式输出就全崩Anthropic 在 2025 年初推出、2026 年正式 GA 的Citations API给出了官方答案——模型直接返回结构化的引用对象包含字符级偏移、文档索引、原文片段全部由 API 层保证。本文给出 Citations 的完整接入方案、三种文档喂入方式、与传统 prompt 引用的对比、以及一个真实可跑的法律 RAG 例子。一、Citations 到底是什么Citations 是 Anthropic 在messagesAPI 上的一个文档块开关。你把文档作为documentcontent block 传给 Claude并打开citations.enabled true模型回答时就会自动在每个论点后附带一个citation 对象结构如下{type:char_location,cited_text:...被引用的原文片段...,document_index:0,document_title:annual-report-2025.pdf,start_char_index:1024,end_char_index:1180}四个关键属性字段含义cited_text被引用的原文片段不计入 output tokendocument_index第几个文档0-indexedstart_char_index/end_char_index在该文档中的字符偏移type引用粒度类型见下表三种引用粒度粒度适用场景类型字段char_location纯文本文档最精确char_locationpage_locationPDF 文档页级page_locationcontent_block_location自定义文档块最灵活content_block_location为什么比 prompt 工程更靠谱Anthropic 自家的对比评测里Citations 内置版相比 prompt-engineered 版本在召回准确率上提升最高 15%。原因有三个引用指向是 API 强制保证的——start_char_index/end_char_index由系统计算不是模型生成的字符串cited_text不计入 output token——你不再需要为了让模型输出原文而支付额外的 token 费用模型不会再编造——所有 citation 都映射到你提供文档的真实位置二、三种文档喂入方式方式 1Plain Text字符精确引用最适合你已经把文档解析为纯文本需要字符级精确定位。importanthropic clientanthropic.Anthropic(api_keysk-你的密钥,base_urlhttps://gw.claudeapi.com)doc_textopen(contract.txt,r,encodingutf-8).read()responseclient.messages.create(modelclaude-opus-4-7,max_tokens1024,messages[{role:user,content:[{type:document,source:{type:text,media_type:text/plain,data:doc_text,},title:甲方乙方合作协议-2026.txt,citations:{enabled:True}},{type:text,text:这份合同的违约金条款是怎么规定的}]}])返回结构精简版forblockinresponse.content:ifblock.typetext:print(block.text)forcitinblock.citationsor[]:print(f └─ 引自{cit.document_title})print(f 字符 [{cit.start_char_index}:{cit.end_char_index}])print(f 原文{cit.cited_text[:80]}...)输出示例违约方需向守约方支付合同总金额 20% 的违约金并在 30 日内一次性支付。 └─ 引自 甲方乙方合作协议-2026.txt 字符 [4128:4280] 原文第十二条 违约责任违约方应当向守约方支付合同总金额百分之二十的违约金...方式 2PDF页级引用最适合扫描件、含图表的财报、合同原件。模型会自动 OCR 视觉理解引用粒度精确到 PDF 的页号。importbase64withopen(annual-report.pdf,rb)asf:pdf_b64base64.standard_b64encode(f.read()).decode(utf-8)responseclient.messages.create(modelclaude-opus-4-7,max_tokens2048,messages[{role:user,content:[{type:document,source:{type:base64,media_type:application/pdf,data:pdf_b64,},title:财报-2025.pdf,citations:{enabled:True}},{type:text,text:现金流量表中经营性净现金流是多少}]}])PDF 模式下 citation 会带start_page_number/end_page_number1-indexed经营性净现金流为 28.5 亿元同比增长 12%。 └─ 引自 财报-2025.pdf 第 32-32 页如果文档已经上传到 Files API可以用file_id引用避免每次 base64 重传。方式 3Custom Content最灵活RAG 必选最适合你自己分了块的 RAG 场景想精确控制每个 chunk 的边界。chunks[第一条 本协议由甲方与乙方于 2026 年 1 月 1 日签订...,第十二条 违约责任违约方应当向守约方支付合同总金额百分之二十的违约金...,第十五条 争议解决因本协议产生的任何争议...]responseclient.messages.create(modelclaude-opus-4-7,max_tokens1024,messages[{role:user,content:[{type:document,source:{type:content,content:[{type:text,text:chunk}forchunkinchunks]},title:合同条款-命中片段,citations:{enabled:True}},{type:text,text:违约金有多少争议怎么解决}]}])返回的 citation 会带start_block_index/end_block_index告诉你引用的是数组里第几块。这种模式特别适合向量检索后给 top-K 个 chunk每个 chunk 是一个 block模型回答时直接告诉你它引用了哪个 block多文档汇总可以把不同来源的文档片段合并成一个 document引用结构清晰三、Node.js / cURL 等价实现Node.js / TypeScriptimportAnthropicfromanthropic-ai/sdk;importfsfromfs;constclientnewAnthropic({apiKey:sk-你的密钥,baseURL:https://gw.claudeapi.com,});constdocTextfs.readFileSync(contract.txt,utf-8);constresponseawaitclient.messages.create({model:claude-opus-4-7,max_tokens:1024,messages:[{role:user,content:[{type:document,source:{type:text,media_type:text/plain,data:docText},title:甲方乙方合作协议.txt,citations:{enabled:true},},{type:text,text:违约金条款是}]}]});for(constblockofresponse.content){if(block.typetext){console.log(block.text);for(constcitof(blockasany).citations||[]){console.log(└─${cit.document_title}[${cit.start_char_index}:${cit.end_char_index}]);}}}cURLcurlhttps://gw.claudeapi.com/v1/messages\-Hx-api-key: sk-你的密钥\-Hanthropic-version: 2023-06-01\-Hcontent-type: application/json\-d{ model: claude-opus-4-7, max_tokens: 1024, messages: [{ role: user, content: [ { type: document, source: {type: text, media_type: text/plain, data: 本协议自 2026 年 1 月 1 日生效...}, title: 合同.txt, citations: {enabled: true} }, {type: text, text: 协议什么时候生效} ] }] }四、Citations vs Prompt 工程引用六维对比维度传统 Prompt 引用Citations API引用可靠性模型可能编造API 保证位置真实Output token 成本引用文本计入输出昂贵cited_text 不计费字符级偏移需自己解析内置start_char_index多文档支持需要复杂 prompt 描述自动document_index实现复杂度自写正则解析SDK 直接拿对象召回准确率基线15%Anthropic 内测数据对法律、医疗、金融、政府类客户这六个维度里前两个就足够说服技术选型。五、Web Search 自带 Citations不需要开关如果你用的是 Anthropic 原生web_search工具web_search_20260209是 2026 年的最新版本支持 dynamic filteringcitations 是默认强开的——你不需要在文档块里加citations.enabled每个网页结果都会自带web_search_result_location类型的 citation。responseclient.messages.create(modelclaude-opus-4-7,max_tokens2048,tools[{type:web_search_20260209,name:web_search}],messages[{role:user,content:2026 年 Anthropic 估值是多少给出来源。}])Anthropic 的服务条款明确直接把 API 输出展示给最终用户时必须保留 citation 指向原始来源——这条对做搜索/问答类产品的团队尤其重要别因为美观需求把 url 字段藏起来。cited_text、title、url 字段同样不计入 token 计费。六、踩坑清单坑 1Citations 与 streaming 一起用要小心累积。流式返回时每个 text delta 可能携带 citation_delta需要在客户端按 block 累积不能简单拼接字符串。SDK 已封装好自写客户端要注意。坑 2document 必须有 title。实测不写 title 也能跑通但所有 citation 的document_title字段会为空前端展示会很难看。养成传 title 的习惯。坑 3Custom content 模式下block 太碎会影响召回。把一份合同拆成 200 个 8 字 block模型反而会看不清。建议每个 block 保持 100-500 字的语义完整段落太碎反而降低准确率。坑 4不是所有模型都返回引用粒度一致。Opus 4.7 / Sonnet 4.6 / Haiku 4.5 都支持 Citations但 Haiku 在多文档复杂场景下偶尔会漏引用。重要场景请用 Opus 4.7 或 Sonnet 4.6。坑 5Citations 不等于防幻觉。模型仍然可能误读文档语义。Citations 只保证引用位置真实存在不保证引用解读正确。生产环境建议二次校验把 cited_text 和模型回答做语义一致性检查。七、一个完整的法律 RAG 端到端示例把上面的 Custom Content 模式串起来做一个最小可跑的法律咨询助手importanthropicfromtypingimportList clientanthropic.Anthropic(api_keysk-你的密钥,base_urlhttps://gw.claudeapi.com)# 假设你有一个向量数据库 (Pinecone / Weaviate / Chroma)defretrieve_chunks(query:str,k:int5)-List[dict]:返回 top-k 法条片段# ... 你的向量检索代码return[{law:民法典,article:第585条,text:当事人可以约定一方违约时...},{law:合同法,article:第114条,text:约定的违约金低于造成的损失...},# ...]defanswer_with_citations(question:str):chunksretrieve_chunks(question)responseclient.messages.create(modelclaude-opus-4-7,max_tokens2048,system你是一个严谨的法律咨询助手。回答必须仅基于提供的法条片段不允许引用未提供的法律。,messages[{role:user,content:[{type:document,source:{type:content,content:[{type:text,text:f【{c[law]}{c[article]}】{c[text]}}forcinchunks]},title:命中的法律条文,citations:{enabled:True}},{type:text,text:question}]}])# 结构化输出附带引用result{answer:,citations:[]}forblockinresponse.content:ifblock.typetext:result[answer]block.textforcitin(block.citationsor[]):idxcit.start_block_index result[citations].append({law:chunks[idx][law],article:chunks[idx][article],cited_text:cit.cited_text,})returnresultprint(answer_with_citations(约定违约金过低能否调整))输出结构示例{answer:根据法律规定约定违约金低于造成损失的可以请求法院或仲裁机构予以增加。,citations:[{law:合同法,article:第114条,cited_text:约定的违约金低于造成的损失的当事人可以请求人民法院或者仲裁机构予以增加...}]}这样的输出可以直接喂给前端做鼠标悬停展示原文或者导出审计报告工程友好度远超 prompt 工程版本。小结Citations 是 Anthropic 官方对防幻觉 可审计需求的标准答案比 prompt 工程引用更可靠、更省钱、更易工程化三种粒度char_location纯文本、page_locationPDF、content_block_location自定义 chunk不计费的省钱细节cited_text 不计入 output token生产建议重要场景用 Opus 4.7 / Sonnet 4.6document 一定要传 titlecustom block 保持语义完整段落重要提醒Citations 只保证引用位置真实不保证语义解读正确注意 Citations 是 Anthropic 原生能力只在 messages API 路径上工作OpenAI 兼容的 chat/completions 接口不支持。国内开发者如果直连api.anthropic.com不通可以通过 claudeapi.com 把base_url改成https://gw.claudeapi.comCitations 全部能力同步可用。参考资料Citations API 官方文档、Anthropic Citations 发布博客。