Einen n8n-Workflow für Dokumentenfragen mit menschlicher Freigabe und einer OpenAI-kompatiblen API erstellen

Die Entscheidung: Wo sollte die Freigabe erfolgen?

Fügen Sie bei Fragen zu Dokumenten nicht allein deshalb eine menschliche Freigabe hinzu, weil ein KI-Modell beteiligt ist. Setzen Sie sie an dem Punkt ein, an dem der Workflow auf sensible Inhalte zugreifen oder eine prüfungsbedürftige Antwort veröffentlichen könnte.

Ein sinnvolles n8n-Design sieht so aus:

1. Eine Frage empfangen.
2. Einen AI Agent eine Dokumentensuchanfrage vorbereiten lassen.
3. Vor der Ausführung des Suchtools eine menschliche Freigabe einholen, wenn das Korpus sensibel ist, die Abfrage eingeschränkte Inhalte offenlegen könnte oder die Suche operative Kosten verursacht.
4. Passagen mit Quellenmetadaten abrufen.
5. Das Modell anweisen, nur anhand dieser Passagen zu antworten.
6. Eine Antwort mit Quellenverweisen zurückgeben oder den Entwurf vor der Veröffentlichung an eine zweite Freigabestufe weiterleiten.

Damit werden drei Entscheidungen getrennt, die häufig miteinander verwechselt werden: Ist die Frage zulässig, ist der Abrufvorgang zulässig und ist die generierte Antwort bereit für den Versand?

n8n beschreibt die menschliche Prüfung für bestimmte Tools, die mit einem AI Agent verbunden sind. Wenn die Prüfung aktiviert ist, pausiert der Workflow, und eine prüfende Person kann den vorgeschlagenen Tool-Aufruf genehmigen oder ablehnen. Details zum unterstützten Verhalten und zu den Freigabekanälen finden Sie in der n8n-Dokumentation zur menschlichen Prüfung.

Voraussetzungen

Sie benötigen:

• Einen n8n-Workflow mit einem AI Agent und einer Modellverbindung.
• Eine durchsuchbare Dokumentenquelle, etwa einen Vektorspeicher, eine Datenbank oder einen internen Suchdienst. Der genaue Connector ist anwendungsspezifisch und wird auf der genannten n8n-Seite nicht festgelegt.
• Ein Abruftool, das Text zusammen mit Dokumentmetadaten zurückgibt.
• Einen in n8n konfigurierten Freigabekanal. Die Dokumentation nennt Chat, Slack, Discord, Telegram, Microsoft Teams, Gmail, WhatsApp Business Cloud, Google Chat und Microsoft Outlook als verfügbare Kanäle.
• Zugriff auf einen OpenAI-kompatiblen API-Endpunkt. OneMux bietet Zugriff auf führende KI-Modelle über eine OpenAI-kompatible API. Nutzen Sie den OneMux-Schnellstart und die API-Dokumentation, um die aktuellen Angaben zu Endpunkt und Authentifizierung zu erhalten.

Die Kompatibilität ist bedingt. Prüfen Sie vor der Verbindung mit n8n, ob der ausgewählte Endpunkt das von Ihrem n8n-Node oder HTTP-Request verwendete Anfrageformat, die Modellkennung, die Authentifizierungsmethode, das Streaming-Verhalten, Tool-Aufrufe und die Parameter unterstützt. Dieser Artikel behauptet nicht, dass ein bestimmtes OneMux-Modell oder eine bestimmte n8n-Konfiguration getestet wurde.

Empfohlene Struktur des n8n-Workflows

Strukturieren Sie den Workflow in fünf logische Phasen:

1. Frage erfassen und normalisieren

Verwenden Sie den von Ihnen gewählten n8n-Einstiegspunkt, um eine Frage zu empfangen und in ein kleines Objekt zu normalisieren, das die Nutzerfrage, den Kontext des Nutzers oder Arbeitsbereichs sowie optional einen Filter für den Dokumentbereich enthält.

Übernehmen Sie uneingeschränkten Nutzereingabetext nicht direkt in eine Systemanweisung. Behandeln Sie die Frage als Daten und definieren Sie das Verhalten des Agenten getrennt. Wenn der Workflow Grenzen für Mandanten oder Abteilungen unterstützt, übergeben Sie diese Grenzen als kontrollierte Felder an das Abruftool, statt dem Modell zu erlauben, sie selbst zu erfinden.

2. Dokumentensuchtool hinzufügen

Verbinden Sie ein Suchtool mit dem AI Agent. Seine Eingabe sollte eng gefasst und eindeutig sein, zum Beispiel:

{
  "query": "string",
  "document_scope": "string or controlled value",
  "max_results": "integer"
}

Das Suchergebnis sollte genügend Metadaten für eine aussagekräftige Quellenangabe bewahren:

{
  "text": "Approved passage from the document",
  "title": "Document title",
  "url": "Document URL or stable identifier",
  "page": "Page number when available",
  "section": "Section heading when available",
  "chunk_id": "Stable passage identifier"
}

