OpenQCoreAI
Loslegen

Ressourcen · Ausgabeverträge

Einheitliche Ausgabeverträge

Eine Spezifikation für Produktionsverträge, die Antworten über Text-, Sprach-, Bild- und Videoanbieter hinweg stabil hält.

Zurück zur DokumentationZum kanonischen Vertrag springen

Kanonischer Antwortvertrag

{
  "success": true,
  "content": "Primary human-readable output",
  "provider": "openai",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 64
  },
  "metadata": {
    "model": "gpt-x",
    "latency_ms": 540,
    "trace_id": "trc_123"
  },
  "images": [],
  "files": [],
  "videos": []
}

Designprinzipien

  • Ein Envelope für alle Modalitäten und Anbieter.
  • Feldnamen bleiben über Laufzeitversionen hinweg stabil.
  • Anbieterspezifische Details gehören in die Metadaten, nicht zu Änderungen der Top-Level-Struktur.
  • Fehlende Modalitätsausgaben liefern leere Arrays zurück, keine Strukturänderungen.
  • Das success-Flag ist für deterministisches Client-Verhalten Pflicht.

Feldreferenz

  • success: boolesches Ergebnis der Operation.
  • content: primäre, für Menschen lesbare Ausgabe.
  • provider: normalisierter Anbieterkennzeichner.
  • usage: normalisiertes Abrechnungsobjekt.
  • metadata: Diagnose- und Ausführungskontext.
  • images/files/videos: Ausgabe-Arrays der Modalitäten.
  • error: strukturiertes Fehlerobjekt, wenn success=false.

Beispiele für mehrere Anbieter

Im OpenAI-Stil normalisierte Antwort

{
  "success": true,
  "content": "Generated response",
  "provider": "openai",
  "usage": { "input_tokens": 90, "output_tokens": 52 },
  "metadata": { "latency_ms": 480 },
  "images": [],
  "files": [],
  "videos": []
}

Im Replicate-Stil normalisierte Antwort

{
  "success": true,
  "content": "Image generation completed",
  "provider": "replicate",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "metadata": { "duration_ms": 2300 },
  "images": [{ "url": "https://..." }],
  "files": [],
  "videos": []
}

Client-Kompatibilitätsregeln

  • Die Rendering-Logik des Frontends sollte von der Envelope-Form abhängen, nicht von den Interna der Anbieter.
  • Clients müssen unbekannte Metadaten-Schlüssel für Vorwärtskompatibilität tolerieren.
  • Leere Arrays sind gültige Ausgaben für nicht anwendbare Modalitäten.
  • Das Parsen sollte explizite Feldprüfungen gegenüber Anbieter-Verzweigungen bevorzugen.

Error Contract

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}
  • Fehler-Payloads müssen einen maschinenlesbaren Code und eine für Menschen lesbare Nachricht enthalten.
  • Trace-Identifikatoren sollten für die Diagnose weitergegeben werden.
  • Antworten mit success=false dürfen niemals Felder wiederverwenden, die ausschließlich in Erfolgspayloads verwendet werden.
  • HTTP-Status und strukturierter Fehlercode müssen konsistent bleiben.