Documentazione API LLMaaS

Compatibilità OpenAI

L'API LLMaaS è compatibile con OpenAI per le chiamate documentate in questo riferimento. Configura l'URL di base https://api.ai.cloud-temple.com/v1 e la tua chiave LLMaaS nel client, quindi verifica le capacità del modello e i parametri dell'endpoint utilizzato.

La compatibilità non copre tutte le funzionalità di OpenAI. Le differenze documentate includono in particolare:

Completamenti : /v1/completions attende un array messages, come la chat; vedere il formato di completamento.
Embedding : gli input devono essere testo; vedere i formati accettati.
Trascrizione audio : i formati di risposta text, srt e vtt non sono supportati; vedere i parametri di trascrizione.
Batch : il servizio utilizza un contratto specifico, con invio diretto delle conversazioni in JSON su /v1/chat/completions/batch.

URL di Base

https://api.ai.cloud-temple.com/v1

Autenticazione

Tutte le richieste richiedono un header Authorization con il tuo token API:

Authorization: Bearer VOTRE_TOKEN_API

Rate Limiting e Fatturazione

Il Principio dei Livelli (Tier) : Livello di Accesso, Budget e Capacità

Il nostro sistema di livelli è progettato come pacchetti di servizio completi che definiscono tre aspetti chiave del tuo utilizzo:

