Deploy di modelli decisionali con llama.cpp su Amazon SageMaker AI

Le applicazioni che instradano richieste, selezionino azioni per gli agenti o assegnino risultati di policy spesso richiedono valutazioni su un insieme fisso di scelte, anziché generare testo libero. Distribuire questi modelli decisionali con llama.cpp su Amazon SageMaker AI offre un percorso gestito per servire modelli quantizzati su infrastrutture CPU o GPU.

Contesto e obiettivi

Questo post continua una serie dedicata ai container AWS Deep Learning Containers (DLC) specializzati per l’inferenza generativa. I precedenti articoli hanno trattato WhisperX, vLLM-Omni – Parte 1 e vLLM-Omni – Parte 2. Qui, si parte dal AWS DLC per llama.cpp per fornire completamenti chat compatibili con l’API OpenAI tramite InvokeEndpoint di SageMaker. Successivamente, si estende lo stesso runtime con SemIf (ex OpenJev), che restituisce probabilità per le opzioni dichiarate senza decodificare un token di risposta. Il campione di codice allegato comprende opzioni di deployment su CPU e GPU.

Panoramica della soluzione

La Figura 1 mostra due percorsi di deployment dallo stesso modello confezionato. Il percorso di generazione testo utilizza il container AWS DLC per llama.cpp e restituisce risposte attraverso l’API compatibile con OpenAI. Il percorso di decisione strutturata costruisce un’immagine figlia che sostituisce il server predefinito con un adattatore SemIf, restituendo probabilità per le opzioni dichiarate.

Diagramma di flusso

Figura 1: esecuzione del AWS DLC per llama.cpp o dell’immagine figlia SemIf su CPU o GPU, in base all’API e ai requisiti di latenza del workload.

Deployment standard (testo generato)

Per il percorso standard, il modello deve essere confezionato come model.tar.gz su Amazon S3 e riferito direttamente all’immagine DLC pubblicata. Il container individua il primo file .gguf nella directory /opt/ml/model, mappa la chiamata POST /invocations a llama-server all’endpoint /v1/chat/completions e passa le variabili d’ambiente SMLLAMACPP_* come argomenti a llama.cpp.

L’API HTTP llama-server non espone i logits finali né le operazioni di stato utilizzate da SemIf. Per questo motivo, il percorso decisionale strutturato impiega AWS CodeBuild per costruire un’immagine figlia, che viene poi archiviata su Amazon Elastic Container Registry (ECR). L’immagine figlia conserva le librerie compilate per CPU o CUDA del DLC, sostituendo però il suo entry point con un adattatore compatibile con SageMaker.

Schema di input e output

Modalità chat (llama.cpp)

L’AWS DLC per llama.cpp accetta lo schema OpenAI Chat Completions. Occorre inviare un array messages contenente oggetti con role e content, insieme a parametri di generazione quali max_tokens e stream:

{
"messages": [
{
"role": "user",
"content": "A customer cannot receive a password reset email. Reply with the best support queue."
}
],
"max_tokens": 64,
"stream": false
}

La risposta utilizza l’array choices compatibile con OpenAI; il testo generato si trova in choices[0].message.content.

Modalità decisione (SemIf)

SemIf adotta uno schema decisionale limitato invece dei messaggi di chat. La richiesta contiene un ID definito dal chiamante, uno stato non strutturato, una domanda e una lista ordinata di opzioni consentite:

{
"decision": {
"id": "support-route",
"state": "The customer cannot receive a password reset email.",
"question": "Which queue should handle this request?",
"options": [
{"id": "account_access", "description": "Account access support."},
{"id": "billing", "description": "Billing support."}
]
}
}

La risposta restituisce optionids, probabilities e i optionlogits grezzi nello stesso ordine, insieme a metadati relativi al prompt, al timing e al modello. Con ID di opzione stabili, l’applicazione può applicare soglie, fallback e controlli di policy senza analizzare il testo generato.

