Szczegółowy przewodnik po parametrach API dużych modeli: od pól żądania do pól odpowiedzi

Jak wygląda żądanie

Adres endpointu to POST https://api.apidamoxing.com/v1/chat/completions, nagłówek autoryzacji to Authorization: Bearer <key>, ciało żądania to JSON kompatybilny z OpenAI. Zobacz pełne żądanie z popularnymi polami:

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

Zwróć uwagę, że model musi mieć wartość uncensored, ponieważ dostępny jest tylko jeden model. Możesz to sprawdzić przez GET /v1/models. Poniżej wyjaśnienie pól.

Po przeczytaniu zauważysz trzy kategorie: „co powiedzieć” (messages, tools), „jak powiedzieć” (temperature, top_p) oraz „ile i kiedy przestać” (max_tokens, stop, stream). Zrozumienie kategorii pomoże Ci zgadnąć przeznaczenie nowych pól.

messages: „Księga” tej rozmowy

messages to tablica, gdzie każdy element ma role i content. Wyobraź sobie, że to dziennik protokołów z spotkań, gdzie model czyta wszystko od początku i pisze kolejną stronę. Nie pamięta tego, co czytał wcześniej, więc w rozmowie wieloetapowej musisz sam podać pełną historię.

Popularny trik: aby wymusić ton, dodaj do historii wiadomość assistant. Pamiętaj, że suma tokenów w prompt i output nie może przekroczyć 100,000 tokenów — im dłuższa historia, tym więcej miejsca zajmuje.

Przykład: system mówi „odpowiadaj tylko na pytania o zamówienia, max trzy zdania”. Pytanie 1: czas dostawy. Pytanie 2: „a zwroty?”. W messages muszą być: system, user 1, assistant 1, user 2. Bez tego model nie zrozumie, na co odnosi się „a zwroty”.

Parametry próbkowania: regulacja „zakresu kreatywności”

Model przypisuje prawdopodobieństwa do wszystkich możliwych tokenów, a następnie losuje. Poniższe parametry to pokrętła regulujące te reguły:

Oba parametry kontrolują „stopień losowości”, ale z różnych perspektyw. Jednoczesna zmiana obu utrudnia ocenę, który z nich wpłynął na wynik, dlatego zalecamy modyfikację tylko jednego parametru na raz. Pola standardowego próbkowania są przekazywane bez zmian; interfejs nie modyfikuje ich samodzielnie.

Dla jasności: załóżmy, że najbardziej prawdopodobne trzy kolejne tokeny mają prawdopodobieństwo 60%, 30% i 10%. Obniżenie temperature sprawia, że token z 60% staje się wyraźnie dominujący, a wynik bardziej przypomina stały wybór pierwszego kandydata; podwyższenie temperature zbliża prawdopodobieństwa wszystkich trzech, zwiększając szansę wylosowania rzadkich tokenów. Przy top_p = 0,9 pozostawiane są tylko dwa pierwsze tokeny (o łącznym prawdopodobieństwie 90%), trzeci jest odrzucany. Powyższe liczby ilustrują zasadę działania i nie odzwierciedlają rzeczywistego prawdopodobieństwa.

Kontrola długości i warunków zakończenia: max_tokens, stop, stream

max_tokens to jak wielkość talerza: jeśli jest za mały, danie zostaje niedokończone, a finish_reason to length. stop to umowny sygnał, po którym model przestaje. stream nie zmienia treści, tylko sposób dostarczania: zamiast podawać wszystko naraz, podaje porcje, co przyspiesza wrażenie odpowiedzi.

Praktyczne zastosowanie stop: jeśli poprosisz model o generowanie w formacie „Pytanie: … Odpowiedź: …###”, ustawienie ### jako wartości stop spowoduje automatyczne zakończenie generowania po napotkaniu separatora. Oszczędza to tokeny i zapobiega zbędnym dodatkowym wywódcom. Pamiętaj, że przy trafieniu stop finish_reason również przyjmuje wartość stop; jeśli musisz rozróżnić te przypadki, sprawdź treść odpowiedzi samodzielnie.

tools i tool_choice: pozwól modelowi „zadzwonić” do Ciebie

Model nie ma bezpośredniego dostępu do danych w czasie rzeczywistym. W podejściu function calling najpierw informujesz model o dostępnych funkcjach. Gdy uzna, że jest to potrzebne, zamiast odpowiadać bezpośrednio, zwraca informację „wywołaj funkcję X z parametrami Y”. Twój program wykonuje funkcję, zwraca wynik, a model na tej podstawie formułuje ostateczną odpowiedź. Format jest zgodny z 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)

Proces składa się z dwóch rund: w pierwszej otrzymujesz tool_calls, a w drugiej dołączasz wynik z role: tool i wysyłasz kolejne zapytanie. Im bardziej szczegółowy opis (description), tym lepiej model wie, kiedy wywołać funkcję. Parametry są przekazywane jako ciąg JSON – koniecznie użyj json.loads do parsowania i walidacji, nie ufasz im bez sprawdzenia.

Pola odpowiedzi: zrozumienie „paragonu” z zapytania

Pomyślna odpowiedź ma zazwyczaj następującą strukturę, z stałymi polami:

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

W kodzie najpierw sprawdź finish_reason: jeśli to length, poinformuj użytkownika o ucięciu treści lub kontynuuj automatycznie; jeśli to tool_calls, przejdź do gałęzi wykonania funkcji. Szczegółowe metody rozliczenia znajdziesz w artykule Tokeny i rozliczenia.

Najczęstsze błędy przy konfiguracji parametrów

• Traktowanie max_tokens jako „górnej granicy wejścia”. max_tokens ogranicza tylko wyjście; wejście kontrolujesz samodzielnie.
• Myślenie, że model pamięta poprzednie zapytanie. Każde zapytanie jest niezależne – historię musisz przekazać samodzielnie.
• Ustawienie temperature na 0 nie gwarantuje identycznych wyników. Wyniki będą bardziej stabilne, ale nie należy zakładać zgodności znak po znaku.
• Bezpośrednie odczytywanie choices[0].message w trybie strumieniowym. W blokach strumieniowych pola to delta – musisz połączyć je samodzielnie.
• Pominięcie dodania wiadomości assistant z tool_calls po wywołaniu funkcji, co powoduje błąd w drugiej rundzie.

Znaczenie kodów błędów i strategię ponawiania zapytań znajdziesz w Dokumentacji. Aby zobaczyć kompletny przykład łączący te parametry, odwołaj się do artykułu Budowanie chatbota.