Un Livello di Accesso (Credito di Acquisto) : Per i Livelli 1 a 4, si tratta di un importo da pagare in anticipo (upfront) per attivare il servizio e sbloccare le capacità tecniche e di budget del livello scelto.
Un Limite di Budget Mensile : È il tetto del tuo consumo mensile, garantendoti un controllo totale sui costi.
Una Capacità Tecnica : Sono i limiti di throughput (token al giorno e all'ora) che garantiscono una performance stabile e prevedibile per il tuo volume di chiamate.

La scelta di un livello è quindi un equilibrio tra l'investimento iniziale, il budget mensile previsto e la capacità tecnica richiesta. Il tuo consumo all'interno di questo pacchetto viene poi fatturato secondo le tariffe vigenti.

Capacità tecniche dei livelli

La tabella seguente presenta esclusivamente i throughput tecnici. Gli importi del credito di accesso e i tetti di budget rientrano nelle condizioni commerciali del livello scelto; consulta il catalogo ufficiale e le condizioni della tua sottoscrizione.

Livello	Token Output/Ora	Token Output/Giorno	Descrizione
Livello 1	150 000	3 600 000	Utilizzo standard
Livello 2	300 000	7 200 000	Uso professionale
Livello 3	450 000	10 800 000	Alto volume
Livello 4	600 000	14 400 000	Impresa
Fatturazione Mensile	Priorità elevata	Priorità elevata	Contatto commerciale

Per conoscere i prezzi pubblici vigenti e stabilire la tua stima, consulta il catalogo tariffario ufficiale Cloud Temple.

Nota : I limiti di throughput sono calcolati sulla base dei token di output. La tariffazione varia a seconda dell'uso:

Tipo di utilizzo
Token di input
Token di output (chat/completamento)
Token di ragionamento
Reranking
Batch asincrono (input)
Batch asincrono (output)
Trascrizione Audio

Per conoscere i prezzi pubblici vigenti e stabilire la tua stima, consulta il catalogo tariffario ufficiale Cloud Temple.

La trascrizione audio viene conteggiata al minuto; ogni minuto iniziato è dovuto.

Header di Limite

Le risposte includono header informativi:

X-RateLimit-Limit-Requests: 1000
X-RateLimit-Remaining-Requests: 999
X-RateLimit-Reset-Requests: 1640995200

Errore 429 - Limite Raggiunto

{
  "error": {
    "message": "Rate limit exceeded. Please upgrade your tier or try again later.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Endpoint

POST /v1/chat/completions

Genera risposte conversazionali.

Richiesta

curl -X POST "https://api.ai.cloud-temple.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN_API" \
  -d '{
    "model": "gpt-oss:120b",
    "messages": [
      {
        "role": "user",
        "content": "Expliquez la photosynthèse"
      }
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
`model`	string	✅	ID del modello (vedi catalogo)
`messages`	array	✅	Conversazione (role: system/user/assistant)
`stream`	boolean	❌	Abilita lo streaming (default: false)
`temperature`	float	❌	Creatività 0.0-2.0 (default: 0.7)
`max_tokens`	integer	❌	Limite di token (default: 1024)
`top_p`	float	❌	Campionamento nucleus 0.0-1.0 (default: 1.0)
`presence_penalty`	float	❌	Penalità presenza -2.0 a 2.0 (default: 0)
`frequency_penalty`	float	❌	Penalità frequenza -2.0 a 2.0 (default: 0)
`user`	string	❌	ID utente univoco
`tools`	array	❌	Lista degli strumenti che il modello può chiamare.
`tool_choice`	string/object	❌	Controlla se il modello deve chiamare uno strumento. "none", "auto", o `{"type": "function", "function": {"name": "my_function"}}`.

Risposta Standard

{
  "id": "chatcmpl-bc52de347f2e4068b7bde380c0f8db37",
  "object": "chat.completion",
  "created": 1749114814,
  "model": "gpt-oss:120b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "La photosynthèse est un processus biologique..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 42,
    "total_tokens": 57
  }
}

Risposta con Chiamata di Strumento

Se il modello decide di chiamare uno strumento, la risposta avrà un finish_reason di tool_calls e il messaggio conterrà un array tool_calls.

{
  "id": "chatcmpl-9f27a53f52b44a9693753f2a5e1f7a73",
  "object": "chat.completion",
  "created": 1749115200,
  "model": "gpt-oss:120b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\n  \"location\": \"Paris, France\",\n  \"unit\": \"celsius\"\n}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 18,
    "total_tokens": 100
  }
}

Dopo aver ricevuto una risposta tool_calls, devi eseguire lo strumento dal tuo lato, quindi inviare nuovamente il risultato al modello utilizzando un messaggio con il role: "tool".

{
  "model": "gpt-oss:120b",
  "messages": [
    {
      "role": "user",
      "content": "Quel temps fait-il à Paris ?"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_current_weather",
            "arguments": "{\"location\": \"Paris, France\", \"unit\": \"celsius\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": \"22\", \"unit\": \"celsius\", \"description\": \"Ensoleillé\"}"
    }
  ]
}

Streaming (SSE)

Con "stream": true, la risposta arriva token per token:

Header di risposta :

Content-Type: text/event-stream
Cache-Control: no-cache

Formato degli eventi :

data: {"choices":[{"delta":{"content":"La"},"finish_reason":null,"index":0}],"created":1749114814,"id":"chatcmpl-bc52de347f2e4068b7bde380c0f8db37","model":"gpt-oss:120b","object":"chat.completion.chunk"}

data: {"choices":[{"delta":{"content":" photo"},"finish_reason":null,"index":0}],"created":1749114814,"id":"chatcmpl-bc52de347f2e4068b7bde380c0f8db37","model":"gpt-oss:120b","object":"chat.completion.chunk"}

data: {"choices":[{"delta":{"content":""},"finish_reason":"stop","index":0}],"created":1749114814,"id":"chatcmpl-bc52de347f2e4068b7bde380c0f8db37","model":"gpt-oss:120b","object":"chat.completion.chunk"}

data: [DONE]

Struttura dei chunk :

choices[].delta.content : Contenuto incrementale
finish_reason : null durante lo streaming, poi "stop"
Segnale di fine : data: [DONE]

Richieste Multimodali (Visione)

Per analizzare immagini, puoi inviare una richiesta in cui il campo content di un messaggio utente è un array (array) contenente sia testo che immagini.

Il formato per un'immagine è un oggetto con type: "image_url" e un campo image_url contenente l'URL dell'immagine nel formato data URI (base64).

Nota di Compatibilità

Sebbene il formato standard e raccomandato sia {"type": "image_url", "image_url": {"url": "data:..."}}, l'API supporta anche per motivi di flessibilità un formato semplificato {"type": "image", "image": "data:..."}. Si consiglia tuttavia di utilizzare il formato standard image_url per una migliore compatibilità con l'ecosistema OpenAI.

OCR e Analisi di Documenti

Per attività specifiche di analisi di documenti (PDF, scansioni, tabelle), raccomandiamo l'uso del modello specializzato DeepSeek-OCR. Vedi la documentazione dedicata.

Esempio di Richiesta Vision

curl -X POST "https://api.ai.cloud-temple.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN_API" \
  -d '{
    "model": "gemma4:31b",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Que vois-tu sur cette image ?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/jpeg;base64,..."
            }
          }
        ]
      }
    ],
    "max_tokens": 500
  }'

