Guida AI parametri dell'API per LLM: dai campi di richiesta a quelli di risposta

Com'è fatta una richiesta

L'endpoint è POST https://api.apidamoxing.com/v1/chat/completions, l'header di autenticazione è Authorization: Bearer <key>, il corpo è JSON e il formato è compatibile con la chat completion di OpenAI. Ecco una richiesta completa con i campi comuni:

复制curl https://api.apidamoxing.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "你是一位耐心的天文科普作者。"},
      {"role": "user", "content": "为什么月亮总是同一面朝向地球？"}
    ],
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 400,
    "stop": ["###"]
  }'

Nota che model deve essere solo uncensored, poiché il servizio offre un solo modello senza alternative. Verifica con GET /v1/models. Di seguito spieghiamo i campi uno per uno.

Leggendo tutto, vedrai che i parametri rientrano in tre categorie: cosa dire (messages, tools), come dirlo (temperature, top_p), quanto dire e quando fermarsi (max_tokens, stop, stream). Questa classificazione ti aiuta a intuire lo scopo di nuovi campi.

messages: il "registro" della conversazione

messages è un array di oggetti con role e content. Immagina un verbale di riunione: il modello legge tutto da capo e scrive la pagina successiva. Non ricorda cosa ha letto prima, quindi devi includere tu la cronologia.

Trucco: inserisci una messaggio assistant finto per impostare il tono. Attenzione: prompt + output non superino 100.000 token.

Esempio: assistant che risponde solo di ordini. Per la seconda domanda, messages deve includere system, user1, assistant1, user2. Senza tutto, il modello non capisce.

Parametri di campionamento: regola lo "spazio di manovra"

Il modello assegna probabilità a ogni candidato. Questi due parametri regolano la selezione:

Entrambi controllano la casualità. Modificarli insieme confonde i risultati: agisci su uno alla volta. I parametri standard vengono passati così come sono.

Esempio: probabilità 60%, 30%, 10%. temperature basso favorisce il primo; alto equalizza. top_p 0.9 mantiene solo i primi due (90%). Numeri ipotetici.

Controllo della lunghezza e interruzione: max_tokens, stop, stream

max_tokens è come la dimensione del piatto: se il piatto è piccolo, il cibo viene ritirato prima di essere servito del tutto e finish_reason sarà length. stop funziona come un segnale convenzionale: lo chef smette quando lo riceve. stream non cambia il contenuto, solo il modo di consegna: invece di "servire tutto insieme", si serve "un boccone alla volta", dando all'utente la sensazione di una risposta più rapida.

Un uso molto pratico di stop: chiedi al modello di seguire un formato fisso come "Domanda: ... Risposta: ...###" e imposta ### come stop. La generazione si interromperà automaticamente al separatore, risparmiando token ed evitando che il modello aggiunga discorsi superflui. Nota: quando stop viene attivato, anche finish_reason sarà stop; se devi distinguere i casi, devi verificare il contenuto tu stesso.

tools e tool_choice: far "chiamare" il modello a te

Il modello non può recuperare dati in tempo reale. Con function calling, tu fornisci al modello la descrizione delle funzioni disponibili; quando lo ritiene necessario, il modello non risponde direttamente, ma restituisce "chiama la funzione X con i parametri Y". Il tuo programma esegue la funzione e restituisce il risultato al modello, che a sua volta organizza la risposta finale. Il formato è compatibile con OpenAI.

复制import json
import os
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "get_tide_time",
        "description": "查询某港口今天的高潮时刻",
        "parameters": {
            "type": "object",
            "properties": {"port": {"type": "string", "description": "港口名称"}},
            "required": ["port"],
        },
    },
}]

messages = [{"role": "user", "content": "青岛今天几点涨潮？"}]
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]
    args = json.loads(call.function.arguments)
    result = {"port": args["port"], "high_tide": "14:20"}   # 这里换成你自己的查询
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)
else:
    print(msg.content)

Fase 1: ottieni tool_calls. Fase 2: aggiungi il risultato con role tool e ripeti. Una description dettagliata aiuta. Il parametro è una stringa JSON: usa json.loads per validare.

Campi di risposta: leggere la "ricevuta"

Una risposta corretta ha approssimativamente questa struttura, con campi fissi:

复制{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "因为潮汐锁定……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 38, "completion_tokens": 212, "total_tokens": 250}
}

Nel codice, controlla prima finish_reason: se è length, avvisa l'utente che il contenuto è stato troncato o prosegui automaticamente; se è tool_calls, passa al ramo di esecuzione delle funzioni. L'utilizzo di usage è spiegato nel dettaglio nella guida sui token e i costi.

I principali errori sui parametri

• Credere che max_tokens limiti l'input. Controlla solo l'output; l'input lo gestisci tu.
• Pensare che il modello ricordi la richiesta precedente. Ogni richiesta è indipendente: porta tu la cronologia.
• Impostare temperature a 0 e aspettarsi risultati identici. Aumenta la stabilità, ma non garantire la corrispondenza carattere per carattere.
• Leggere choices[0].message nello streaming. I blocchi contengono delta: devi assemblarli tu.
• Dopo la chiamata allo strumento, hai dimenticato di aggiungere il messaggio dell'assistant con tool_calls, causando un errore nel secondo turno.

Significato errori e retry indocumentazione. Esempio completo inChatbot.