Claude Platform Docs
MessagesModellfähigkeiten

Quellenangaben

Verankere Claudes Antworten in deinen Quelldokumenten. Citations geben die exakten Passagen zurück, die jede Aussage stützen, sodass du Antworten überprüfen und Quellen für deine Nutzer sichtbar machen kannst.

Claude kann detaillierte Citations bereitstellen, wenn Fragen zu Dokumenten beantwortet werden, und hilft dir so, die Quellen hinter jeder Antwort nachzuverfolgen und zu überprüfen.

Alle aktiven Modelle unterstützen Citations.

Das folgende Beispiel zeigt, wie du Citations für ein reines Textdokument mit der Messages API aktivierst:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": "The grass is green. The sky is blue.",
                    },
                    "title": "My Document",
                    "context": "This is a trustworthy document.",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "What color is the grass and sky?"},
            ],
        }
    ],
)
print(response)

Wie Citations funktionieren

Citations funktionieren in drei Phasen:

  1. Du stellst Dokumente bereit und aktivierst Citations

    • Füge Dokumente in einem der unterstützten Formate ein: PDFs, reiner Text oder benutzerdefinierte Inhalte.
    • Setze citations.enabled=true für jedes deiner Dokumente. Eine Anfrage kann Dokumente mit aktivierten Citations nicht mit Dokumenten ohne aktivierte Citations mischen.
    • Claude kann Text zitieren, aber keine Bilder.
  2. Die API verarbeitet die Dokumente

    • Dokumentinhalte werden „gechunkt“, um die minimale Granularität möglicher Citations zu definieren. Zum Beispiel ermöglicht das Chunking nach Sätzen Claude, einen einzelnen Satz zu zitieren oder mehrere aufeinanderfolgende Sätze zu verketten, um einen Absatz oder eine längere Passage zu zitieren.
      • Für PDFs: Die API extrahiert Text wie in PDF-Unterstützung beschrieben und chunkt ihn in Sätze. Claude kann keine Bilder in PDFs zitieren.
      • Für reine Textdokumente: Die API chunkt den Inhalt in Sätze.
      • Für benutzerdefinierte Inhaltsdokumente: Die API verwendet deine Inhaltsblöcke unverändert und führt kein weiteres Chunking durch.
  3. Claude antwortet mit Citations

    • Eine Antwort kann mehrere Textblöcke enthalten. Jeder Textblock kann eine Aussage von Claude und eine Liste von Citations enthalten, die diese stützen.
    • Citations verweisen auf bestimmte Stellen in Quelldokumenten. Das Format einer Citation hängt vom Typ des Dokuments ab, das Claude zitiert.
      • Für PDFs: Citations enthalten den Seitenzahlbereich (1-indiziert).
      • Für reine Textdokumente: Citations enthalten den Zeichenindexbereich (0-indiziert).
      • Für benutzerdefinierte Inhaltsdokumente: Citations enthalten den Inhaltsblock-Indexbereich (0-indiziert), der der ursprünglich bereitgestellten Inhaltsliste entspricht.
    • Dokumentindizes werden bereitgestellt, um die Referenzquelle anzugeben, und sind 0-indiziert gemäß der Liste aller Dokumente in deiner ursprünglichen Anfrage.

Zitierbare versus nicht zitierbare Inhalte

  • Text, der innerhalb des source-Inhalts eines Dokuments gefunden wird, kann zitiert werden.
  • title und context sind optionale Felder, die an das Modell übergeben, aber nicht für zitierte Inhalte verwendet werden.
  • title ist in der Länge begrenzt, daher ist das context-Feld nützlich, um Dokumentmetadaten als Text oder als JSON-String zu speichern.

Citation-Indizes

  • Dokumentindizes sind 0-indiziert aus der Liste aller Dokumentinhaltsblöcke in der Anfrage (über alle Nachrichten hinweg).
  • Zeichenindizes sind 0-indiziert mit exklusiven Endindizes.
  • Seitenzahlen sind 1-indiziert mit exklusiven Endseitenzahlen.
  • Inhaltsblock-Indizes sind 0-indiziert mit exklusiven Endindizes aus der im benutzerdefinierten Inhaltsdokument bereitgestellten content-Liste.

