AYXZA Relay · Gateway AI universale

Sezione commerciale · 01 / 03

Perché AYXZA Relay

Integrare l'AI in un prodotto non è più "chiamare un'API". Significa gestire cinque vendor diversi, contenere i costi, garantire continuità di servizio e proteggere i dati. AYXZA Relay risolve tutti questi problemi con una libreria sola.

Il problema Senza gateway

✗Codice duplicato per ogni provider (OpenAI, Anthropic, Gemini…)
✗Lock-in tecnico: cambiare modello = rifare l'integrazione
✗Costi fuori controllo, nessuna visibilità per tenant
✗Un provider down = servizio down
✗Dati sensibili inviati al cloud, nessuna opzione on-prem
✗RAG/knowledge base da costruire da zero ogni volta

La soluzione Con AYXZA Relay

+API unica: gw.chat() funziona con qualsiasi modello registrato
+Switch provider via configurazione, zero refactoring
+Costi tracciati per chiamata, utente e modello, con quote e budget per tenant
+Fallback automatico verso un modello di riserva, con interruttore di sicurezza per provider
+Motori locali (Ollama, vLLM, llama.cpp) per i dati sensibili, senza rete esterna
+Modulo Knowledge Base con pgvector incluso

Casi d'uso tipici

01

SaaS multi-tenant

Tracking costi per cliente, limiti per piano, modelli diversi per tier. Tutto out-of-the-box.

02

Enterprise on-premise

Ollama locale per dati riservati, fallback cloud opzionale per task non-sensibili.

03

Knowledge base aziendale

RAG su documenti interni con pgvector, re-index automatica, isolation per tenant.

04

Agenti & chains

Multi-step orchestration, output strutturato nativo (Gemini, OpenAI) e allegati multimodali (PDF, immagini) sui prompt.

05

Migrazione provider

Il modello si cambia dalla configurazione o dalla console, senza toccare il codice dell'applicazione.

06

Alta disponibilità

Fallback trasparente: se un provider non risponde, la richiesta passa al modello di riserva dichiarato, senza modifiche al codice.

Governo e osservabilità

01

Profili di instradamento

Ogni richiesta resta nella classe dichiarata, locale, cloud europeo o cloud, e scorre i candidati in ordine.

02

Resilienza

Modelli di riserva, interruttore di sicurezza per provider, più chiavi per provider con pausa automatica di quella in errore e sonda di salute su comando.

03

Console web

Una console web governa provider, modelli, chiavi, prompt, quote e knowledge base, e offre un banco di prova per chat ed embedding.

04

Prompt versionati

I prompt sono versionati e validati: ogni esecuzione registra la versione usata e ripete il tentativo quando l'output non supera i controlli.

05

Documenti e confidenza

Documenti PDF e Word entrano nella knowledge base; le risposte portano una confidenza che combina il giudizio del modello e la pertinenza dei passaggi recuperati.

06

Quote e budget

Quote di spesa per utente e per tenant, con il confronto tra spesa effettiva e tetto.

07

Conservazione dei dati

Le chiamate più vecchie di una data si anonimizzano dopo una prova a vuoto, lasciando intatti i numeri contabili.

08

OpenTelemetry

Tracce OpenTelemetry native su ogni chiamata, pronte per qualunque collettore.

09

Ciclo degli strumenti

Il modello invoca le funzioni dell'applicazione e Relay gestisce i turni fino alla risposta.

Sezione tecnica · 02 / 03

Architettura

Libreria Python pura, stateless dove possibile, con persistenza su PostgreSQL + pgvector. Nessuna dipendenza da servizi esterni se non i provider LLM stessi.

Architettura a strati

Dal client applicativo ai provider, passando per il gateway core.

