Come installare un LLM in Python: locale o API

Due significati di installazione di un LLM

Quando le persone chiedono come installare llm in python, di solito intendono una di due cose. La prima è eseguire un modello in locale: scaricare i pesi e caricarli con una libreria sulla tua CPU o GPU. La seconda è installare una libreria client in modo che il tuo codice Python possa comunicare con un modello che gira da qualche altra parte. Entrambe sono valide e quella giusta dipende dall'hardware e da cosa vuoi costruire.

La rotta API è molto più breve. Esegui pip install openai, punta il client su una base URL e chiama il modello. Nessun peso, nessun driver GPU, nessuna pianificazione della memoria. Il resto di questa pagina fornisce i passaggi e il codice per quella rotta, con una breve sezione su quella locale così da poter confrontare.

Installazione locale o API ospitata: come scegliere

Domanda	Installazione locale	API Ospitata
Cosa installi	Una libreria di inferenza più i pesi del modello	Il pacchetto openai
Hardware	Memoria e di solito una GPU dimensionata per il modello	Qualsiasi macchina in grado di effettuare chiamate HTTPS
Costo	Il tuo hardware e l'elettricità	Per token, da credito prepagato
Funziona offline	Sì	No
Tempo alla prima risposta	Download, configurazione, regolazione	Qualche minuto

L'installazione locale ha senso se devi tenere tutto su una macchina, devi lavorare offline o vuoi sperimentare con i pesi stessi. Librerie come i binding di llama.cpp o Hugging Face transformers sono i punti di partenza soliti; controlla la loro documentazione per i requisiti hardware, poiché dipendono dalla dimensione del modello che scegli.

L'API ha senso se vuoi un risultato funzionante rapidamente, il tuo laptop non può contenere un modello grande o la tua app deve servire molti utenti. Paghi per token invece di acquistare hardware. Per questo servizio il costo è $0,15 per 1M di token di input e $0,50 per 1M di token di output, senza abbonamento. La pagina dei prezzi ha i dettagli.

Passaggio 1: crea un ambiente virtuale e installa il pacchetto

Usa un ambiente virtuale in modo che l'installazione rimanga pulita. Qualsiasi versione recente di Python 3 funziona con il pacchetto openai.

Copypython3 -m venv .venv
source .venv/bin/activate
pip install openai

Poi hai bisogno di una chiave. Iscriviti alla pagina delle chiavi API con Google o con email e password. I nuovi utenti possono richiedere $0,50 di credito di prova lì con un clic, valido per 7 giorni e senza carta. Memorizza la chiave in una variabile d'ambiente invece che nel file di origine:

Copyexport API_KEY="paste-your-key-here"

Passaggio 2: effettua la tua prima chiamata

Il servizio è compatibile con OpenAI, quindi le uniche modifiche rispetto a uno script OpenAI standard sono la base URL e l'ID del modello. L'ID del modello è uncensored.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.getaiapikey.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what a context window is in two sentences."},
    ],
    temperature=0.7,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Se questo stampa una risposta e due conteggi di token, l'installazione è completata. Per verificare che la tua chiave funzioni e vedere l'ID del modello, puoi anche chiamare GET /v1/models:

Copyfor m in client.models.list():
    print(m.id)

La stessa richiesta dalla shell, senza Python affatto, è una singola chiamata curl a https://api.getaiapikey.com/v1/chat/completions con l'intestazione Authorization: Bearer seguita dalla tua chiave. La guida rapida nella documentazione la mostra per esteso.

Passaggio 3: stream dei token in arrivo

Aspettare che finisca una risposta lunga prima di stampare qualcosa sembra lento. Imposta stream=True e il server invia i token tramite server-sent events. Puoi chiedere un riepilogo dell'utilizzo nell'ultimo chunk con stream_options.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short scene set in a lighthouse."}],
    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 chunk.usage:
        print("\n", chunk.usage.total_tokens, "tokens")

Un dettaglio importante per la produzione: una richiesta in streaming mantiene il suo slot di concorrenza fino alla fine dello stream. Una chiave completa permette 8 richieste concorrenti, quindi se la tua app apre molti stream lunghi, chiudili quando l'utente si disconnette.

Passaggio 4: modalità JSON e chiamata di funzioni

Per un output strutturato, imposta response_format su un oggetto JSON. Indica anche al modello nel prompt di rispondere in JSON, perché l'impostazione garantisce una sintassi JSON valida ma non i nomi di campo che vuoi.

Copyimport json

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"title\": string, \"tags\": [string]}"},
        {"role": "user", "content": "Give me a title and tags for a post about slow travel."},
    ],
    response_format={"type": "json_object"},
)
data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])