POST /v1/completions

warning

Nota : L'endpoint /v1/completions utilizza lo stesso formato di /v1/chat/completions con i messaggi. Per il completamento di testo semplice, utilizzare un messaggio user con il proprio prompt.

Completamenti di testo tramite formato chat.

Richiesta

curl -X POST "https://api.ai.cloud-temple.com/v1/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN_API" \
  -d '{
    "model": "gpt-oss:120b",
    "messages": [
      {
        "role": "user",
        "content": "Complétez cette phrase: L'intelligence artificielle est"
      }
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'

Parametri

Identici a /v1/chat/completions - vedere la sezione precedente.

Risposta

Formato identico a /v1/chat/completions.

POST /v1/audio/transcriptions

Trascrizione audio in testo (Whisper).

Richiesta

curl -X POST "https://api.ai.cloud-temple.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer VOTRE_TOKEN_API" \
  -F "file=@audio.wav" \
  -F "language=fr" \
  -F "response_format=json"

Parametri

Paramètre	Type	Obligatoire	Description
`file`	binary	✅	File audio (wav, mp3, m4a).
`language`	string	❌	Codice lingua ISO 639-1 (es: "fr"). Rilevamento automatico se non fornito.
`initial_prompt`	string	❌	Contesto o parole specifiche per migliorare la precisione della trascrizione.
`task`	string	❌	Attività da eseguire: `transcribe` (default) o `translate` (tradurre in inglese).
`response_format`	string	❌	`json` (default, equivalente a `verbose_json`). I formati `text`, `srt`, `vtt` non sono attualmente supportati.

Risposta (`json`)

{
  "text": "Bonjour, ceci est un test de transcription audio.",
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.0,
      "end": 4.0,
      "text": " Bonjour, ceci est un test de transcription audio.",
      "tokens": [ 50364, 40365, 33, 2373, 359, 456, 2373, 323, 1330, 2373, 2264, 50564 ],
      "temperature": 0.0,
      "avg_logprob": -0.25,
      "compression_ratio": 1.5,
      "no_speech_prob": 0.05
    }
  ],
  "language": "fr"
}

POST /v1/embeddings

Crea un vettore di embedding che rappresenta il testo di input.

Richiesta

curl -X POST "https://api.ai.cloud-temple.com/v1/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN_API" \
  -d '{
    "model": "granite-embedding:278m",
    "input": "Le texte à vectoriser"
  }'

Parametri

Paramètre	Type	Obligatoire	Description
`model`	string	✅	ID del modello di embedding (vedi catalogo)
`input`	string or array of strings	✅	Il testo o la lista di testi da vettorizzare.

Risposta

Estratto abbreviato: i puntini di sospensione rappresentano le altre componenti del vettore. Questo blocco illustra la struttura della risposta e non costituisce un documento JSON direttamente copiabile.

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.018902843818068504,
        -0.023282647132873535,
        ...
        -0.016484618186950684
      ]
    }
  ],
  "model": "granite-embedding:278m",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}

POST /v1/rerank

Riordina una lista di documenti per pertinenza rispetto a una query. Compatibile con l'API Cohere (v1 e v2).

Fatturazione: consultare il catalogo tariffario ufficiale Cloud Temple. Tutti i documenti inviati vengono conteggiati, anche se top_n limita il numero di risultati restituiti. Vedere il dettaglio del calcolo.

Richiesta

curl -X POST "https://api.ai.cloud-temple.com/v1/rerank" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN_API" \
  -d '{
    "model": "nvidia/llama-nemotron-rerank-vl-1b-v2",
    "query": "Quelle est la capitale de la France ?",
    "documents": [
      "Paris est la capitale et la plus grande ville de France.",
      "Lyon est une grande ville du sud-est de la France.",
      "La France est un pays d'\''Europe occidentale."
    ],
    "top_n": 2
  }'

Parametri

Paramètre	Type	Obligatoire	Description
`model`	string	✅	ID del modello di reranking (vedi catalogo)
`query`	string	✅	La query di ricerca
`documents`	array	✅	Lista dei documenti da riordinare
`top_n`	integer	❌	Numero di risultati da restituire (default: tutti)

