Risorse · Documentazione
Documentazione della piattaforma.
Pronto per la produzione fin dalla progettazione.
Documentazione OpenQCore per team che realizzano prodotti AI affidabili per chat, voce, generazione multimodale e workflow di conoscenza, con controllo del runtime basato sugli ambiti.
Avvio rapido
Dalla prima richiesta al percorso di produzione in pochi minuti.
1) Autenticazione
Usa l'autenticazione JWT (sessione) o con chiave API con controllo accessi basato sullo scope.
2) Scegli lo scope di runtime
Imposta il contesto personale o del workspace usando gli header di runtime quando necessario.
3) Richiama chat completions
Usa /api/v1/chat/completions per l'esecuzione principale dell'assistente.
4) Aggiungi voce e multimodale
Usa /api/v1/voice e gli endpoint Iris per flussi di lavoro STT/TTS, immagini, video e OCR.
5) Integra la conoscenza
Usa /api/v1/console/knowledge per caricamento, ingestione e richieste basate sul recupero.
URL base
Base API pubblica
/api/v1Tutti gli endpoint pubblici della piattaforma sono montati sotto /api/v1.
Autenticazione e ambito
Accesso contestuale per esecuzioni personali e del workspace.
Metodi di autenticazione
JWT/sessione o chiave API
Header dello scope
X-Scope-Type: personal | workspace
Header del workspace
X-Workspace-ID: [uuid] (richiesto nello scope workspace)
Header agente
X-Agent-ID: [uuid] (opzionale)
Regole di validazione
- Se lo scope è personal, workspace_id non è consentito.
- Se lo scope è workspace, workspace_id è obbligatorio.
- Gli header di scope non validi restituiscono 422.
Limiti di velocità
Limitazione basata su policy per contesto di autenticazione.
Chiave API
60 richieste al minuto
La chiave del bucket usa l'identità hash della chiave API.
JWT/session
120 richieste al minuto
La chiave del bucket usa l'id del workspace quando presente, altrimenti l'id dell'utente.
Header di risposta per il throttling
Runtime Chat
/chat/completions con livelli di controllo per la produzione.
GET /api/v1/chat/healthPOST /api/v1/chat/completionsComportamenti di esecuzione
- Tracciamento della backpressure e rifiuto in caso di sovraccarico del sistema (503).
- Blocco distribuito per prevenire elaborazioni duplicate in corso (409).
- Cache per deduplicazione per risposte non in streaming.
- Persistenza di sessione/messaggi per i turni dell'utente e dell'assistente.
- Validazione in runtime per la richiesta, gli allegati e l'accesso alla sessione.
Runtime Voce
Pipeline STT → LLM → TTS con streaming e interruzione.
POST /api/v1/voice/chat/metaPOST /api/v1/voice/chatPOST /api/v1/voice/interrupt/{session_id}WS /api/v1/voice/wsFunzionalità vocali
- Router per provider di fallback (OpenAI + Azure).
- Interruttori di circuito per le fasi STT, LLM e TTS.
- Pipeline di conversione audio per input non-WAV.
- Risposte audio in streaming con intestazioni dei metadati.
- Contesto di cancellazione per l'interruzione a livello di sessione.
- Gestione del carico e degrado della qualità sotto carico elevato.
Iris Multimodale
Flussi di lavoro per immagini, video, OCR e verifica instradati dal modello.
Catalogo dei modelli
iris-orbit
Modalità di instradamento automatico
iris-genesis
Generazione di immagini
iris-edit
Modifica delle immagini (non implementato)
iris-lens
Analisi delle immagini (non implementato)
iris-video
Generazione di video
iris-ocr
OCR dei documenti
iris-verify
Verifica dell'identità
iris-guard
Rilevamento delle frodi (non implementato)
iris-face
Verifica facciale (non implementato)
Conoscenza della console
API della console del workspace per l'ingestione e le richieste.
/api/v1/console/knowledgeGET /api/v1/console/knowledgePOST /api/v1/console/knowledgePOST /api/v1/console/knowledge/uploadGET /api/v1/console/knowledge/{item_id}PATCH /api/v1/console/knowledge/{item_id}DELETE /api/v1/console/knowledge/{item_id}POST /api/v1/console/knowledge/askVincoli della conoscenza
- Dimensione massima del file: 20MB
- Tipi consentiti: PDF, DOC, DOCX, TXT, Markdown
- L'ingestione viene eseguita in background in modo asincrono
- Stati: in attesa → in elaborazione → elaborato | non riuscito
Semantica degli errori
Classi di risposta comuni della piattaforma.
400
Richiesta non valida, dati mancanti o input malformato
401
Autenticazione assente o non valida
403
Ambito non consentito / restrizione del ruolo nel workspace
404
Risorsa non trovata
409
Richiesta già in elaborazione (conflitto di blocco)
413
Payload troppo grande (es. limiti per audio/file)
415
Tipo di contenuto non supportato
422
Errore di validazione (ambito/contesto/schema)
429
Limite di richieste superato
503
Sovraccarico del sistema / provider non disponibile
Osservabilità
Esecuzione tracciabile attraverso i cicli di vita di chat e voce.
- ID di traccia per la correlazione delle richieste.
- Pipeline middleware per il logging dell'utilizzo.
- Inizializzazione di OpenTelemetry con esportazione OTLP.
- Gli header di risposta espongono segnali temporali nei flussi vocali.
Navigazione della documentazione
Esplora le sezioni della documentazione
Vai direttamente alle guide di implementazione e alle referenze di produzione per ogni superficie di runtime.
Autenticazione
Autenticazione JWT/API key, header di scope e modello di validazione.
API Chat
Completamento, comportamento di streaming e controlli di runtime.
API Voce
Pipeline vocale in tempo reale, flusso di interruzione e header dei metadati.
API Iris
Endpoint per immagini/video/OCR/verifica e routing.
API Knowledge
Caricamento, ciclo di vita dell'indicizzazione, recupero e flussi di lavoro per le richieste.
Fornitori
Matrice delle capacità, politica di instradamento e strategia di failover.
Contratti di output
Struttura di risposta unificata tra fornitori e modalità.
Architettura
Livelli di runtime, astrazione dei fornitori e garanzie del sistema.
Sviluppa con fiducia sul runtime OpenQCore.
Usa la documentazione come mappa di produzione per chat, voce, generazione multimodale ed esecuzione basata sulla conoscenza.