Uitleg API-parameters voor LLM's: van request-velden tot response-velden

Hoe ziet een request eruit

Endpoint: POST https://api.apidamoxing.com/v1/chat/completions. Autorisatie: Authorization: Bearer <key>. Body is JSON, compatibel met OpenAI chat-completions. Zie het volledige voorbeeld:

复制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": ["###"]
  }'

Vul bij model alleen uncensored in, want er is maar één model. Controleer met GET /v1/models. We leggen de velden nu uit.

De parameters vallen in drie groepen: 'wat' (messages, tools), 'hoe' (temperature, top_p) en 'hoeveel/wanneer' (max_tokens, stop, stream). Herken de groep om de functie te raden.

messages: het 'notitieboekje' van het gesprek

messages is een array met role en content. Het model leest alles opnieuw en schrijft de volgende pagina. Het onthoudt niets; jij moet de geschiedenis volledig meesturen.

Een veelgebruikte truc: wil je dat het model in een bepaalde toon verder schrijft, voeg dan zelf een assistant-bericht toe aan de geschiedenis. Onthoud dat de prompt en de uitvoer samen niet meer dan 100,000 tokens mogen beslaan; hoe langer de geschiedenis, hoe meer ruimte dit in beslag neemt.

Een concreet voorbeeld. Je bouwt een customer support-assistent met de system-prompt 'Beantwoord alleen vragen over bestellingen, maximaal drie zinnen'. De gebruiker vraagt in de eerste ronde naar de levertijd en in de tweede ronde 'en wat als ik het wil retourneren?'. De tweede request moet messages bevatten: system, de user-message van ronde 1, de assistant-response van het model uit ronde 1, en de user-message van ronde 2. Ontbreekt er één, dan weet het model niet waar 'dat' naar verwijst.

Samplingparameters: de "ruimte" aanpassen

Wanneer het model een token genereert, kent het eerst kansen toe aan alle kandidaten en trekt het vervolgens een keuze. De volgende twee parameters zijn de knoppen om de trekregels aan te passen:

Beide bepalen 'hoe willekeurig', maar vanuit een ander perspectief. Als je ze tegelijk aanpast, is het moeilijk te zien welk effect van welke parameter komt. Pas daarom bij voorkeur maar één aan. Deze standaard velden voor sampling worden doorgegeven zoals ze zijn; de API herschrijft ze niet.

Nog een concreet voorbeeld: stel dat de drie meest waarschijnlijke volgende woorden van het model kansen van 60%, 30% en 10% hebben. Een lagere temperature maakt het woord met 60% kans nog dominanter, waardoor de output lijkt alsof er altijd voor het eerste woord wordt gekozen. Een hogere temperature maakt de kansen dichter bij elkaar, waardoor minder waarschijnlijke woorden vaker getrokken worden. Bij top_p van 0,9 worden alleen de eerste twee woorden behouden die samen 90% van de kans dekken; het derde woord valt af. Deze cijfers zijn alleen bedoeld om het principe uit te leggen en geen echte kansen.

Lengte en stopregels beheren: max_tokens, stop, stream

max_tokens is als de grootte van een bord: als het bord te klein is, wordt het weggehaald voordat het eten op is, en dan is finish_reason 'length'. stop is als een afgesproken signaal: de kok stopt zodra hij het signaal hoort. stream verandert niet de inhoud, alleen de manier van leveren: van 'alles klaar serveren' naar 'een hap tegelijk serveren', waardoor de gebruiker het gevoel heeft dat de respons sneller is.

Een handige toepassing van stop: laat het model een vast format volgen zoals 'Vraag: ... Antwoord: ...###'. Stel ### in als stop-teken, dan stopt de generatie automatisch bij het scheidingsteken. Dit bespaart tokens en voorkomt dat het model er achter nog onnodige tekst bij verzint. Let op: als stop geraakt wordt, is finish_reason ook 'stop'. Als je dit wilt onderscheiden van een normale stop, moet je zelf de inhoud controleren.

tools en tool_choice: het model 'laten bellen'

Het model heeft geen toegang tot realtime data. Bij function calling geef je eerst aan welke functies beschikbaar zijn. Als het model een functie nodig heeft, antwoordt het niet direct, maar vraagt het om een functie aan te roepen met bepaalde parameters. Jouw programma voert de functie uit en geeft het resultaat terug, waarna het model het antwoord formuleert. De indeling is compatibel met 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)

Het proces verloopt in twee ronden: in de eerste ronde haal je tool_calls op, in de tweede ronde voeg je de resultaten met role 'tool' toe en vraag je opnieuw op. Hoe specifieker de description, hoe beter het model weet wanneer het moet aanroepen. De parameters zijn een JSON-string; parseer en valideer ze altijd met json.loads, vertrouw ze niet zomaar.

Responsvelden: de 'bon' begrijpen

Een succesvolle respons ziet er ongeveer zo uit, met vaste velden:

复制{
  "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}
}

Kijk in de code eerst naar finish_reason: als het 'length' is, geef dan een melding dat de inhoud is afgekapt of voer automatisch een vervolg uit; als het 'tool_calls' is, ga dan naar de tak voor functieverwerking. De rol van usage wordt in token en facturatie gedetailleerder uitgelegd.

Veelgemaakte fouten met parameters

• max_tokens verwarren met 'inputlimiet'. Het regelt alleen de output; de input bepaal jij.
• Gelooven dat het model zich vorige verzoeken herinnert. Elk verzoek is onafhankelijk; de historie voer je zelf mee.
• Een temperature van 0 betekent dat het resultaat elke keer exact hetzelfde is. Dit is stabieler, maar je mag niet aannemen dat het letterlijk per token identiek is.
• Lees in stream-modus direct choices[0].message. In de blokken van de stream is het veld delta; je moet deze zelf aan elkaar plakken.
• Je vergeet de assistant-berichten met tool_calls toe te voegen na de tool-aanroep, wat leidt tot een fout in de tweede ronde.

De betekenis van foutcodes en herstelstrategieën vind je in documentatie. Voor een compleet voorbeeld waarin deze parameters aan elkaar worden geknoopt, zie Chatbot bouwen.