API di Chat

La Chat API è il servizio backend Hono.js che alimenta l’assistente di fiskaly Workspace. Fornisce streaming di eventi inviati dal server (SSE), recupero del contesto RAG tramite Vertex AI e un robusto livello di sicurezza per la chat pubblica e i dashboard amministrativi.

Funzionalità principali

• Risposte in streaming — I Server-Sent Events (SSE) forniscono caratteri digitati a bassa latenza e metadati strutturati.
• Ancoraggio RAG — Il contesto viene recuperato da 5 fonti integrate (Docs MDX, OpenAPI, Knowledge Base Zendesk, Web e PDF).
• Due modelli — Le richieste vengono instradate in modo intelligente tra Gemini 2.5 Pro (query complesse) e Gemini 2.0 Flash (query semplici/saluti).
• Sistema di persona — Personalizzare le risposte per sviluppatori, product manager o operatori retail con diversi comportamenti di fallback.

Integrazione API

Per utilizzare la Chat API, si creerà tipicamente una sessione anonima, quindi si aprirà una connessione EventSource all’endpoint di streaming /api/chat.

1. Creare una sessione

POST /api/session

Restituisce un token di sessione JWT necessario per la limitazione della frequenza e la continuità.

2. Trasmettere una conversazione in streaming

POST /api/chat
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "message": "How do I create a TSS in SIGN DE?",
  "persona": "developer",
  "history": []
}

La risposta è un flusso SSE che emette payload JSON con il prefisso data:. Il flusso conterrà sia frammenti di testo che metadati (come citazioni recuperate o il punteggio di qualità finale).

💡Usi React?

Se si sta creando un’applicazione React, forniamo una libreria UI completa pronta all’uso. Consultare la documentazione sui Componenti UI della Chat invece di creare il client SSE da zero.

Sicurezza e limiti

La Chat API include severi meccanismi di protezione per l’uso in produzione:

• Limitazione della frequenza — 5 messaggi al minuto, 30 all’ora per sessione.
• Filtraggio dell’input — Rilevamento di jailbreak e validazione della lunghezza (massimo 3000 caratteri per messaggio).
• Filtraggio dell’output — Scansione PII e verifica del radicamento.
• Protezione del budget — Un limite di spesa giornaliero configurabile per l’intero tenant previene costi LLM imprevisti.

Reindicizzazione dei contenuti

La knowledge base RAG viene automaticamente reindicizzata ogni giorno alle 3:00 UTC tramite un CronJob Kubernetes. Questo garantisce che la documentazione nuova o aggiornata, gli articoli Zendesk e le specifiche API siano riflesse nelle risposte della chat entro 24 ore.

Dashboard amministrativo

Il servizio chat-api ospita anche una SPA React interna su /admin/*, protetta da Google OAuth. Il dashboard fornisce:

• Revisione delle conversazioni e assegnazione dei tag di qualità.
• Elementi di azione (Todo) per il miglioramento dei contenuti.
• Override dei prompt LLM basati su trigger di parole chiave.
• Analisi di utilizzo, costi e budget.

Passi successivi

Componenti UI della Chat

Componenti React pronti all'uso per il Widget Chat di fiskaly e l'esperienza a pagina intera.

Codice sorgente backend

Visualizzare il codice sorgente dell'API sottostante, incluse le route Hono e la pipeline RAG.