Modelli decisionali correlati

SemIf fa parte di una più ampia classe di modelli decisionali che assegnano un punteggio a risultati definiti dall’applicazione a partire da uno stato non strutturato. Altre implementazioni includono:

• Jev: modello decisionale di TypeSafe con API /v1/systemone;
• Kev: server di modelli progettato per la compatibilità con l’API TypeSafe;
• Strands Decider 2B: modello costruito appositamente per flussi di lavoro di agenti con output calibrati.

Scelta del workflow decisionale

Utilizzare questo pattern quando l’applicazione definisce le scelte consentite al momento della richiesta e necessita di un modello per interpretare il contesto non strutturato. Esempi tipici:

• Instradamento di un caso verso una coda specifica;
• Estrazione di un valore da un set noto;
• Assegnazione della priorità a un incidente;
• Verifica di un risultato di policy;
• Selezione di un’azione per un agente.

È fondamentale mantenere autorizzazioni e regole aziendali deterministiche al di fuori del modello e validare le probabilità prodotte prima di adottarle come confidenza operativa.

Quando usare la modalità testo vs. decisione

Adottare il percorso standard di generazione testo di SageMaker AI quando si richiedono completamenti chat compatibili con OpenAI tramite InvokeEndpoint. L’immagine SageMaker AI mappa POST /invocations all’endpoint llama-server /v1/chat/completions. Costruire un’immagine figlia solo quando l’applicazione necessita di comportamenti non forniti da questa interfaccia, come l’accesso diretto ai logits e allo stato offerto da SemIf.

Rimuovere la generazione del token di risposta non elimina l’inferenza del modello: il modello elabora comunque lo stato completo, la domanda e le descrizioni delle opzioni prima che SemIf legga i logits finali. È consigliabile mantenere i prompt concentrati e valutare il modello con decisioni etichettate dalla propria applicazione prima della messa in produzione.

Ottimizzazione per latenza e qualità

Il benchmark riportato si riferisce all’estensione SemIf, non all’endpoint di generazione testo. Dimensione del modello, quantizzazione, lunghezza del prompt, runtime e numero di thread CPU influiscono su ciascuna decisione. Per quantificare questi trade‑off, sono stati inviati i medesimi 231 task pubblici JevBench in modalità seriale a un endpoint CPU e a uno GPU.

Configurazione e risultati

Modello	Quantizzazione	Istanza	Thread/GPU	Risposte valide	Precisione	p50	p95
Qwen3.5‑4B	Q4KM	ml.c6i.8xlarge	32	231/231	179/231 (77.5 %)	1.715 s	19.291 s
Qwen3.5‑4B	Q4KM	ml.g6e.xlarge	full GPU offload	231/231	180/231 (77.9 %)	0.352 s	0.599 s

Rispetto alla configurazione CPU, l’endpoint GPU è stato 4,9 volte più veloce al p50 e 32,2 volte più veloce al p95. Il campione utilizza la funzionalità instance pools di SageMaker AI per elencare i tipi di istanza GPU compatibili in ordine di priorità, consentendo a SageMaker di selezionare un’alternativa qualora la prima scelta non fosse disponibile. L’ordine dei pool è: g6e, g6, g5, poi g4dn. SageMaker ha selezionato ml.g6e.xlarge e i log di avvio hanno confermato che llama.cpp ha scaricato tutti i 34 strati del modello su una NVIDIA L40S.

Le immagini CPU e GPU usano build diverse di llama.cpp e hanno prodotto previsioni differenti su sei task difficili. La differenza di accuratezza a risposta singola è stata trattata come variazione di runtime, non come prova che lo scaricamento su GPU migliori la qualità del modello.

Modelli più piccoli hanno ridotto la latenza mediana, ma le versioni 2 B e 0.8 B hanno raggiunto rispettivamente il 66,7 % e il 58,4 % di accuratezza. Per questo motivo, il campione mantiene il modello 4 B Q4KM come impostazione predefinita orientata alla qualità. Queste misurazioni includono la latenza di rete e non costituiscono garanzie di servizio.