Risposta

Estratto illustrativo del formato Jina/vLLM descritto dal contratto della piattaforma. I punteggi e i contatori di seguito sono fittizi. Il proxy trasmette la risposta del motore e aggiunge un blocco backend, omesso qui.

{
  "id": "score-8bb47ca195d8cb2f",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.0401,
      "document": {
        "text": "Paris est la capitale et la plus grande ville de France.",
        "multi_modal": null
      }
    },
    {
      "index": 2,
      "relevance_score": 0.0253,
      "document": {
        "text": "La France est un pays d'Europe occidentale.",
        "multi_modal": null
      }
    }
  ],
  "usage": {
    "prompt_tokens": 39,
    "total_tokens": 39
  },
  "model": "nvidia/llama-nemotron-rerank-vl-1b-v2"
}

I relevance_score sono punteggi grezzi non normalizzati, non probabilità tra 0 e 1. Utilizzare il loro ordine relativo; qualsiasi soglia deve essere calibrata sul proprio modello e corpus. I contatori usage.prompt_tokens e usage.total_tokens sono distinti dalla fatturazione per documento elaborato; non è richiesto alcun campo usage.billed_units.search_units per calcolare quest'ultima.

L'endpoint /v2/rerank (SDK Cohere v2) è inoltre disponibile con lo stesso formato di richiesta.

Esempio Python (SDK Cohere)

import cohere

# Compatible avec le SDK Cohere en pointant vers l'API LLMaaS
co = cohere.Client(
    api_key="VOTRE_TOKEN_API",
    base_url="https://api.ai.cloud-temple.com"
)

results = co.rerank(
    model="nvidia/llama-nemotron-rerank-vl-1b-v2",
    query="Quelle est la capitale de la France ?",
    documents=[
        "Paris est la capitale et la plus grande ville de France.",
        "Lyon est une grande ville du sud-est de la France.",
        "La France est un pays d'Europe occidentale."
    ],
    top_n=2
)

for result in results.results:
    print(f"Index: {result.index}, Score: {result.relevance_score:.4f}")

POST /v1/chat/completions/batch

Invia più conversazioni indipendenti con un modello comune per un'elaborazione asincrona. Il campo messages è un array di conversazioni. La risposta HTTP 202 contiene l'identificativo del batch.

Utilizzare GET /v1/chat/completions/batch/{id} con la stessa chiave API per seguire l'elaborazione e recuperare i risultati. Consultare la guida Batch per il formato, i limiti e un esempio completo.

GET /v1/models

Lista degli identificativi dei modelli esposti dall'API. Utilizzare questa risposta per popolare il parametro model.

Consultare anche il ciclo di vita dei modelli per le deprecazioni, le date di fine supporto e le migrazioni. Un identificativo può essere mantenuto come reindirizzamento verso un successore; la sua presenza in questa lista non garantisce il mantenimento del modello originale.

Richiesta

curl -X GET "https://api.ai.cloud-temple.com/v1/models" \
  -H "Authorization: Bearer VOTRE_TOKEN_API"

Risposta

Questo estratto è illustrativo: gli identificativi e i valori dei metadati, tra cui max_model_len, non costituiscono le caratteristiche attuali del servizio. Utilizzare la risposta di GET /v1/models per ottenere i valori effettivi.

{
  "object": "list",
  "data": [
    {
      "id": "gpt-oss:120b",
      "object": "model",
      "created": 1749110897,
      "owned_by": "CloudTemple",
      "root": "gpt-oss:120b",
      "aliases": ["gpt-oss:120b"],
      "max_model_len": 60000,
      "permission": [
        {
          "id": "modelperm-gpt-oss:120b-1749110897",
          "object": "model_permission",
          "allow_sampling": true,
          "allow_view": true,
          "allow_fine_tuning": false
        }
      ]
    }
  ]
}

Codici di Errore

400 - Richiesta Non Valida

{
  "error": {
    "message": "Invalid parameter 'temperature': must be between 0 and 2",
    "type": "invalid_request_error",
    "param": "temperature"
  }
}

401 - Non Autorizzato

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error"
  }
}

404 - Modello Non Trovato

