Perché l'SDK OpenAI copre ciò di cui hai bisogno
Quando le persone cercano un SDK per l'API Qwen, di solito vogliono una libreria client che gestisca autenticazione, ritentativi, streaming e risposte tipizzate. Gli SDK OpenAI fanno già tutto questo, e questo servizio implementa la stessa interfaccia HTTP: POST /v1/chat/completions, POST /v1/responses e GET /v1/models. Qualsiasi client che permetta di sovrascrivere l'URL di base può comunicare con esso.
Una precisazione prima di iniziare. Questa non è l'API ufficiale di Alibaba o di qualsiasi altro fornitore di modelli, e non è un router che inoltra le tue richieste altrove. È un singolo modello open-weight, eseguito da un provider indipendente e ottimizzato per rispondere senza rifiuto dei contenuti per uso adulto legale. L'unico ID modello che passi è uncensored.
Questo rende la migrazione semplice. Se il tuo progetto chiama già un modello chat ospitato tramite l'SDK OpenAI, devi modificare tre valori: l'URL base, la chiave API e il nome del modello. Nient'altro nel tuo codice deve essere modificato.
Installa ed effettua la prima chiamata
Installa il pacchetto ufficiale per Python o Node. Non c'è nulla di specifico del servizio da aggiungere.
pip install openai
# Node: npm install openai
Crea una chiave nella pagina chiave API, poi esportala in modo che non finisca mai nel tuo codice sorgente.
export API_KEY="paste-your-key-here"
Ora lo script Python più piccolo utile. Il client legge la chiave dall'ambiente e invia richieste al servizio invece che a OpenAI.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what a context window is in two sentences."},
],
temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)
Se preferisci HTTP grezzo, la stessa richiesta in curl appare così:
curl https://api.uncensoredqwen.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello."}]}'Streaming delle risposte con l'SDK
Imposta stream=True ed esegui l'iterazione sui chunk. Il servizio invia eventi server-sent e riporta l'utilizzo dei token alla fine dello streaming, così puoi registrare i costi senza una seconda chiamata.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a short product description for a desk lamp."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
print("\nTokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
Tieni a mente una cosa: una richiesta in streaming occupa il suo slot di concorrenza fino alla fine dello stream. Se un consumatore è lento o dimentichi di chiudere lo stream, raggiungerai il limite di concorrenza prima del previsto.
Lo stesso pattern in Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredqwen.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses of JSON mode." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}Chiamata di funzioni e modalità JSON
I parametri dell'SDK che usi già per gli strumenti passano direttamente: tools, tool_choice, streaming tool_calls, e i risultati restituiti come messaggi con role: "tool". Un round trip minimo è così:
import os, json
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by id",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
messages.append(first.choices[0].message)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps({"status": "shipped"}),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
Per l'output strutturato, passa response_format={"type": "json_object"} e dì anche "rispondi in JSON" nel prompt. La modalità JSON chiede al modello un output JSON, ma il tuo codice dovrebbe comunque analizzarlo e validare nomi e tipi di campo prima di usarli.
Le impostazioni di campionamento come temperature, top_p, stop, seed e le penalità vengono passate, quindi il tuning esistente si trasferisce.
Gestisci gli errori 429 e leggi le intestazioni
Lo SDK genera un'eccezione di limite di richieste su HTTP 429, e il corpo della risposta ti dice quale limite hai raggiunto. Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova permette 2 richieste concorrenti e 60 al minuto.
| Codice di errore | Significato | Cosa fare |
|---|---|---|
rate_limited | Troppe richieste al minuto | Distribuisci le chiamate o aggiungi un limitatore lato client |
concurrency | Troppe richieste contemporaneamente | Limita il tuo pool di worker a 8 (2 su una chiave di prova) |
429 con Retry-After: 5 | Sovraccarico temporaneo | Attendi 5 secondi e ritenta |
Ogni risposta include X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency. Per leggerli con l'SDK Python, usa il wrapper per risposta grezza:
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "ping"}],
max_tokens=5,
)
print("Balance:", raw.headers.get("X-Balance-USD"))
print("Request id:", raw.headers.get("X-Request-Id"))
completion = raw.parse()
Le richieste fallite o rifiutate non vengono addebitate, quindi un nuovo tentativo dopo un 429 non ti costa due volte. L'articolo esistente su errori comuni dell'API Qwen copre altri errori di configurazione che le persone commettono.
Quanto costa una chiamata
La tariffa è $0,15 per 1M di token di input e $0,50 per 1M di token di output, pagati dal credito prepagato. Prendi una richiesta con 2.000 token di prompt e 500 token di completamento:
- Input: 2.000 x $0,15 / 1.000.000 = $0,0003
- Output: 500 x $0,50 / 1.000.000 = $0,00025
- Totale: $0.00055
Il credito di prova da $0,50 copre circa 900 richieste di questa dimensione ($0,50 / $0,00055 fa circa 909). Il credito di prova si ottiene con un clic nella pagina delle chiavi dopo la registrazione, non richiede una carta e dura 7 giorni; l'articolo sul piano gratuito spiega come funziona. Le ricariche a pagamento partono da $20 e la pagina dei prezzi elenca i livelli di bonus e i metodi di pagamento accettati.
Il contesto è di 100.000 token per prompt e completamento insieme, e max_tokens è opzionale. Impostarlo è comunque una buona abitudine quando vuoi un limite superiore prevedibile sul costo.
Spostamento di un progetto esistente
La maggior parte dei lettori arriva con codice che chiama già un modello chat. Una breve checklist mantiene il passaggio senza intoppi:
- Modifica
base_url(obaseURLin Node) ahttps://api.uncensoredqwen.com/v1. Mantieni il suffisso/v1e non aggiungere/chat/completionstu stesso, perché l'SDK aggiunge il percorso alla fine. - Sostituisci la chiave con quella del tuo account. L'autenticazione è un'intestazione standard
Authorization: Bearer, che l'SDK costruisce per te. - Sostituisci il nome del modello con
uncensored. Le richieste con un nome di modello sconosciuto falliranno, quindi cerca nel tuo codice i nomi hard-coded. - Rimuovi qualsiasi campo di richiesta per funzionalità che il servizio non offre, come input immagine o chiamate di embeddings.
- Esegui una chiamata a
GET /v1/modelscome test di fumo. Se elenca il modello, il tuo URL e la tua chiave sono corretti.
I framework che avvolgono il client OpenAI di solito espongono le stesse due impostazioni con nomi come openai_api_base o OPENAI_BASE_URL. Se il tuo strumento offre una variabile d'ambiente per l'URL di base, puoi cambiare un'intera applicazione senza toccarne il codice sorgente. Prova prima con una chiave di prova, poiché i suoi limiti inferiori di 2 richieste concorrenti e 60 al minuto mostreranno rapidamente se la tua applicazione apre più connessioni parallele di quanto pianificato.
La gestione del contesto merita un secondo sguardo. La finestra qui è di 100.000 token condivisi tra prompt e completamento. Se la tua vecchia configurazione ha tagliato la cronologia a una dimensione diversa, puoi allentare o stringere quel taglio per adattarla, ma tieni d'occhio il costo di reinviare una lunga cronologia ad ogni turno.
Suggerimenti pratici per il codice di produzione
- Tieni la chiave fuori dal repository. Leggila da una variabile d'ambiente o da un archivio segreti, come negli esempi sopra.
- Imposta un timeout. L'SDK accetta un argomento
timeoutsul client. Le generazioni lunghe con streaming necessitano di un timeout di lettura generoso. - Definisci un limite per i tuoi worker. Un pool di thread o un semaforo dimensionato al tuo limite di concorrenza evita la maggior parte degli errori 429 prima che accadano.
- Registra l'ID della richiesta. Se contatti il supporto, il valore da
X-Request-Ididentifica la chiamata. - Tieni d'occhio il saldo. Leggi
X-Balance-USDdalle risposte, o chiamaGET /v1/balance, così un lavoro batch si ferma prima che il credito si esaurisca.
Il modello è solo testo. Non c'è generazione di immagini, audio o video, nessun embedding e nessun fine-tuning, quindi non pianificare attorno a questi metodi SDK. I dettagli completi sui parametri sono nella documentazione. I prompt non sono usati per l'addestramento.
