Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

collections_search und file_search in der Responses-API

Lektion 11 von 16 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Suche direkt in Gesprächen integrieren
  2. Das collections_search-Werkzeug
  3. Das file_search-Werkzeug
  4. Zwei Mechanismen, zwei Kostenstrukturen
  5. Mehrere Werkzeuge kombinieren
  6. Werkzeugverhalten verfeinern
  7. Kernaussagen

Suche direkt in Gesprächen integrieren

Der Endpunkt POST /v1/documents/search eignet sich gut für isolierte Fragen, überlässt Ihnen jedoch die gesamte Orchestrierungsarbeit: Formulierung der Abfrage, Abruf von Auszügen, Einsetzen in einen Prompt und Aufruf des Modells. Die Responses-API kehrt diese Last um. Indem Sie Ihre Sammlungen als Werkzeug deklarieren, entscheidet Grok, wann gesucht werden soll, wonach gesucht wird und wie die Ergebnisse zu einer Antwort verarbeitet werden. Sie wechseln von einem von Ihnen gesteuerten Pipeline-Ansatz zu einem Assistenten, der Ihre Dokumente selbstständig durchsucht.

Das collections_search-Werkzeug

Sie müssen lediglich ein Objekt zur tools-Liste hinzufügen, um diesen Zugriff zu aktivieren:

response = await client.responses.create(
    model="grok-4.5",
    input="Was ist unser Elterngeldanspruch?",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_rh_policies"]
        }
    ]
)

Hinter diesem einzigen Aufruf analysiert Grok die Frage, formuliert eine auf die Sammlung zugeschnittene Suchabfrage, holt relevante Passagen ab, fasst diese zusammen und verweist auf die verwendeten Dokumente. In der Praxis wird für die obige Frage „Elterngeldanspruch” in col_rh_policies übersetzt, die Absätze aus dem Firmenvertrag beibehalten und eine Anzahl von Tagen zusammen mit der Quelle zurückgegeben, ohne dass Sie eine einzige Zeile Abruffunktionslogik schreiben müssen.

Das file_search-Werkzeug

Das Gegenstück existiert für einzelne Dateien, die nicht in einer Sammlung gespeichert sind. Es muss nicht deklariert werden: Es aktiviert sich automatisch, sobald Ihre Anfrage ein input_file enthält.

response = await client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_file",
            "file_id": "file_contrat_abc"
        },
        {
            "type": "input_text",
            "text": "Enthält dieser Vertrag eine Wettbewerbsklausel?"
        }
    ]
)

Es ist das attachment_search-Werkzeug, das dem file_search entspricht, das im Hintergrund aktiviert wird. Dieses implizite Verhalten erklärt eine häufige Verwirrung: Nutzer fragen sich, warum die Deklaration von file_search in tools scheinbar keine Wirkung zeigt, obwohl sie einfach redundant ist.

Zwei Mechanismen, zwei Kostenstrukturen

Aspektcollections_searchfile_search / attachment_search
QuelleIndexierte Sammlung(en)Einzelne Datei(en)
DeklarationExplizit in toolsAutomatisch mit input_file
IndexierungVorkalkuliertEchtzeit
Kosten2,50 $ / 1.00010,00 $ / 1.000
LeistungSchnell (bestehender Index)Langsamer (Echtzeit-Indexierung)
EinsatzfallDauerhafte WissensdatenbankEinmalige Analyse

Die Zeile „Indexierung” treibt alle anderen Faktoren an. Eine Sammlung wird einmal und für immer indiziert, sodass jede Frage diese Arbeit wiederverwendet: Sie ist schnell und wird mit 2,50 $ pro tausend Aufrufen berechnet. Eine angehängte Datei wird bei jeder Anfrage indiziert, was zu zusätzlichen Latenzen und 10,00 $ pro tausend Aufrufen führt. Der Vertrag, den Ihre Rechtsabteilung einmal analysiert, fällt in die zweite Kategorie; das HR-Repository, das hundertmal täglich abgefragt wird, fällt offensichtlich in die erste.

Mehrere Werkzeuge kombinieren

Der eigentliche Vorteil dieses Ansatzes zeigt sich, wenn Sie Grok mehrere Werkzeuge zur Verfügung stellen und es auswählen lässt, welche für die Frage geeignet sind.

response = await client.responses.create(
    model="grok-4.5",
    input="Vergleichen Sie unsere interne Richtlinie mit den neuesten europäischen Vorschriften zu diesem Thema.",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_politiques_internes"]
        },
        {
            "type": "web_search"
        }
    ]
)

Diese Frage erfordert zwei aufeinanderfolgende Schritte: Grok fragt zunächst die Sammlung ab, um Ihre interne Richtlinie zu finden, startet dann eine Websuche nach aktuellen europäischen Vorschriften und kontrastiert beide in seiner Antwort. Keine Orchestrierung auf Ihrer Seite, kein if-Statement, um zu entscheiden, welche der beiden Quellen relevant ist – und wenn die Frage sich ausschließlich auf Ihre interne Richtlinie konzentriert hätte, würde das Web nicht verwendet werden.

Werkzeugverhalten verfeinern

Drei Parameter ermöglichen es, die in tools deklarierte Suche zu präzisieren.

tools=[
    {
        "type": "collections_search",
        "collection_ids": ["col_docs_1", "col_docs_2"],
        "max_results": 10,
        "retrieval_mode": "hybrid"
    }
]
  • collection_ids: Abfrage mehrerer Sammlungen gleichzeitig
  • max_results: Begrenzung der Anzahl der Ergebnisse zur Reduzierung des injizierten Kontexts
  • retrieval_mode: Auswahl des Suchmodus (hybrid als Standard)

max_results verdient besondere Aufmerksamkeit: Jeder zurückgegebene Auszug beansprucht Kontext und kostet Tokens. Bei einem Support-Assistenten, bei dem Antworten im Allgemeinen in zwei oder drei Passagen passen, reduziert die Senkung des Standardwerts auf fünf Ergebnisse die Kosten, ohne die wahrgenommene Qualität zu beeinträchtigen.

Preise ab dem 5. August 2026 — Preise ändern sich regelmäßig: Prüfen Sie vor jeder Budgetberechnung die aktuellen Preise auf der offiziellen xAI-Modell- und Preis-Seite.

Kernaussagen

  • collections_search ermöglicht es Grok, Ihre Sammlungen während eines Gesprächs automatisch abzufragen
  • file_search / attachment_search aktiviert sich automatisch für einzelne Dateien
  • Sammlungen sind viermal günstiger und schneller als angehängte Dateien
  • Sie können collections_search mit web_search und anderen Werkzeugen kombinieren
  • Grok wählt automatisch die Werkzeuge basierend auf der Frage aus