{
  "error": {
    "message": "Model 'unknown-model' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

429 - Limite di Rate

{
  "error": {
    "message": "Rate limit exceeded. Please upgrade your tier or try again later.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500 - Errore del Server

{
  "error": {
    "message": "Internal server error",
    "type": "server_error"
  }
}

503 - Servizio Non Disponibile

{
  "error": {
    "message": "Service temporarily unavailable",
    "type": "service_unavailable_error"
  }
}

Esempi per Linguaggio

Python con requests

import requests
import json

# Configuration
# Il est recommandé de protéger votre clé API en utilisant des variables d'environnement.
# Exemple: API_KEY = os.getenv("LLMAAS_API_KEY")
API_KEY = "VOTRE_TOKEN_API"
BASE_URL = "https://api.ai.cloud-temple.com/v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# Chat completion
payload = {
    "model": "gpt-oss:120b",
    "messages": [
        {"role": "user", "content": "Bonjour !"}
    ],
    "max_tokens": 100
}

try:
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=payload,
        timeout=30 # Ajout d'un timeout pour la requête
    )

    response.raise_for_status() # Lève une exception pour les codes d'erreur HTTP (4xx, 5xx)
    result = response.json()
    print(result["choices"][0]["message"]["content"])

except requests.exceptions.HTTPError as e:
    print(f"Erreur HTTP: {e.response.status_code} - {e.response.text}")
except requests.exceptions.RequestException as e:
    print(f"Erreur réseau: {e}")
except json.JSONDecodeError:
    print(f"Erreur de décodage JSON: {response.text}")
except Exception as e:
    print(f"Une erreur inattendue est survenue: {e}")

Python con Streaming

import requests
import json

def stream_chat(message, model="gpt-oss:120b"):
    # Il est recommandé de protéger votre clé API en utilisant des variables d'environnement.
    # Exemple: API_KEY = os.getenv("LLMAAS_API_KEY")
    API_KEY = "VOTRE_TOKEN_API"
    BASE_URL = "https://api.ai.cloud-temple.com/v1"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    }

    payload = {
        "model": model,
        "messages": [{"role": "user", "content": message}],
        "stream": True,
        "max_tokens": 200
    }

    try:
        response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers=headers,
            json=payload,
            stream=True,
            timeout=30 # Ajout d'un timeout pour la requête
        )

        response.raise_for_status() # Lève une exception pour les codes d'erreur HTTP (4xx, 5xx)

        for line in response.iter_lines():
            if line:
                line = line.decode('utf-8')
                if line.startswith('data: '):
                    data = line[6:]  # Enlever 'data: '
                    if data == '[DONE]':
                        break
                    try:
                        chunk = json.loads(data)
                        content = chunk['choices'][0]['delta'].get('content', '')
                        if content:
                            print(content, end='', flush=True)
                    except json.JSONDecodeError:
                        print(f"Erreur de décodage JSON dans le stream: {data}")
                        continue
        print() # Nouvelle ligne après le stream
    except requests.exceptions.HTTPError as e:
        print(f"Erreur HTTP: {e.response.status_code} - {e.response.text}")
    except requests.exceptions.RequestException as e:
        print(f"Erreur réseau: {e}")
    except Exception as e:
        print(f"Une erreur inattendue est survenue: {e}")

# Utilisation
stream_chat("Expliquez la physique quantique")

JavaScript/Node.js

const axios = require('axios');

// Configuration
// Il est recommandé de protéger votre clé API en utilisant des variables d'environnement.
// Exemple: const API_KEY = process.env.LLMAAS_API_KEY;
const API_KEY = 'VOTRE_TOKEN_API';
const BASE_URL = 'https://api.ai.cloud-temple.com/v1';

async function chatCompletion(message) {
    try {
        const response = await axios.post(
            `${BASE_URL}/chat/completions`,
            {
                model: 'gpt-oss:120b',
                messages: [
                    { role: 'user', content: message }
                ],
                max_tokens: 100
            },
            {
                headers: {
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${API_KEY}`
                },
                timeout: 30000 // Ajout d'un timeout pour la requête (30 secondes)
            }
        );

        return response.data.choices[0].message.content;
    } catch (error) {
        console.error('Erreur:', error.response?.data || error.message);
        // Gestion plus détaillée des erreurs peut être ajoutée ici si nécessaire
        // Par exemple: if (error.response?.status === 429) { console.error("Rate limit exceeded"); }
    }
}

// Utilisation
chatCompletion('Bonjour !').then(response => {
    if (response) {
        console.log(response);
    }
});

JavaScript con Fetch (Node.js lato server)

Eseguire questo esempio lato server con Node.js che dispone di fetch nativo. Impostare LLMAAS_API_KEY nell'ambiente del server. Per un'interfaccia web, il browser chiama il vostro backend, che autentica l'utente e verifica i suoi diritti prima di chiamare LLMaaS. La chiave di servizio rimane esclusivamente lato server e non deve essere integrata nel codice inviato al browser.

async function fetchCompletion(message) {
    const apiKey = process.env.LLMAAS_API_KEY;
    if (!apiKey) {
        throw new Error('La variable LLMAAS_API_KEY doit être définie côté serveur.');
    }
    const response = await fetch('https://api.ai.cloud-temple.com/v1/chat/completions', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`
        },
        body: JSON.stringify({
            model: 'gpt-oss:120b',
            messages: [
                { role: 'user', content: message }
            ],
            max_tokens: 100
        })
    });

    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }

    const data = await response.json();
    return data.choices[0].message.content;
}

Buone Pratiche

Gestione degli Errori

def safe_api_call(payload):
    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if response.status_code == 429:
            print("Rate limit atteint, attendre...")
            time.sleep(60)  # Attendre 1 minute
            return safe_api_call(payload)  # Retry
        else:
            print(f"Erreur HTTP: {e}")
    except requests.exceptions.RequestException as e:
        print(f"Erreur réseau: {e}")

Ottimizzazione dei Costi

Utilizzare modelli appropriati : Modelli più piccoli per i test
Limitare max_tokens : Evitare risposte troppo lunghe
Riutilizzare le conversazioni : Finestra di contesto efficace
Monitoraggio : Seguire il proprio utilizzo nella Console

Sicurezza

Proteggere il proprio token : Variabili d'ambiente
Rotazione regolare : Cambiare le chiavi periodicamente
Validazione input : Pulire i dati degli utenti
Rate limiting client : Implementare i propri limiti

SDK e Integrazioni

Per le chiamate supportate, configurare l'SDK OpenAI con l'URL di base e la chiave LLMaaS. Consultare l'ambito di compatibilità prima di migrare un'integrazione :

OpenAI Python SDK

from openai import OpenAI

# Il est recommandé de protéger votre clé API en utilisant des variables d'environnement.
# Exemple: api_key=os.getenv("LLMAAS_API_KEY")
client = OpenAI(
    api_key="VOTRE_TOKEN_API",
    base_url="https://api.ai.cloud-temple.com/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-oss:120b",
        messages=[
            {"role": "user", "content": "Bonjour !"}
        ],
        max_tokens=50 # Ajout de max_tokens pour cohérence avec les tests
    )

    print(response.choices[0].message.content)

except Exception as e:
    print(f"Erreur OpenAI SDK: {e}")

LangChain

Utilizzare le versioni validate e prerequisiti LangChain. Gli esempi seguenti sono stati verificati con risposte LLMaaS simulate.

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

# Configuration du chat model (compatible avec LLMaaS)
# Il est recommandé de protéger votre clé API en utilisant des variables d'environnement.
# Exemple: api_key=os.getenv("LLMAAS_API_KEY")
chat = ChatOpenAI(
    api_key="VOTRE_TOKEN_API",
    base_url="https://api.ai.cloud-temple.com/v1",
    model="gpt-oss:120b",
    max_tokens=200
)

try:
    # Utilisation avec messages
    messages = [HumanMessage(content="Expliquez l'IA en 3 phrases")]
    response = chat.invoke(messages)
    print(response.content)

    # Ou avec une simple chaîne
    response = chat.invoke("Bonjour, comment ça va ?")
    print(response.content)

except Exception as e:
    print(f"Erreur LangChain: {e}")

Utilizzo degli Embeddings

Utilizzare OpenAIEmbeddings con check_embedding_ctx_length=False per inviare i testi direttamente, senza pre-tokenizzazione locale. Questa impostazione è documentata da LangChain. Il parametro encoding_format="float", passato tramite model_kwargs, richiede vettori numerici.

import os
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    api_key=os.environ["LLMAAS_API_KEY"],
    base_url="https://api.ai.cloud-temple.com/v1",
    model="granite-embedding:278m",
    check_embedding_ctx_length=False,
    model_kwargs={"encoding_format": "float"},
)

