Skip to main content

Zitate

Zitate verknüpfen Textstellen in einer Assistentenantwort mit den Quellen, die diese belegen. Aktivieren Sie enableCitations, wenn Sie eine Sitzung erstellen oder fortsetzen, und lesen Sie dann die citations-Nutzlast bei assistant.message-Ereignissen, um Fußnoten, Quelllisten oder Inline-Links darzustellen.

Warnung

Zitate sind experimentell. Der Optionsname, die Ereignisnutzlast und die Anbieterabdeckung können sich in einer zukünftigen Version ändern.

Funktionsweise von Zitaten

Zitate werden vom Modellanbieter erstellt, nicht vom SDK. Der Fluss hat drei Teile:

  1. Ihre Anwendung stellt zitierbares Material bereit, z. B. einen Dokumentanhang oder das Ergebnis eines Tools, das Quellmaterial enthält.
  2. Die Laufzeit kennzeichnet dieses Material bei der Übertragung als zitatierbar, wenn enableCitations aktiviert ist. Bei Anthropic-Modellen werden Dateianhänge als document-Blöcke mit aktivierten Quellenangaben gesendet.
  3. Das Modell gibt Zitatmetadaten zurück, und die Laufzeit normalisiert es in ein anbieteragnostisches citations Objekt für das endgültige assistant.message Ereignis.

Der Anbietersupport ist eingeschränkt. Das provider-Feld in jedem Quelldatensatz gibt an, woher das Zitat stammt:

AnbieterwertBedeutung
anthropicZitat, das durch eine Antwort eines Anthropic-(Claude-)Modells erzeugt wurde
openaiZitat aus einer Antwort eines OpenAI-Modells
clientZur Laufzeit aus der Toolausgabe synthetisiertes Zitat

Hinweis

enableCitations Das Aktivieren garantiert nicht, dass eine Antwort Zitate enthält. Modelle geben sie nur dann aus, wenn die Antwort auf zitierfähigem Quellenmaterial basiert. Behandeln Sie das citations Feld immer als optional.

Aktivieren von Zitaten in einer Sitzung

Legen Sie die Option für die Sitzungserstellung fest, und legen Sie sie erneut beim Fortsetzen fest, wenn Nach einem Neustart Zitate angezeigt werden sollen.

Codesprachen navigation

TypeScript
const session = await client.createSession({
    onPermissionRequest: approveAll,
    enableCitations: true,
});

const resumed = await client.resumeSession(session.sessionId, {
    onPermissionRequest: approveAll,
    enableCitations: true,
});

Lesen von Zitaten aus Assistentennachrichten

Zitate treffen erst beim abschließenden assistant.message-Ereignis ein, nicht bei assistant.message_delta-Ereignissen. Warten Sie auf die endgültige Nachricht, bevor Sie Quellmarkierungen rendern.

Codesprachen navigation

TypeScript
session.on((event) => {
    if (event.type !== "assistant.message" || !event.data.citations) {
        return;
    }

    const { sources, spans } = event.data.citations;
    const sourceById = new Map(sources.map((source) => [source.id, source]));

    for (const span of spans) {
        const quoted = event.data.content.slice(span.startIndex, span.endIndex);
        for (const reference of span.references) {
            const source = sourceById.get(reference.sourceId);
            const label = source?.title ?? source?.url ?? source?.path ?? source?.id;
            console.log(`"${quoted}" — ${label}`);
        }
    }
});

Referenz zur Zitatnutzlast

Das citations Objekt trennt deduplizierten Quellen von den Textspannen, die auf sie verweisen, sodass eine Quelle, die fünfmal zitiert wird, in sources nur einmal erscheint.