Token-Kosten

  • Das Aktivieren von Citations führt zu einem leichten Anstieg der Input-Tokens aufgrund von Ergänzungen des System-Prompts und des Dokument-Chunkings.
  • Die Zitatfunktion ist jedoch sehr effizient in Bezug auf Output-Token. Intern gibt das Modell Zitate in einem standardisierten Format aus, und diese Zitate werden anschließend in zitierten Text und Indizes zur Position im Dokument geparst. Das Feld cited_text wird der Einfachheit halber bereitgestellt und zählt nicht zu den Output-Token.
  • Wenn cited_text in nachfolgenden Gesprächsrunden zurückgegeben wird, zählt es ebenfalls nicht zu den Input-Tokens.

Funktionskompatibilität

Citations funktionieren mit anderen API-Funktionen, einschließlich Prompt-Caching, Token-Zählung und Batch-Verarbeitung.

Strukturierte Daten mit Citations erhalten

Um für jeden extrahierten Wert eine Citation zu erhalten, fordere Claude auf, mit einer Zeile pro Feld zu antworten. Parse die Zeilen dann in deinem Code zu strukturierten Daten.

Vermeide Benutzer- oder System-Prompts, die ausschließlich JSON anfordern, wie etwa „Gib nur ein JSON-Objekt zurück, keinen anderen Text.“ Eine Anfrage mit einem solchen Prompt ist erfolgreich, aber die Antwort enthält möglicherweise nur wenige oder gar keine Citations.

Der folgende Prompt fragt zwei Felder aus dem reinen Textdokument im Beispiel oben auf dieser Seite ab. Sende ihn anstelle der Frage aus diesem Beispiel:

Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.

In der folgenden Antwort hat jeder Wert seine eigenen Citations:

{
  "content": [
    { "type": "text", "text": "grass_color: " },
    {
      "type": "text",
      "text": "green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green. ",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": "\nsky_color: " },
    {
      "type": "text",
      "text": "blue",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The sky is blue.",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 20,
          "end_char_index": 36
        }
      ]
    }
  ]
}

Um die Antwort zu parsen, befolge diese Schritte:

  1. Lies die text-Blöcke der Reihe nach und füge den Text jedes Blocks der aktuellen Zeile hinzu. Beginne bei jedem Zeilenumbruchzeichen eine neue Zeile.
  2. Hänge die citations jedes Blocks an jede Zeile an, die einen Teil seines Textes enthält. Ein zitierter Block kann nur den Wert enthalten, wie in diesem Beispiel, oder eine ganze Zeile.
  3. Überspringe Zeilen, die keinen Doppelpunkt enthalten. Teile jede verbleibende Zeile an ihrem ersten Doppelpunkt in einen Feldnamen und einen Wert auf und entferne bei beiden die Leerzeichen am Anfang und Ende. Überspringe Zeilen, deren Name keinem deiner Felder entspricht, wie etwa eine abschließende Anmerkung.
  4. Prüfe, ob jedes Feld einen Wert und mindestens eine Citation hat. Die API garantiert keines von beiden.

Prompt-Caching mit Citations verwenden

Die in Antworten generierten Citation-Blöcke können nicht direkt gecacht werden, aber die Quelldokumente, auf die sie verweisen, können gecacht werden. Um die Leistung zu optimieren, wende cache_control auf deine obersten Dokumentinhaltsblöcke an.

client = anthropic.Anthropic()

# Langer Dokumentinhalt (zum Beispiel technische Dokumentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": long_document,
                    },
                    "citations": {"enabled": True},
                    "cache_control": {
                        "type": "ephemeral"
                    },  # Cache the document content
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?",
                },
            ],
        }
    ],
)
print(response)

In diesem Beispiel:

  • Der Dokumentinhalt wird mit cache_control auf dem Dokumentblock gecacht.
  • Citations sind für das Dokument aktiviert.
  • Claude kann Antworten mit Citations generieren und gleichzeitig vom gecachten Dokumentinhalt profitieren.
  • Nachfolgende Anfragen, die dasselbe Dokument verwenden, profitieren vom gecachten Inhalt.

Dokumenttypen

Auswahl eines Dokumenttyps

Für Citations werden drei Dokumenttypen unterstützt. Dokumente können direkt in der Nachricht bereitgestellt werden (base64, Text oder URL) oder über die Files API hochgeladen und per file_id referenziert werden:

TypAm besten geeignet fürChunkingCitation-Format
Reiner TextEinfache Textdokumente, ProsaSatzZeichenindizes (0-indiziert)
PDFPDF-Dateien mit TextinhaltSatzSeitenzahlen (1-indiziert)
Benutzerdefinierter InhaltListen, Transkripte, spezielle Formatierung, granularere CitationsKein zusätzliches ChunkingBlockindizes (0-indiziert)

Reine Textdokumente

Reine Textdokumente werden automatisch in Sätze gechunkt. Du kannst sie inline oder per Referenz mit ihrer file_id bereitstellen:

Eine vollständige Anfrage mit reinem Text findest du im ersten Beispiel auf dieser Seite. Der Dokumentblock verwendet eine text-Quelle:

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "Plain text content..."
  },
  "title": "Document Title",
  "context": "Context about the document that will not be cited from",
  "citations": { "enabled": true }
}

PDF-Dokumente

Du kannst PDF-Dokumente als base64-codierte Daten, als URL oder per file_id bereitstellen. Die API extrahiert ihren Text und chunkt ihn in Sätze.

Claude kann keine Bilder zitieren, daher kann es kein PDF zitieren, das ein Scan eines Dokuments ist und keinen extrahierbaren Text enthält.

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

Benutzerdefinierte Inhaltsdokumente

Benutzerdefinierte Inhaltsdokumente geben dir Kontrolle über die Granularität der Citations. In der source des Dokuments ist type gleich content, und das Feld content enthält eine Liste von Inhaltsblöcken. Die API führt kein weiteres Chunking durch: Jeder Textblock, den du bereitstellst, ist ein Chunk, die kleinste Einheit, die Claude zitieren kann.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "content",
                        "content": [
                            {"type": "text", "text": "First chunk"},
                            {"type": "text", "text": "Second chunk"},
                        ],
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)


Antwortstruktur

Wenn Citations aktiviert sind, enthalten Antworten mehrere Textblöcke mit Citations:

{
  "content": [
    { "type": "text", "text": "According to the document, " },
    {
      "type": "text",
      "text": "the grass is green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green. ",
          "document_index": 0,
          "document_title": "Example Document",
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": " and " },
    {
      "type": "text",
      "text": "the sky is blue",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The sky is blue.",
          "document_index": 0,
          "document_title": "Example Document",
          "start_char_index": 20,
          "end_char_index": 36
        }
      ]
    },
    {
      "type": "text",
      "text": ". Information from page 5 states that "
    },
    {
      "type": "text",
      "text": "water is essential",
      "citations": [
        {
          "type": "page_location",
          "cited_text": "Water is essential for life.",
          "document_index": 1,
          "document_title": "PDF Document",
          "start_page_number": 5,
          "end_page_number": 6
        }
      ]
    },
    {
      "type": "text",
      "text": ". The custom document mentions "
    },
    {
      "type": "text",
      "text": "important findings",
      "citations": [
        {
          "type": "content_block_location",
          "cited_text": "These are important findings.",
          "document_index": 2,
          "document_title": "Custom Content Document",
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Streaming-Unterstützung

Bei Streaming-Antworten kommen Citations als citations_delta-Delta-Typ innerhalb von content_block_delta-Events an. Jedes Delta enthält eine einzelne Citation, die zur citations-Liste des aktuellen text-Inhaltsblocks hinzugefügt wird.

Nächste Schritte

Lerne den Ereignisablauf und die anderen Inhaltsblock-Delta-Typen kennen, die zusammen mit citations_delta eintreffen.

Übergib Suchergebnisse aus deiner RAG-Pipeline als erstklassige Inhaltsblöcke mit integrierter Citation-Unterstützung.

Erfahre, wie Claude Text aus PDFs extrahiert und wie seitenbasierte Citations auf deine Quelldateien zurückverweisen.

Lade Dokumente einmal hoch und referenziere sie per file_id über mehrere Citation-Anfragen hinweg.

Verfügbarkeit

Quellenangaben
APIs
  • Messages API
  • Managed Agents Nicht unterstützt
Modelle
  • Alle Modelle

Zutreffende Endpunkte

  • /v1/messages
Zero Data RetentionBerechtigt

Ausgenommen: Abgedeckte Modelle

HIPAABerechtigt

War diese Seite hilfreich?