vectors = embeddings.embed_documents(["Premier document", "Deuxième document"])
query_vector = embeddings.embed_query("Ma question")

Questa impostazione disabilita anche il taglio automatico dei testi in base alla finestra di contesto di questo client. Tagliare i documenti prima della chiamata e rispettare il limite del modello scelto, come nel tutorial RAG.

Gli errori dell'API risalgono sotto forma di eccezioni : non vengono sostituiti da una lista vuota. Gestirli a livello della propria applicazione prima di procedere con l'indicizzazione o la ricerca.

Validazione : formato delle richieste confrontato con il contratto e il codice del proxy ; invio di testi singoli e in batch, autenticazione, lettura dei vettori e propagazione degli errori HTTP verificati con risposte simulate. Non è stata effettuata alcuna chiamata di produzione per questa validazione.

Supporto

Documentazione : Guida rapida
Catalogo modelli : Elenco completo
Console : Gestione e monitoraggio tramite Console Cloud Temple
Supporto : Tramite la Console Cloud Temple

Compatibilità OpenAI​

URL di Base​

Autenticazione​

Rate Limiting e Fatturazione​

Il Principio dei Livelli (Tier) : Livello di Accesso, Budget e Capacità​

Capacità tecniche dei livelli​

Header di Limite​

Errore 429 - Limite Raggiunto​