TypFeldDescription
CitationssourcesDeduplizierte Menge von Quellen, auf die durch die Zitationsspannen verwiesen wird
CitationsspansTextabschnitte des generierten Textes, die mit ihren zugehörigen Quellen annotiert sind
CitationSourceidStabiler, auf einen Turn begrenzter Identifier, referenziert durch CitationReference.sourceId
CitationSourceproviderSystem, das das Zitat erzeugt hat: anthropic, , openaioder client
CitationSourcetitle?Lesbarer Titel der Quelle
CitationSourceurl?URL der Quelle, wenn es sich um eine Webressource handelt
CitationSourcepath?Dateipfad relativ zum Stammverzeichnis des Agent-Arbeitsbereichs, wenn die Quelle eine Datei ist
CitationSpanstartIndexStartversatz im endgültigen Nachrichteninhalt (UTF-16-Codeeinheiten, nullbasiert, einschließlich)
CitationSpanendIndexEnd-Offset im endgültigen Inhalt der Nachricht (UTF-16-Codeeinheiten, nullbasiert, exklusiv)
CitationSpanreferencesDie Quellen, die diese Spanne unterstützen
CitationReferencesourceIdBezeichner des CitationSource, auf das diese Referenz verweist
CitationReferencecitedText?Exakter Text aus der Quelle, der die Textspanne unterstützt, wenn er vom Modell bereitgestellt wird
CitationReferencelocation?Position innerhalb der Quelle, die die Spanne unterstützt
CitationReferenceproviderMetadata?Anbietereigene Korrelationsdaten, die undurchsichtig durchgegangen werden

Tipp

Span-Offsets werden in UTF-16-Codeeinheiten relativ zur endgültigen content-Zeichenfolge gemessen. TypeScript, Java und .NET Zeichenfolgen sind bereits UTF-16, sodass Sie sie direkt segmentieren können. Python-Zeichenfolgen werden nach Unicode-Codepunkten indiziert, und Zeichenfolgen in Go und Rust sind UTF-8-codiert. Konvertieren Sie den Inhalt daher vor dem Slicing in UTF-16-Codeeinheiten, wie es in den obigen Beispielen geschieht.

Zitatstellen

CitationReference.location ist eine diskriminierte Union mit type als Diskriminator:

LagerplatztypFelderVerwendung
char
startIndex, endIndexZeichenbereich innerhalb des Quelltexts
page
startPage, endPageSeitenbereich innerhalb eines paginierten Dokuments
block
startBlock, endBlockInhaltsblockbereich innerhalb eines strukturierten Dokuments

Bereitstellen zitierfähiger Quellen

Zitate benötigen Quellmaterial, das das Modell attributieren kann. Es gibt zwei Möglichkeiten, sie zu liefern.

Anfügen von Dokumenten an eine Nachricht

Wenn Zitate aktiviert sind und die Sitzung einen Anbieter von Anthropic verwendet, werden Dateianhänge als document-Blöcke mit aktivierter Zitierfunktion gesendet, sodass das Modell Passagen daraus zitieren kann.

await session.sendAndWait({
    prompt: "Summarize the attached PDF and cite the passages you used.",
    attachments: [
        {
            type: "blob",
            data: pdfBase64,
            displayName: "quarterly-report.pdf",
            mimeType: "application/pdf",
        },
    ],
});

Siehe Bildeingabe für die Anhang-API sowie die file- und blob-Anhang-Formen.

Zurückgeben zitatbarer Quellen aus einem Tool

Toolergebnisse enthalten ein experimentelles citableSources-Array. Jeder Eintrag stellt content bereit, auf das sich das Modell beziehen kann, zusammen mit einem id sowie optionalen title, url und path. Diese Quellen werden zusammen mit dem Toolergebnis gespeichert, sodass sie auch nach dem Fortsetzen der Sitzung erhalten bleiben, und auf ihrer Grundlage erstellte Zitate werden mit dem Anbieter client gekennzeichnet.

Limitations

  • Zitate sind in jedem SDK experimentell und unterliegen nicht den Kompatibilitätsgarantien.
  • Die Abdeckung hängt vom Modellanbieter ab. Eine für einen Anbieter ohne Unterstützung für Zitate konfigurierte Sitzung sendet keine citations-Nutzlast.
  • Zitate sind nur im letzten assistant.message-Ereignis enthalten, sodass Streaming-Clients sie während der laufenden Antwort nicht darstellen können.
  • Öffentliche Code- und IP-Duplizierungszitate sind nicht Teil dieser Oberfläche.

Weiterführende Lektüre