Büyük model API uç noktası parametreleri detaylı açıklama: İstek alanlarından yanıt alanlarına

Bir istek nasıl görünür

Uç nokta adresi POST https://api.apidamoxing.com/v1/chat/completions şeklindedir. Yetkilendirme başlığı Authorization: Bearer <key>'dir. İstek gövdesi JSON formatındadır ve OpenAI sohbet tamamlama ile uyumludur. Yaygın alanları içeren tam bir istek örneğine bakalım:

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

Dikkat: model alanına yalnızca uncensored yazılabilir çünkü hizmetin tek bir modeli vardır, başka seçenek yoktur. GET /v1/models ile bunu doğrulayabilirsiniz. Aşağıda alanları tek tek açıklayacağız.

Makaleyi okuduktan sonra, bu parametrelerin üç kategoriye ayrıldığını göreceksiniz: “ne söyleneceğini” belirleyenler (messages, tools), “nasıl söyleneceğini” belirleyenler (temperature, top_p) ve “ne kadar söyleneceği, ne zaman durulacağı” belirleyenler (max_tokens, stop, stream). Bu sınıflandırmayı aklınızda tutun; yabancı bir alanla karşılaştığınızda önce hangi kategoriye ait olduğunu belirleyin, işlevini büyük olasılıkla tahmin edebilirsiniz.

messages: Bu sohbetin “defteri”

messages bir dizidir; her öğe role ve content içerir. Bunu sayfa sayı tutulan bir toplantı tutanağı gibi düşünün. Model her seferinde baştan okur ve bir sonraki sayfayı yazar. Kendisi ne okuduğunu hatırlamaz, bu yüzden çoklu konuşmalarda geçmişi siz tam olarak sağlamalısınız.

Yaygın bir teknik: Modelin belirli bir üslupta devam etmesini istiyorsanız, kendi oluşturduğunuz bir assistant mesajını geçmişe ekleyebilirsiniz. İstem ve çıktının toplamının 100.000 token'ı geçmemesi gerektiğini unutmayın; geçmiş ne kadar uzunsa, o kadar fazla yer kaplar.

Somut bir örnek verelim. Bir müşteri hizmetleri asistanı yaptığınızı düşünün. system mesajı “Yalnızca siparişlerle ilgili soruları yanıtlayın, yanıt üç cümveyi geçmesin” şeklinde olsun. Kullanıcı ilk soruda kargo süresini sorar, ikinci soruda “Peki iade?” diye sorar. İkinci istekte messages sırasıyla şunları içermelidir: system, ilk sorunun user'ı, ilk yanıtın assistant'ı, ikinci sorunun user'ı. Eksik bir mesaj olursa model “o” kelimesinin neye atıfta bulunduğunu bilemez.

Örneklem parametreleri: “Yaratıcılık alanını” ayarla

Model her karakteri üretirken önce tüm aday karakterlere olasılık puanı verir, sonra rastgele seçim yapar. Aşağıdaki iki parametre bu seçim kurallarını ayarlayan düğmelerdir:

Her iki parametre de rastgelelik derecesini kontrol eder, ancak farklı açılardan. Hangi parametrenin etki ettiğini ayırt etmek zor olacağından, etkilerin aynı anda değerlendirilmesi zordur; bu nedenle bir seferde yalnızca birini değiştirmeniz önerilir. Bu standart örnek alanları olduğu gibi iletilir; API yanlılış bir şekilde değiştirmez.

Daha sezgisel bir sayısal örnekle açıklayalım: Modelin bir sonraki en olası üç kelimesinin olasılıklarının sırasıyla %60, %30 ve %10 olduğunu varsayalım. temperature değerini düşürmek, %60 olasılıklı kelimenin baskın hale gelmesini sağlar ve her seferinde en yüksek olasılıklı kelimenin seçilmesi gibi bir çıktı üretir. Değeri artırmak ise olasılıkları birbirine yaklaştırır ve daha düşük olasılıklı kelimelerin seçilme ihtimalini artırır. top_p değeri 0.9 olarak ayarlandığında, kümülatif olasılık %90'a ulaşan ilk iki kelime korunur ve üçüncü kelime elenir. Bu sayılar yalnızca prensibi açıklamak için varsayımsaldır ve gerçek olasılıkları yansıtmaz.