Endpoint​

POST /v1/chat/completions​

Richiesta​

Parametri​

Risposta Standard​

Risposta con Chiamata di Strumento​

Streaming (SSE)​

Richieste Multimodali (Visione)​

Esempio di Richiesta Vision​

POST /v1/completions​

Richiesta​

Parametri​

Risposta​

POST /v1/audio/transcriptions​

Richiesta​

Parametri​

Risposta (json)​

POST /v1/embeddings​

Richiesta​

Parametri​

Risposta​

POST /v1/rerank​

Richiesta​

Parametri​

Risposta​

Esempio Python (SDK Cohere)​

POST /v1/chat/completions/batch​

GET /v1/models​

Richiesta​

Risposta​

Codici di Errore​

400 - Richiesta Non Valida​

401 - Non Autorizzato​

404 - Modello Non Trovato​

429 - Limite di Rate​

500 - Errore del Server​

503 - Servizio Non Disponibile​

Esempi per Linguaggio​

Python con requests​

Python con Streaming​

JavaScript/Node.js​

JavaScript con Fetch (Node.js lato server)​

Buone Pratiche​

Gestione degli Errori​

Ottimizzazione dei Costi​

Sicurezza​

SDK e Integrazioni​

OpenAI Python SDK​

LangChain​

Utilizzo degli Embeddings​

Supporto​

Compatibilità OpenAI

URL di Base

Autenticazione

Rate Limiting e Fatturazione

Il Principio dei Livelli (Tier) : Livello di Accesso, Budget e Capacità

Capacità tecniche dei livelli

Header di Limite

Errore 429 - Limite Raggiunto

Endpoint

POST /v1/chat/completions

Richiesta

Parametri

Risposta Standard

Risposta con Chiamata di Strumento

Streaming (SSE)

Richieste Multimodali (Visione)

Esempio di Richiesta Vision

POST /v1/completions

Richiesta

Parametri

Risposta

POST /v1/audio/transcriptions

Richiesta

Parametri

Risposta (`json`)

POST /v1/embeddings

Richiesta

Parametri

Risposta

POST /v1/rerank

Richiesta

Parametri

Risposta

Esempio Python (SDK Cohere)

POST /v1/chat/completions/batch

GET /v1/models

Richiesta

Risposta

Codici di Errore

400 - Richiesta Non Valida

401 - Non Autorizzato

404 - Modello Non Trovato

429 - Limite di Rate

500 - Errore del Server

503 - Servizio Non Disponibile

Esempi per Linguaggio

Python con requests

Python con Streaming

JavaScript/Node.js

JavaScript con Fetch (Node.js lato server)

Buone Pratiche

Gestione degli Errori

Ottimizzazione dei Costi

Sicurezza

SDK e Integrazioni

OpenAI Python SDK

LangChain

Utilizzo degli Embeddings

Supporto