Penjelasan Parameter API Model Besar: Dari Field Permintaan ke Respons

Seperti Apa Tampilan Satu Permintaan

Alamat endpoint adalah POST https://api.apidamoxing.com/v1/chat/completions, header otentikasi adalah Authorization: Bearer <key>, dan body permintaan adalah JSON yang kompatibel dengan format chat completion OpenAI. Mari kita lihat contoh permintaan lengkap yang menggunakan field-field umum:

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

Perhatikan bahwa model di sini hanya boleh diisi dengan uncensored karena layanan hanya memiliki satu model tanpa opsi lain. Anda dapat memverifikasinya menggunakan GET /v1/models. Di bawah ini adalah penjelasan per field.

Setelah membaca artikel ini, Anda akan menyadari bahwa parameter-parameter ini dapat dikelompokkan menjadi tiga kategori: yang menentukan "apa yang diucapkan" (messages, tools), yang menentukan "bagaimana cara mengucapkannya" (temperature, top_p), dan yang menentukan "berapa banyak dan kapan berhenti" (max_tokens, stop, stream). Ingat pengelompokan ini; jika Anda menemui field asing di masa depan, tentukan dulu kategorinya, dan Anda akan bisa menebak fungsinya.

messages: Buku Catatan Percakapan Ini

messages adalah sebuah array, di mana setiap elemen memiliki role dan content. Bayangkan ini sebagai catatan rapat yang dicatat per halaman. Model akan membaca ulang dari awal setiap kali, lalu menulis halaman berikutnya. Model tidak mengingat apa yang telah dibacanya sebelumnya, sehingga dalam percakapan multi-gilir, riwayat harus Anda sertakan secara lengkap.

Trik umum: agar model melanjutkan penulisan dengan gaya tertentu, Anda bisa membuat pesan assistant dan memasukkannya ke riwayat. Ingat, jumlah token untuk prompt dan output gabungan tidak boleh melebihi 100,000 token; semakin panjang riwayat, semakin banyak ruang yang digunakan.

Contoh konkret. Anda membuat asisten layanan pelanggan, system menulis "Hanya jawab pertanyaan terkait pesanan, jawaban tidak lebih dari tiga kalimat". Pengguna bertanya tentang waktu pengiriman di putaran pertama, lalu bertanya "Bagaimana dengan pengembalian barang" di putaran kedua. Di permintaan putaran kedua, messages harus secara berurutan berisi: system, user putaran pertama, jawaban assistant model putaran pertama, user putaran kedua. Jika satu pun hilang, model tidak tahu apa yang dimaksud "pengembalian".

Parameter Sampling: Mengatur Ruang Kreasi

Saat menghasilkan setiap kata, model terlebih dahulu memberikan skor probabilitas kepada semua kata kandidat, lalu melakukan undian. Dua parameter di bawah ini adalah tombol untuk mengatur aturan undian tersebut:

Keduanya mengatur "seberapa acak", hanya dengan sudut pandang berbeda. Mengatur keduanya sekaligus sulit untuk menilai efek mana yang berasal dari mana, jadi disarankan mengubah hanya satu parameter sekaligus. Parameter sampling standar ini diteruskan apa adanya ke model, API tidak akan mengubahnya secara diam-diam.

Contoh angka lainnya: anggap model paling mungkin menghasilkan tiga token berikutnya dengan probabilitas 60%, 30%, 10%. Menurunkan temperature membuat yang 60% lebih unggul, output lebih mirip selalu memilih yang pertama; menaikkan temperature mendekatkan ketiganya, token jarang lebih mudah terpilih. Dengan top_p 0.9, hanya dua token pertama yang dipertahankan hingga mencapai 90%, yang ketiga langsung gugur. Angka ini hanya asumsi untuk menjelaskan prinsip, bukan probabilitas nyata.

Kontrol panjang dan penghentian: max_tokens, stop, streaming

max_tokens seperti ukuran piring saji. Jika piring kecil, makanan diambil sebelum habis, finish_reason akan menjadi length. stop seperti kode rahasia yang disepakati, chef berhenti saat mendengar kode tersebut. stream tidak mengubah konten, hanya cara penyampaian: dari "semua selesai baru disajikan" menjadi "selesai satu suap, sajikan satu suap", pengguna merasa respons lebih cepat.

stop memiliki kegunaan praktis: Anda meminta model output dengan format tetap “Pertanyaan: ……Jawaban:……###”, lalu menetapkan ### sebagai stop agar berhenti otomatis saat mencapai pemisah, sehingga menghemat token dan menghindari model berbicara berlebihan setelahnya. Perhatikan bahwa saat stop terpicu, finish_reason juga bernilai stop; jika Anda perlu membedakan, Anda harus memeriksa konten sendiri.

tools dan tool_choice: Memungkinkan model "menelepon" Anda

Model tidak dapat mengakses data secara real-time. Pendekatan function calling adalah: Anda memberi tahu model fungsi apa saja yang tersedia. Saat model merasa perlu, ia tidak langsung menjawab, tetapi mengembalikan "Silakan panggil fungsi tertentu dengan parameter...". Program Anda akan mengeksekusi fungsi tersebut dan mengembalikan hasilnya, lalu model akan menyusun jawaban berdasarkan hasil tersebut. Formatnya konsisten dengan 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)

Alurnya dua putaran: putaran pertama mendapatkan tool_calls, putaran kedua menambahkan hasil dengan role: tool lalu melakukan permintaan lagi. Semakin spesifik description, semakin jelas model kapan harus memanggil. Parameter adalah string JSON, wajib memparse-nya dengan json.loads dan lakukan validasi, jangan langsung percaya.

Field respons: Memahami "struk" yang dikembalikan

Respons sukses biasanya memiliki struktur berikut, dengan field yang tetap:

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

Di kode, periksa finish_reason terlebih dahulu: jika length, beri tahu pengguna bahwa konten terpotong atau lanjutkan secara otomatis; jika tool_calls, masuk ke cabang eksekusi fungsi. Penggunaan usage dijelaskan lebih rinci dalam metode anggaran di token dan penagihan.

Beberapa kesalahan parameter yang paling sering terjadi

• Menganggap max_tokens sebagai "batas input". Ini hanya mengatur output, input dikontrol oleh Anda.
• Mengira model mengingat permintaan sebelumnya. Setiap permintaan bersifat independen, riwayat dibawa sendiri.
• Mengatur temperature ke 0 membuat Anda mengira hasil akan selalu persis sama. Ini akan lebih stabil, tetapi Anda tidak boleh mengasumsikan konsistensi karakter per karakter.
• Dalam mode streaming, baca choices[0].message secara langsung. Bidang dalam blok streaming adalah delta, yang harus Anda gabungkan sendiri.
• Lupa menambahkan pesan assistant dengan tool_calls setelah panggilan tool, menyebabkan kesalahan pada putaran kedua.

Arti kode kesalahan dan strategi retry dapat dilihat di dokumentasi. Untuk melihat contoh lengkap yang menghubungkan parameter-parameter ini, lihat artikel membuat chatbot.