Uzunluk ve durdurma kontrolü: max_tokens, stop, stream

max_tokens, bir servis tabağı büyüklüğü gibidir. Tabağın küçük olması, yemek bitmeden servis edilmesine neden olur; bu durumda finish_reason 'length' olur. stop, bir anlaşma gibidir; şef bu sinyali aldığı anda durur. stream içeriği değiştirmez, sadece teslim biçimini değiştirir: "hepsini yapıp sunmak" yerine "yapılanı hazırladıkça sunmak" şeklinde olur; kullanıcı yanıtın daha hızlı olduğunu hisseder.

stop'un çok pratik bir kullanımı vardır: Modeli "Soru: ... Cevap: ... ###" gibi sabit bir formatta çıktı vermeye zorlayın ve ###'ı stop olarak ayarlayın. Model ayırıcıya geldiğinde otomatik olarak durur; bu, token tasarrufu sağlar ve modelin gereksiz sözler sarf etmesini önler. stop tetiklendiğinde finish_reason yine 'stop' olur; ayırt etmek isterseniz içeriği kendiniz kontrol etmeniz gerekir.

tools ve tool_choice: Modelin size "telefon etmesini" sağlamak

Model gerçek zamanlı verilere erişemez. function calling yaklaşımı şudur: Önce modele hangi fonksiyonların mevcut olduğunu belirtirsiniz. Model buna ihtiyaç duyduğunda doğrudan cevap vermek yerine, "Şu fonksiyonu şu parametrelerle çağır" şeklinde bir fonksiyon çağırma bilgisi döndürür. Programınız bu sonucu işler ve modeli besler; model de buna göre cevabı düzenler. Format OpenAI ile uyumludur.

复制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)

Süreç iki aşamalıdır: İlk aşamada tool_calls alınır, ikinci aşamada role değeri tool olan sonuç eklenerek istek tekrar gönderilir. description ne kadar detaylı yazılırsa model, ne zaman çağrı yapması gerektiğini o kadar iyi anlar. Parametreler JSON dizgesi olarak gönderilir; mutlaka json.loads ile ayrıştırılmalı ve doğrulama yapılmalıdır, doğrudan güvenilmemelidir.

Yanıt alanları: Dönen "faturayı" okumak

Başarılı bir yanıt kabaca aşağıdaki gibidir; alanlar sabittir:

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

Kodda önce finish_reason'a bakılmalı: length ise kullanıcıya içeriğin kesildiği belirtilmeli veya otomatik olarak devam ettirilmeli; tool_calls ise fonksiyon yürütme dalına geçilmeli. usage'nın işlevi, token ve faturalandırma başlıklı makalede daha detaylı bütçe yöntemleriyle açıklanmıştır.

En sık yapılan parametre hataları

• max_tokens'i "girdi üst limiti" olarak düşünmeyin. max_tokens sadece çıktıyı yönetir; girdi sizin kontrolünüz altındadır.
• Modelin bir önceki isteği hatırladığını sanmak. Her istek bağımsızdır; geçmiş kendiliğinden gelir.
• temperature değerini 0 olarak ayarlayınca her sonucun tamamen aynı olacağını sanmak. Daha stabil hale gelir, ancak kelime kelime aynı olacağı varsayılmamalıdır.
• Akış modunda doğrudan choices[0].message okumak. Akış modunda gelen parçalarda alan delta'dır; verileri kendiniz birleştirmeniz gerekir.
• tool çağrısından sonra role değeri assistant olan ve tool_calls içeren mesajı eklemeyi unutmak; bu durum ikinci aşamada hataya neden olur.

Hata kodlarının anlamları ve yeniden deneme stratejileri belge'de yer almaktadır. Bu parametreleri bir araya getiren tam bir örneği görmek için sohbet botu oluşturma makalesine bakın.