Die oben genannten Feldnamen sind ein Implementierungsmuster und keine Aussage über ein erforderliches n8n-Schema. Passen Sie sie an den von Ihnen verwendeten Connector oder Dienst an. Entscheidend ist die Nachvollziehbarkeit: Der Antwortgenerator muss die Passage und ihre Herkunft gemeinsam erhalten.

3. Menschliche Prüfung um das ausgewählte Tool legen

Öffnen Sie im AI Agent den Bereich „Tools“, suchen Sie den Abschnitt „Human review“, wählen Sie einen Freigabekanal aus und verbinden Sie das Dokumentensuchtool mit diesem Prüfschritt. Konfigurieren Sie die Anmeldedaten und Einstellungen des ausgewählten Kanals in n8n.

Eine Nachricht an die prüfende Person kann die geplante Aktion und ihre Parameter anzeigen. In der n8n-Dokumentation werden dafür die Variablen $tool.name und $tool.parameters beschrieben. Eine praktische Nachricht ist:

The AI wants to use {{ $tool.name }} with these parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

Approve only if the query and document scope are appropriate for this request.

Das ist besonders nützlich, wenn die prüfende Person einen riskanten Umfang erkennen muss, etwa bei einer Anfrage, die offenbar die Dokumente eines anderen Teams durchsuchen soll. Bei gewöhnlicher öffentlicher Dokumentation kann eine Freigabe für jede Suche unnötige Reibung erzeugen. Lassen Sie den Abruf in diesem Fall automatisch erfolgen und legen Sie die Freigabe auf ein separates Tool, das die endgültige Antwort veröffentlicht oder versendet.

4. OpenAI-kompatiblen Modell-Endpunkt verbinden

Konfigurieren Sie die Modellebene anhand der von Ihrem Anbieter dokumentierten Endpunkt- und Zugangsdaten. Beginnen Sie bei OneMux mit dem OneMux-Schnellstart, wählen Sie ein Modell aus, das die von Ihrem n8n-Node benötigten Funktionen unterstützt, und prüfen Sie Modellkennung sowie Anfrageparameter.

Eine generische Anfrageform kann wie folgt aussehen, ist jedoch nur beispielhaft und kein getestetes OneMux-Rezept:

curl https://api.example-provider.invalid/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer only from supplied document passages."},
      {"role": "user", "content": "What does the document say about retention?"}
    ]
  }'

Ersetzen Sie die Platzhalter-URL, die Schlüsselverwaltung und die Modell-ID durch die Werte aus der aktuellen Dokumentation des Anbieters. Legen Sie keine Zugangsdaten in Workflow-Exporten oder für Nutzer sichtbaren Freigabenachrichten offen. Wenn der n8n-Modell-Node einen Parameter erwartet, den der Endpunkt nicht unterstützt, verwenden Sie eine kompatible Konfiguration oder ein auf HTTP Request basierendes Design nur dann, wenn Ihre Anforderungen an Sicherheit und Antwortverarbeitung erfüllt sind.

5. Quellenangaben im Antwort-Prompt erzwingen

Übergeben Sie dem Modell die abgerufenen Passagen in einem klar abgegrenzten Kontext und verlangen Sie für jede wesentliche Aussage eine Quellenangabe. Zum Beispiel:

You answer questions about the supplied documents.

Rules:
- Use only the passages in DOCUMENT_CONTEXT.
- If the passages do not support an answer, say that the documents do not establish it.
- Do not create titles, URLs, page numbers, or quotations.
- Cite each factual answer using the supplied title and page, section, URL, or chunk ID.
- Distinguish a direct statement from an inference.

DOCUMENT_CONTEXT:
{{ JSON.stringify($json.documents) }}

QUESTION:
{{ $json.question }}

Die genaue Syntax des Ausdrucks hängt davon ab, wie Ihre vorherigen n8n-Nodes die Daten strukturieren. Betrachten Sie diesen Prompt als Muster und nicht als direkt importierbaren Workflow-Export.

Freigabedesign: Abruf oder Veröffentlichung

Es gibt zwei sinnvolle Punkte für eine Freigabe:

Bei Workflows mit hohem Risiko können Sie auch beide Punkte verwenden. Die n8n-Dokumentation erklärt, dass die Prüfung für alle mit einem AI Agent verbundenen Tools oder nur für ausgewählte Tools gelten kann, was dieses selektive Design unterstützt. Außerdem wird darauf hingewiesen, dass die Freigabe über einen anderen Kanal als die Hauptinteraktion erfolgen kann; beispielsweise kann ein nutzerseitiger Chat mit einer Prüfung durch ein Teammitglied in Slack kombiniert werden.

System-Prompt und Verhalten bei Ablehnung

Teilen Sie dem Agent mit, welche Tools eine Freigabe benötigen und was eine Ablehnung bedeutet. Wenn eine prüfende Person die Suche ablehnt, sollte der Agent denselben Aufruf nicht mit einer veränderten Formulierung wiederholen und nicht behaupten, Belege gefunden zu haben. Er sollte erklären, dass der angeforderte Abruf nicht genehmigt wurde, und, sofern vorhanden, eine engere zulässige Alternative anbieten.