La chiamata di funzioni segue lo schema standard. Descrivi una funzione, il modello potrebbe chiedere di chiamarla, la esegui tu stesso e invii il risultato indietro con role: "tool".

Copytools = [{
    "type": "function",
    "function": {
        "name": "get_time",
        "description": "Return the current time for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "What time is it in Lisbon?"}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)

msg = first.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    messages.append(msg)
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps({"time": "14:05"}),
    })
    final = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools
    )
    print(final.choices[0].message.content)

Testa le chiamate di funzioni su alcuni prompt prima di affidarti a loro. Qualsiasi modello può scegliere la funzione sbagliata o riempire male un argomento, quindi valida gli argomenti nel tuo codice prima di eseguire qualsiasi cosa con effetti collaterali.

Passaggio 5: gestisci limiti ed errori

Le chiavi complete permettono 8 richieste concorrenti e 300 richieste al minuto. Le chiavi di prova permettono 2 e 60. Oltre quei limiti ottieni HTTP 429. Il codice errore rate_limited significa troppe richieste al minuto, e concurrency significa troppe contemporaneamente. In caso di sovraccarico temporaneo l'API restituisce anche 429 con un'intestazione Retry-After: 5.

Il client Python OpenAI riprova alcuni errori da solo, ma un wrapper esplicito mantiene il comportamento ovvio:

Copyimport time
from openai import RateLimitError

def ask(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited after retries")

Ogni risposta porta X-Request-Id, X-Balance-USD e intestazioni di rate-limit, che puoi loggare. Includi l'ID della richiesta se contatti il supporto. Le richieste fallite o rifiutate non vengono addebitate, quindi riprovare non costa extra.

Pianifica anche i limiti di dimensione. La finestra di contesto è di 100.000 token, prompt più completamento, e il corpo della richiesta massimo è di 8 MB. Le cronologie di chat lunghe dovrebbero essere tagliate o riassunte prima che raggiungano quei numeri.

Quando la chiamata non funziona

La maggior parte dei problemi alla prima esecuzione deriva da una manciata di errori. Controlla questi in ordine prima di sospettare qualsiasi altra cosa.

• Base URL senza il percorso della versione. Il valore deve terminare con /v1. Il client aggiunge /chat/completions ad esso, quindi una mancanza di /v1 invia la richiesta alla rotta sbagliata.
• Chiave errata o mancante. La chiave va nell'intestazione Authorization: Bearer, che il client costruisce da api_key. Se la variabile d'ambiente è vuota, il client solleva un errore all'avvio o invia una chiave vuota. Stampa bool(os.environ.get("API_KEY")) per verificare.
• Un nome del modello di un altro servizio. L'unico ID del modello qui è uncensored. Nomi come quelli in altri tutorial non corrisponderanno.
• Nessun saldo. Guarda l'intestazione X-Balance-USD. Una prova che ha superato i 7 giorni, o un saldo esaurito, richiede una ricarica a partire da $20.
• Vecchio pacchetto. Se un esempio usa OpenAI( e Python dice che non può importare quel nome, hai il pacchetto pre-1.0. Esegui pip install --upgrade openai.

Per vedere la risposta grezza incluse le intestazioni, usa il wrapper raw-response del client:

Copyraw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=5,
)
print(raw.headers.get("x-request-id"), raw.headers.get("x-balance-usd"))
completion = raw.parse()
print(completion.choices[0].message.content)

Questo stampa l'ID della richiesta e il tuo saldo rimanente accanto alla risposta, che è un rapido controllo di salute che puoi eseguire da un cron job o da uno script di avvio.

Utilizzo con altri strumenti

Poiché l'endpoint segue il formato OpenAI, altre librerie Python possono usarlo con le stesse due impostazioni. I framework che accettano una base URL OpenAI personalizzata hanno bisogno solo di base_url e api_key. Per Node, il pacchetto ufficiale openai accetta gli stessi campi:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.getaiapikey.com/v1",
  apiKey: process.env.API_KEY,
});

const r = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Say hello in five words." }],
});
console.log(r.choices[0].message.content);

Questo è un servizio solo testo: nessuna generazione di immagini o audio, nessun embedding e nessun fine-tuning. Se il tuo progetto ha bisogno di quelli, abbina questa API con un altro strumento per quella parte. Il modello è un modello a pesi aperti gestito da un provider indipendente e ottimizzato per rispondere senza rifiuti di contenuti per l'uso adulto legale. I contenuti sessuali che coinvolgono minorenni non sono mai permessi.

Altre guide

• Chiave API LLM gratuita: cosa copre il credito di prova
• Chiave API LLM per un Bot Discord: Guida alla configurazione
• Checklist API IA