Burime · Kontratat e Daljes

Kontratat e Daljes të Unifikuara

Një specifikim kontrate prodhimi që mban përgjigjet të qëndrueshme nëpër ofruesit e tekstit, zërit, imazhit dhe videos.

Kthehu te Dokumentet Shko te Kontrata Kanonike

Kontrata Kanonike e Përgjigjes

{
  "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": []
}

Parimet e Dizajnit

Një kuvertë për të gjitha modalitetet dhe ofruesit.
Emrat e fushave mbeten të qëndrueshme nëpër versionet e runtime-it.
Detajet specifike të ofruesit ruhen në metadatë, jo në ndryshimin e strukturës kryesore.
Daljet e modaliteteve të munguar kthejnë vargje të zbrazëta, jo ndryshime të strukturës.
Flamuri success është i detyrueshëm për trajtimin deterministik të klientit.

Referenca e Fushave

success: rezultat boolean i operacionit.
content: dalje kryesore e lexueshme nga njeriu.
provider: identifikator i normalizuar i ofruesit.
usage: objekt llogaritjeje i normalizuar.
metadata: diagnostikë dhe kontekst ekzekutimi.
images/files/videos: vargje daljesh për modalitetet.
error: objekt i strukturuar i gabimit kur success=false.

Shembuj me shumë ofrues

Përgjigje e normalizuar në stilin OpenAI

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

Përgjigje e normalizuar në stilin Replicate

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

Rregullat e Kompatibilitetit të Klientit

Logjika e renderimit në frontend duhet të bazohet në formën e kuvertës, jo në pjesët e brendshme të ofruesit.
Klientët duhet të pranojnë çelësa metadata të panjohur për kompatibilitetin e ardhshëm.
Vargjet e zbrazëta janë dalje të vlefshme për modalitetet që nuk zbatohen.
Parsimi duhet të preferojë kontrollat e qarta të fushave mbi degëzimin sipas ofruesit.

Error Contract

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}

Paketat e gabimit duhet të përfshijnë kod të lexueshëm nga makina dhe një mesazh të lexueshëm nga njeriu.
Identifikuesit e gjurmimit duhet të propagohen për diagnostikim.
Përgjigjet me success=false nuk duhet kurrë të ri-përdorin fushat e paketës që janë vetëm për sukses.
Statusi HTTP dhe kodi i strukturuar i gabimit duhet të jenë të përputhshëm.