Eine knappe Richtlinie lautet:

The document_search tool requires human approval. If it is denied, do not call it again for the same request. Tell the user that the lookup was not approved. Never answer from memory when document evidence is required.

Dies entspricht der dokumentierten Empfehlung von n8n, das Verhalten von Tools und menschlicher Prüfung in den System-Prompt aufzunehmen, damit der Agent abgelehnte Aufrufe angemessen verarbeiten kann.

Fehlerbehebung und Einschränkungen

Die Freigabeanfrage enthält zu wenig Kontext

Prüfen Sie, ob die Tool-Eingaben eindeutige Felder verwenden und die Prüfnachricht $tool.name und $tool.parameters enthält. Verstecken Sie den wichtigen Suchumfang nicht in einer undurchsichtigen Zeichenfolge.

Quellenangaben fehlen

Untersuchen Sie die Ausgabe des Abrufs, bevor sie das Modell erreicht. Wenn Titel, URL, Seite, Abschnitt oder Chunk-Kennungen durch einen Mapping-Node entfernt werden, kann das Modell diese Angaben nicht zuverlässig rekonstruieren. Weisen Sie das Modell außerdem an, nicht belegte Aussagen abzulehnen.

Der Endpunkt lehnt die Anfrage ab

Prüfen Sie die Basis-URL, den Authentifizierungs-Header, die Modell-ID, die Unterstützung von Tool-Aufrufen, die Kontextlimits und die Parameternamen. OpenAI-kompatibel bedeutet nicht identisch: Die Kompatibilität muss sowohl mit dem Anfrageformat von n8n als auch mit der dokumentierten API des Anbieters abgeglichen werden.

Eine Ablehnung führt zu einer unpassenden Antwort

Fügen Sie dem System-Prompt eine eindeutige Richtlinie für Ablehnungen hinzu und testen Sie sowohl den Freigabe- als auch den Ablehnungspfad. n8n beschreibt Genehmigung und Abbruch als getrennte Ergebnisse. Ihr Workflow sollte beide verarbeiten, statt davon auszugehen, dass das Tool immer ausgeführt wird.

Der Workflow ist zu langsam

Verwenden Sie eine selektive Prüfung, statt jede Suche mit geringem Risiko freizugeben. Beschränken Sie die Freigabe auf sensible Abrufe oder Veröffentlichungen und messen Sie die betrieblichen Auswirkungen in Ihrer eigenen Umgebung. Treffen Sie ohne Tests keine Annahmen über Modellgeschwindigkeit, Abrufqualität oder Freigabeverzögerung.

Kosten- und Betriebsplanung

OneMux ist hier als Weg für den Modellzugriff relevant, nicht als Ersatz für die Workflow-Steuerung von n8n. Prüfen Sie vor der Auswahl eines Modells die aktuellen OneMux-Preise und berücksichtigen Sie die Nutzung von Eingaben und Ausgaben, das Abrufvolumen, wiederholte Freigabeversuche sowie mögliche Kosten des Dokumentensuchdienstes. Der geltende Preis hängt vom ausgewählten Modell und den aktuell veröffentlichten Bedingungen ab; dieser Artikel nennt keinen Tarif und verspricht keine Einsparungen.

Für Informationen zur Ausgabenübersicht und zur Modellauswahl können Sie den OneMux-Modellkatalog aufrufen. Machen Sie die Modellauswahl von den tatsächlich benötigten Funktionen Ihres Workflows abhängig, insbesondere von strukturierten Ausgaben oder Tool-Aufrufen.

Fazit

Ein robuster n8n-Workflow für Fragen zu Dokumenten ist nicht einfach nur ein Agent, der mit einem Modell verbunden ist. Er ist eine kontrollierte Kette: autorisierte Passagen abrufen, ihre Metadaten bewahren, an der richtigen Tool-Grenze eine Prüfung verlangen und eine Antwort erstellen, die ausschließlich die erhaltenen Belege zitiert.

Nutzen Sie n8n für Orchestrierung und menschliche Freigaben und prüfen Sie OneMux als praktischen Weg für den Zugriff auf OpenAI-kompatible Modelle, wenn der dokumentierte Endpunkt und die Parameter zu Ihrem Design passen. Beginnen Sie mit einem kleinen Korpus, testen Sie genehmigte und abgelehnte Pfade und behandeln Sie nicht belegte Aussagen, fehlende Quellenangaben und inkompatible Parameter als Workflow-Fehler statt als unerklärliche Modellprobleme.

Quellen

• n8n: Human-in-the-loop für Tools — Quelle für das Verhalten bei Tool-Freigaben, Freigabekanäle, $tool-Ausdrücke und Hinweise zum Umgang mit Ablehnungen.
• OneMux-Dokumentation — Anbieterdokumentation zur aktuellen API-Nutzung und zu Kompatibilitätsdetails.
• OneMux-Schnellstart — Ausgangspunkt für die Konfiguration von Endpunkt und Authentifizierung.
• OneMux-Preise — aktuelle Preisreferenz, die vor der Bereitstellung geprüft werden sollte.