flowchart TB subgraph CLIENT["CLIENT APPLICATIONS"] A1["Web App"] A2["Backend API"] A3["CLI / Scripts"] end subgraph FORGE["AYXZA Relay · Gateway Library"] GW["Unified API
gw.chat · gw.embedding · gw.kb"] subgraph CORE["Core Services"] R["Profili
instradamento"] T["Tracking
cost · tenant · model"] F["Fallback
provider failover"] K["Knowledge Base
RAG + pgvector"] end GW --> R R --> T T --> F GW -.-> K end subgraph PROV["LLM PROVIDERS"] P1["OpenAI"] P2["Anthropic"] P3["Google Gemini"] P4["Google Vertex"] P5["OpenAI-compatible
Ollama · vLLM · llama.cpp"] end DB[("PostgreSQL
+ pgvector")] CLIENT --> GW F --> P1 F --> P2 F --> P3 F --> P4 F --> P5 T --> DB K --> DB

Flusso di una richiesta con fallback

Provider primario non disponibile, fallback automatico al secondario.

sequenceDiagram autonumber participant App as Client App participant Relay as AYXZA Relay participant P1 as OpenAI primary participant P2 as Anthropic fallback participant DB as PostgreSQL App->>Relay: gw.chat(ChatRequest(profilo="standard")) Relay->>P1: POST /v1/chat/completions P1-->>Relay: 503 Service Unavailable Note over Relay: Salto verso il modello di riserva Relay->>P2: POST /v1/messages P2-->>Relay: 200 OK + tokens Relay->>DB: log(tenant, model, cost, latency) Relay-->>App: response (transparent)

Pipeline RAG · Knowledge Base

Ingestion → chunking → embedding → retrieval → generation.

flowchart LR D["Documents
PDF · Word · testo"] S["Source Registry
aggiornamento per hash"] CH["Chunker
shared utility"] EM["Embedder
gemini-embedding-2
768-dim"] VS[("pgvector
HNSW index")] Q["User query"] QE["Query embedding"] RT["Retrieval
global + tenant chunks"] GEN["LLM Generation
any provider"] D --> S --> CH --> EM --> VS Q --> QE --> RT VS -.-> RT RT --> GEN

API in azione

Poche righe per la chat, l'instradamento per profilo, l'output strutturato e le risposte dalla knowledge base.

# 1. Inizializzazione: provider, modelli e chiavi si registrano una volta
import os
from forge_ai import ChatRequest, ForgeAIConfig, Gateway, Message

config = ForgeAIConfig(
    database_url=os.environ["FORGE_AI_DATABASE_URL"],
    fernet_key=os.environ["FORGE_AI_FERNET_KEY"],
)

with Gateway(config) as gw:
    # 2. Chat diretta su un provider e un modello
    r = gw.chat(ChatRequest(
        provider="gemini",
        modello="gemini-2.5-flash",
        messaggi=[Message(role="user", content="Riassumi questo contratto in 3 punti")],
    ))
    print(r.testo, r.costo, r.provider, r.latenza_ms)

    # 3. Instradamento per profilo: candidati e fallback stanno nella configurazione
    r = gw.chat(ChatRequest(
        profilo="standard",
        messaggi=[Message(role="user", content="...")],
    ))

    # 4. Output strutturato nativo con JSON Schema
    r = gw.chat(ChatRequest(
        provider="openai",
        modello="gpt-4o-mini",
        messaggi=[Message(role="user", content="Estrai i dati da questa fattura...")],
        output_schema={"type": "object",
                       "properties": {"totale": {"type": "number"}, "iva": {"type": "number"}},
                       "required": ["totale", "iva"], "additionalProperties": False},
    ))

    # 5. Knowledge base: risposta con confidenza
    esito = gw.kb.interroga(
        "Qual è la policy sui rimborsi spese?",
        codice_prompt="qa_policy",
        app_codice="intranet",
    )
    print(esito.risposta, esito.confidenza_finale)

Capability matrix

Capability	OpenAI	Anthropic	Gemini	Vertex	Ollama
Chat completion	●	●	●	●	●
Streaming	●	—	●	—	●
Structured output (native)	●	—	●	●	—
Function calling	●	●	●	—	●
Embeddings	●	—	●	●	●
Vision · multimodal	●	●	●	●	●
On-premise · air-gapped	—	—	—	—	●

Requisiti

Python 3.12+
PostgreSQL 16+ con estensione pgvector
Chiavi API dei provider scelti (non necessarie per i motori locali)
Un motore locale compatibile con OpenAI (Ollama, vLLM, llama.cpp) per i modelli on-premise

Stack tecnologico

SQLAlchemy 2.x
Pydantic v2 per validazione e schemi
Alembic per migrazioni database
Ritentativi con backoff esponenziale e jitter
Suite di oltre 1700 test, con contratti pubblici verificati a ogni rilascio

Provider supportati · 03 / 03

Provider integrati

Tutti i principali vendor LLM cloud, più un adapter compatibile con OpenAI che raggiunge motori cloud (Groq, DeepSeek, OpenRouter) e locali (Ollama, vLLM, llama.cpp), anche in ambienti isolati.

OA

OpenAI

Modelli GPT e serie o

Frontier reasoning, function calling completo, structured output nativo.

AN

Anthropic

Claude Opus · Sonnet · Haiku

Long-context (200K+), eccellente per reasoning lungo e analisi documentale.

GG

Google Gemini

Gemini 2.5 e 3 · gemini-embedding-2

Multimodale nativo, embedding a 768 dimensioni, livelli di ragionamento configurabili.

VX

Google Vertex AI

Enterprise GCP · regione configurabile

Gli stessi modelli Gemini su Google Cloud, con fatturazione GCP e regione di elaborazione a scelta, anche europea.

OL

Ollama

Llama · Mistral · Qwen · local

Esecuzione 100% locale, zero rete esterna, ideale per dati sensibili e GDPR. Lo stesso adapter OpenAI-compatible raggiunge anche motori cloud (Groq, DeepSeek, OpenRouter).

++

Provider custom

extensible api

Aggiungere un nuovo provider richiede ~150 righe Python implementando l'interfaccia BaseProvider.

Contattaci

Per valutare un'integrazione, discutere un caso d'uso o ricevere una demo personalizzata sul tuo prodotto.

Contattaci →

Un solo SDK. Tutti i modelli AI.