Esercitazione sulla compattazione delle API per le risposte OCI
Utilizzare l'SDK Python OpenAI con l'API OCI Responses per compattare in modo esplicito o automatico la cronologia delle conversazioni, quindi continuare la conversazione con il contesto restituito.
Panoramica
Man mano che una conversazione cresce, un'applicazione invia più cronologia ad ogni richiesta. La compattazione riduce la cronologia a una rappresentazione più piccola che il modello può utilizzare in turni successivi. Utilizzarlo per gestire il contesto nelle conversazioni a lungo termine e nei flussi di lavoro degli agenti.
In questa esercitazione viene descritta una configurazione di distribuzione di finzione, viene compattata la conversazione e viene posta una domanda di follow-up per verificare i dettagli del modello conservato.
Puoi utilizzare l'SDK Python OpenAI con una chiave API OCI Generative AI e un endpoint OCI regionale. L'SDK fornisce l'interfaccia client. Le richieste vengono autenticate con OCI e inviate all'AI generativa OCI.
Tutti i modelli supportati dall'API delle risposte OCI, inclusi i modelli importati, supportano la compattazione sia esplicita che automatica. La compattazione è disponibile nelle aree AI aziendali e segue l'area e la disponibilità dell'hosting di ogni modello. Entrambe le modalità sono supportate per l'inferenza su richiesta e l'hosting dedicato.
| Modalità | Operation | Cosa inviare dopo |
|---|---|---|
| Esplicito (standalone) | Chiamare client.responses.compact(...), che invia POST /responses/compact, quando un'applicazione è pronta per compattare la cronologia. |
Passare l'array output restituito completo, seguito dal messaggio dell'utente successivo. |
| Automatico (gestito dal server) | Chiamare client.responses.create(...) con context_management e una soglia token. OCI compatta il contesto durante POST /responses quando viene raggiunta la soglia. |
Con store=False, passare l'elemento di compattazione più recente e tutti gli elementi di output successivi, seguiti dal messaggio utente successivo. Se non viene restituito alcun elemento di compattazione, conservare la cronologia esistente e aggiungere il nuovo output. |
Gli elementi di compattazione contengono un contesto cifrato e opaco. Conservare i campi e l'ordine serializzati. Non leggere, modificare o sostituire i loro contenuti con un riepilogo di testo.
La compattazione utilizza i token del modello e può perdere i dettagli durante la generazione del sintetico. Compatta prima di raggiungere il limite di contesto del modello e lascia spazio alla risposta e ai giri successivi. La compattazione esplicita è sincrona e non supporta lo storage, l'esecuzione in background o lo streaming.
Gli esempi gestiscono la cronologia nell'applicazione e impostano store=False sulle richieste di creazione delle risposte. Per il workflow separato che utilizza lo stato di conversazione gestito da OCI, vedere Usa memoria agente con API risposte.
Informazioni preliminari
Per completare questo tutorial, è necessario:
- Accesso all'API Risposte OCI in un'area AI aziendale supportata. Selezionare un modello da Modelli e aree supportati disponibile per la tenancy nell'area selezionata. Per i modelli di base, consulta i modelli per area per la disponibilità di hosting on-demand e dedicato.
- Una chiave API OCI Generative AI con accesso al modello e al progetto selezionati. Se necessario, creare una chiave API e aggiungerne le autorizzazioni.
- OCID progetto AI generativa OCI. La compattazione richiede il contesto di progetto per ogni modello. Se necessario, creare un progetto.
- Python 3.10 o versioni successive su macOS, Linux o sottosistema Windows per Linux. I comandi utilizzano una shell compatibile con Bash.
Gli esempi utilizzano l'SDK Python OpenAI con credenziali OCI e un URL di base OCI. Non richiedono una chiave API OpenAI, l'SDK Python OCI o l'interfaccia CLI OCI.
Questi esempi utilizzano l'autenticazione della chiave API OCI Generative AI. Compaction supporta anche l'autenticazione IAM OCI. Per questa impostazione, vedere Autenticazione basata sull'AI generativa basata su IAM. È necessario un OCID progetto AI generativa OCI con uno dei metodi di autenticazione.
1. Preparare l'ambiente Python e l'accesso OCI
2. Compatta una conversazione in modo esplicito
In questo esempio viene creata una risposta, viene aggiunto l'output completo della risposta alla cronologia e viene richiamato responses.compact. Sostituisce quindi la cronologia con l'output compatto completo e chiede informazioni sulla finestra di conservazione e manutenzione del backup della distribuzione.
La breve conversazione rende la sequenza facile da seguire. In un'applicazione, chiamare la compattazione quando la cronologia accumulata deve essere ridotta e si adatta comunque al limite di contesto del modello.
3. Abilita compattazione automatica
Per la compattazione automatica, includere context_management in una richiesta di creazione di risposta con type: "compaction" e un compact_threshold esplicito di almeno 1000 token. Selezionare una soglia inferiore al limite di contesto del modello e lasciare spazio all'output e ai turni successivi.
In questo esempio vengono creati 40 scambi di stato sintetici a livello locale per creare una cronologia più lunga. Invia la cronologia in una richiesta con una soglia di 1.000 token, controlla la compattazione e invia una richiesta di follow-up. I 40 exchange non effettuano chiamate API separate.
4. Uso di un modello ospitato su un cluster AI dedicato (facoltativo)
Puoi utilizzare modelli che supportano l'API delle risposte OCI per l'inferenza su richiesta o ospitarli su cluster AI dedicati, in base alle opzioni di hosting di ciascun modello. Entrambe le modalità di compattazione funzionano con entrambe le opzioni di hosting. Gli esempi precedenti utilizzano un ID modello su richiesta. Quando si ospita un modello in un cluster AI dedicato, si crea un endpoint modello su tale cluster per chiamare il modello. Passa l'OCID di tale endpoint come valore model della richiesta.
Il cluster di hosting fornisce le risorse di calcolo per l'inferenza. È possibile creare diversi endpoint per lo stesso modello hosted, ad esempio per fornire ad applicazioni, team o centri di costo diversi i propri punti di accesso. Ogni endpoint ha il proprio OCID e gli endpoint condividono le risorse di computazione del cluster. Per ulteriori informazioni, vedere Gestione degli endpoint del modello.
Controllare i risultati
Un elemento di compattazione restituito conferma che si è verificata la compattazione. Non stabilisce che ogni dettaglio sia stato conservato. Rivedere la risposta di follow-up rispetto alla configurazione originale.
Per valutare la compattazione per un'applicazione, utilizzare conversazioni rappresentative con fatti e istruzioni importanti per il flusso di lavoro. Confronta la stessa domanda di follow-up con la storia completa, con la compattazione esplicita e con la compattazione automatica. Controllare i fact conservati, le istruzioni seguenti, il formato di output e qualsiasi chiamata di strumento richiesta dal flusso di lavoro.
Eseguire diversi esempi e regolare la soglia di compattazione in base a ciò che si osserva. La compattazione stessa utilizza i token modello, quindi un contesto più piccolo non garantisce un minore utilizzo totale dei token o risposte più rapide per ogni richiesta.
Risoluzione dei problemi
| Sintomo | Cosa controllare |
|---|---|
| Uno script segnala una variabile di ambiente mancante. | Impostare OCI_BASE_URL, OCI_MODEL e OCI_OPENAI_PROJECT nella shell in cui viene eseguito lo script. |
401 o 403 | Confermare che si sta utilizzando una chiave API OCI Generative AI e l'endpoint OCI regionale corretto. Controllare la validità della chiave, le autorizzazioni di progetto e l'accesso all'endpoint del modello o dell'inferenza. |
404 per /responses/compact | Verificare che l'URL di base termini in /openai/v1. Verificare che l'ID modello o l'OCID endpoint di inferenza siano corretti e disponibili nell'area selezionata. |
| Contesto progetto mancante in una richiesta. | Impostare OCI_OPENAI_PROJECT sull'OCID del progetto AI generativa OCI e passarlo tramite project= durante la creazione del client SDK. Il contesto del progetto è obbligatorio per ogni modello. |
| La compattazione automatica non restituisce un elemento di compattazione. | Verificare che la richiesta includa context_management con type: "compaction" e una soglia di almeno 1000 token. Usa una cronologia più lunga o riduci una soglia più grande mantenendola pari o superiore a 1.000. |
L'SDK non dispone di un metodo responses.compact. | Attivare l'ambiente virtuale e installare openai>=2.45.0. Controllare la versione installata con python -m pip show openai. |
| Una risposta di follow-up perde i dettagli previsti. | Per la compattazione esplicita, passare l'array output restituito completo. Per la compattazione automatica, conservare l'elemento di compattazione più recente e tutti gli elementi di output successivi. Se non viene restituito alcun elemento di compattazione, conservare la cronologia esistente e il nuovo output. La interazione può comportare la perdita dei dettagli, pertanto è possibile anche valutare il modello e la soglia mediante conversazioni rappresentative. |
Passi successivi
- Rivedere Gestisci contesto con compattazione per conoscere il funzionamento e i limiti dell'API.
- Informazioni sulla cronologia delle conversazioni gestite da OCI.
- Per informazioni sull'interfaccia SDK compatibile, consultare la guida alla compattazione OpenAI. Utilizzare i requisiti specifici di OCI in questa esercitazione per le richieste OCI.