Linee guida per la scelta tra CPU e GPU

• Usare CPU per workload in background, offline o a bassa intensità, che non richiedono latenza e possono tollerare risposte di qualche secondo.
• Usare GPU per decisioni interattive, prompt lunghi o carichi con obiettivi stringenti di latenza di coda.
• Mantenere le descrizioni di stato e opzioni concise; raggruppare decisioni con lo stesso stato in un’unica richiesta.
• Scalare le istanze endpoint per gestire la concorrenza.
• Il punteggio condiviso riutilizza il prefisso comune del prompt, mentre l’adattatore restituisce risposte HTTP 503 ritentabili anziché consentire una coda illimitata attorno al contesto stateful di llama.cpp.

Prerequisiti

Per avviare il deployment sono necessari:

• Un account AWS e un bucket S3 nella regione di deployment.
• Python 3.10 o versioni successive, Git e l’AWS Command Line Interface (AWS CLI).
• Un ruolo di servizio CodeBuild specifico per l’estensione opzionale SemIf.
• Un ruolo IAM che SageMaker AI possa assumere.
• Permessi per SageMaker AI, Amazon ECR, Amazon S3, CodeBuild, azioni pass‑role di IAM e Amazon CloudWatch Logs.
• Quota per un endpoint SageMaker in tempo reale compatibile con CPU x86 o GPU NVIDIA.

Esempio di deployment testuale (CPU)

L’esempio di generazione testo utilizza il DLC CPU e un’istanza CPU fissa. Il codice prepara il modello, lo carica su S3, crea un endpoint SageMaker con l’immagine llama-cpp:server-sagemaker-cpu-v1 e invia una richiesta di tipo Chat Completion. La risposta è analizzata tramite l’array choices.

Esempio di deployment SemIf (GPU opzionale)

L’estensione SemIf mantiene la CPU come impostazione predefinita per carichi non sensibili alla latenza, ma offre la possibilità di passare a GPU per ridurre drasticamente i tempi di coda. Il processo prevede:

• Creare un file Dockerfile che parte dall’immagine DLC per llama.cpp;
• Sostituire l’entry point con lo script di adattatore SemIf;
• Utilizzare CodeBuild per costruire l’immagine e spingerla su ECR;
• Definire un endpoint SageMaker che punti all’immagine personalizzata, scegliendo un’istanza ml.g6e.xlarge per scaricamento completo su GPU;
• Inviare richieste con lo schema decisionale (ID, stato, domanda, opzioni) e interpretare le probabilità e i logits restituiti.

Best practice operative

• Mantenere i prompt brevi e focalizzati per minimizzare il tempo di inferenza.
• Validare le probabilità con dataset di riferimento prima della produzione.
• Separare le regole di autorizzazione e di policy dal modello per garantire determinismo.
• Monitorare i log di CloudWatch per rilevare errori 503 e implementare meccanismi di retry.
• Sfruttare il bilanciamento automatico di SageMaker per scalare in base al traffico.

Conclusioni

Utilizzare llama.cpp su Amazon SageMaker AI consente di servire modelli decisionali quantizzati in modo gestito, sia su CPU che su GPU. La modalità standard fornisce completamenti chat compatibili con OpenAI, mentre l’adattatore SemIf permette di ottenere direttamente probabilità e logits per insiemi di opzioni predefinite, eliminando la necessità di analizzare testi generati. I benchmark dimostrano che le GPU offrono velocità di latenza significativamente superiori, sebbene la precisione rimanga sostanzialmente invariata rispetto alla CPU. Con i prerequisiti adeguati e le best practice di deployment, le organizzazioni possono integrare questi modelli decisionali nei loro flussi di lavoro, migliorando l’efficienza di routing, priorizzazione e selezione delle azioni automatizzate.