تفاصيل معاملات واجهة برمجة تطبيقات النماذج الكبيرة: من حقول الطلب إلى حقول الاستجابة

كيف يبدو الطلب

عنوان الواجهة هو POST https://api.apidamoxing.com/v1/chat/completions، و رأس المصادقة هو Authorization: Bearer <key>، وجسم الطلب بصيغة JSON ومتوافق مع واجهة chat completion الخاصة بـ OpenAI. دعنا نرى طلباً كاملاً يستخدم الحقول الشائعة:

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

ملاحظة: يجب أن يكون model هنا uncensored فقط، لأن الخدمة تحتوي على نموذج واحد فقط دون خيارات أخرى. يمكنك التحقق باستخدام GET /v1/models. سنشرح الحقول واحدة تلو الأخرى أدناه.

بعد قراءة المقال بالكامل، ستلاحظ أن هذه المعاملات تنقسم إلى ثلاث فئات: ما يحدد "ماذا نقول" (messages، tools)، وما يحدد "كيف نقول" (temperature، top_p)، وما يحدد "كم نقول ومتى نتوقف" (max_tokens، stop، stream). تذكر هذا التصنيف، وسيمكنك تخمين وظيفة أي حقل غريب بناءً على فئته.

messages: دفتر سجل هذه المحادثة

messages هي مصفوفة، يحتوي كل عنصر على role و content. تخيلها كدفتر اجتماعات يسجل الأحداث صفحة تلو الأخرى. يقرأ النموذج كل شيء من البداية ثم يكتب الصفحة التالية. لا يتذكر ما قرأه سابقاً، لذا يجب عليك توفير التاريخ كاملاً للمحادثات متعددة الأدوار.

حيلة شائعة: لجعل النموذج يكتب بأسلوب معين، يمكنك إنشاء رسالة assistant وإضافتها إلى التاريخ. تذكر أن مجموع prompt والمخرجات لا يجب أن يتجاوز 100,000 token، وكلما طالت السجلات زاد استهلاك المساحة.

مثال عملي. قمت ببناء مساعد خدمة عملاء، وحددت في system: "أجب فقط على الأسئلة المتعلقة بالطلبات، ولا تتجاوز ثلاث جمل". في الجولة الأولى، سأل المستخدم عن وقت الشحن، وفي الجولة الثانية سأل: "ماذا عن الإرجاع؟". يجب أن تحتوي رسالة الجولة الثانية على messages بالترتيب التالي: system، user من الجولة الأولى، رد assistant من النموذج في الجولة الأولى، وuser من الجولة الثانية. إذا غاب أي منها، لن يعرف النموذج ما يشير إليه "ذلك".

معاملات العينات: ضبط "مساحة الإبداع"

عند توليد كل حرف، يعطي النموذج درجات احتمالية لجميع الحروف المرشحة ثم يسحب قرعة. المعاملان أدناه هما مقبضان لتعديل قواعد السحب:

كلاهما يتحكمان في "مدى العشوائية"، لكن من زوايا مختلفة. من الصعب تحديد تأثير التعديل المتزامن، لذا يُنصح بتعديل واحد فقط في كل مرة. تُمرر حقول المعايرة القياسية كما هي دون تعديل من الواجهة.

مثال رقمي توضيحي: افترض أن الكلمات الثلاث الأكثر احتمالاً للنموذج هي 60% و30% و10%. خفض temperature يعزز الكلمة ذات الاحتمال الأعلى (60%)، مما يجعل المخرج يشبه اختيار الأول دائماً. رفعها يقارب الاحتمالات، مما يزيد فرصة اختيار الكلمات الأقل شيوعاً. مع top_p = 0.9، يتم الاحتفاظ بالكلمات التي تصل تراكمياً إلى 90% فقط (الكلمة الأولى والثانية)، بينما تُستبعد الثالثة. هذه الأرقام افتراضية للتوضيح وليست احتمالات حقيقية.

التحكم في الطول والتوقف: max_tokens، stop، stream

يشبه max_tokens حجم طبق التقديم. إذا كان الطبق صغيراً، تُرفع الأطباق قبل اكتمال الوجبة، ويكون finish_reason هو length. يعمل stop كإشارة سرية، حيث يتوقف الطاهي عند سماعها. لا يغير stream المحتوى، بل طريقة التسليم: من "تقديم الوجبة كاملة" إلى "تقديم لقمة تلو الأخرى"، مما يعطي المستخدم انطباعاً بسرعة الاستجابة.

استخدام عملي لـ stop: اطلب من النموذج اتباع التنسيق "سؤال: ... جواب: ...###"، ثم حدد ### كقيمة stop. سيتوقف النموذج تلقائياً عند الفاصل، مما يوفر tokens ويتجنب الكلام الزائد. لاحظ أن finish_reason يكون stop أيضاً عند التوقف، لذا إذا كنت تريد التمييز، يجب فحص المحتوى بنفسك.

tools و tool_choice: تمكين النموذج من "الاتصال" بك

النموذج لا يملك بيانات حية. يتم استدعاء الدوال (function calling) عبر تعريف الدوال المتاحة للنموذج. عند الحاجة، لا يجيب النموذج مباشرة، بل يعيد "استدعاء دالة معينة بالمعاملات..."، ثم ينفذ برنامجك النتيجة ويعيدها للنموذج ليجمع الإجابة. التنسيق متوافق مع 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)

العملية على مرحلتين: المرحلة الأولى تحصل على tool_calls، والمرحلة الثانية تضيف نتائج role: tool ثم تطلب مرة أخرى. كلما كان الوصف أكثر تحديداً، عرف النموذج متى يستدعي. المعامل سلسلة JSON، يجب تحليلها باستخدام json.loads والتحقق منها، ولا تثق بها مباشرة.

حقول الاستجابة: قراءة "الفاتورة"

الاستجابة الناجحة تتكون عادةً من الحقول الثابتة التالية:

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

تحقق من finish_reason: إذا كان length، أبلغ المستخدم أو تابع الكتابة؛ وإذا كان tool_calls، نفذ دالة. تفاصيل ميزانية الرموزtoken والنفقات موضحة في المقال.

أخطاء شائعة في المعاملات

• اعتبار max_tokens "حد الإدخال". هو يحدد الإخراج فقط، والإدخال يتحكم به المستخدم.
• اعتقاد أن النموذج يتذكر الطلب السابق. كل طلب مستقل، والتاريخ يُمرر يدوياً.
• ضبط temperature على 0 يعني أن كل نتيجة ستكون متطابقة حرفياً في كل مرة. سيكون الأمر أكثر استقراراً، لكن لا ينبغي افتراض التطابق الحرفي لكل نتيجة.
• قراءة choices[0].message مباشرة في الوضع التدفقي. حقول الكتلة في الوضع التدفقي هي delta، ويجب تجميعها.
• نسيان إضافة رسالة assistant التي تحتوي على tool_calls بعد استدعاء الأداة، مما يسبب خطأ في المرحلة الثانية.

راجعالمستند لمعاني أخطاء الاستراتيجيات. لمثال كامل يربط المعلمات، راجع مقالبناء روبوت الدردشة.