دليل البدء السريع لواجهة Hy3 API لسير العمل الوكيل وطويل السياق

نموذج Hy3 من Tencent متاح على Novita AI بمعرف النموذج tencent/hy3، ونقطة نهاية chat/completions متوافقة مع OpenAI، ونافذة سياق بحجم 256 ألف رمز، ودعم لاستدعاء الدوال والمخرجات المنظمة وثلاثة أوضاع للتفكير. يغطي هذا الدليل السريع الإعداد للمطور: تكوين العميل، إرسال أول طلب، استخدام استدعاء الدوال، تفعيل التفكير، وفهم حدود المعدل قبل البدء في البناء.

متى تستخدم دليل البدء السريع هذا

استخدم هذا الدليل عندما تحتاج إلى طلب عمل لـ Hy3 قبل كتابة أي كود إضافي. يغطي مسارًا عمليًا: اختر معرف النموذج، تحقق من الهوية، أرسل طلب اختبار واحد، ثم قم بالتوسع إلى استدعاء الدوال أو التفكير حسب احتياجات عبء العمل الخاص بك.

هندسة Hy3 — إجمالي 295 مليار معامل، 21 مليار معامل نشط في بنية MoE — مصممة لتحقيق توازن بين الجودة والكفاءة على نطاق واسع. يجدر النظر فيها عندما تحتاج إلى:

• معالجة مستندات طويلة السياق (نافذة 256 ألف رمز تناسب حوالي 200 ألف كلمة في استدعاء واحد).
• حوار متعدد الأدوار يستفيد من ميزانية المعاملات النشطة الكبيرة.
• مهام وكيلية تتطلب استدعاء أدوات وتنسيق وسيطات موثوق.
• مساعدة في البرمجة تمتد عبر قواعد أكواد كبيرة دون تجزئة.

يغطي هذا الدليل فقط مسار تكامل API عبر Novita AI. لا يغطي الاستضافة الذاتية، الضبط الدقيق، أو النقل إلى خلفيات استدلال أخرى.

الخطوة 1: الحصول على مفتاح API من Novita

أنشئ حسابًا على Novita AI وانتقل إلى قسم مفاتيح API في لوحة التحكم. قم بإنشاء مفتاح واحفظه في متغير بيئة. احتفظ به خارج كود العميل، حزم الواجهة الأمامية، والمستودعات العامة.

export NOVITA_API_KEY="your_api_key"

إذا كنت تستخدم بالفعل OpenAI Python SDK أو عملاء متوافقين مع OpenAI في مشاريع أخرى، فإن الإعداد هنا هو نفسه — قم بتغيير عنوان URL الأساسي واسم النموذج فقط، ولا شيء آخر.

الخطوة 2: تأكيد معرف النموذج ونقطة النهاية

هذه القيم الثلاث هي كل ما تحتاجه للتكوين:

العنصر	القيمة
مفتاح API	مفتاح API الخاص بك من Novita AI، مخزن كمتغير بيئة
عنوان URL الأساسي المتوافق مع OpenAI	https://api.novita.ai/openai
نقطة نهاية إكمال المحادثة	POST https://api.novita.ai/openai/v1/chat/completions
معرف النموذج	tencent/hy3

استخدم tencent/hy3 في جميع استدعاءات API. في واجهة المستخدم أو الوثائق الموجهة للمستخدم، استخدم اسم العرض “Hy3”.

فهرس وثائق Novita AI يسرد عنوان URL الأساسي المتوافق مع OpenAI، و مرجع API لإكمال المحادثة يوثق شكل الطلب والاستجابة بالكامل.

الخطوة 3: التحقق من الأسعار والحدود وتفاصيل النموذج

القيم الحالية من صفحة نموذج Hy3 على Novita AI:

الحقل	القيمة
اسم العرض	Hy3
معرف نموذج API	tencent/hy3
سلسلة النماذج	Hunyuan
البنية	MoE، 295B إجمالي / 21B نشط
نقطة النهاية	chat/completions
وسائط الإدخال	نص
وسائط الإخراج	نص
نافذة السياق	262,144 رمز
الحد الأقصى لرموز الإخراج	262,144 رمز
الميزات	بدون خادم، استدعاء دوال، مخرجات منظمة، تفكير
سعر الإدخال	مدرج بسعر $0 / مليون رمز (تحقق من السعر الحالي على صفحة النموذج)
سعر الإخراج	مدرج بسعر $0 / مليون رمز (تحقق من السعر الحالي على صفحة النموذج)

حدود المعدل تختلف حسب مستوى الحساب (T1–T5) وتقاس بعدد الطلبات في الدقيقة (RPM) والرموز في الدقيقة (TPM). يتم سرد مستويات وعتبات الحدود الحالية في وثائق حدود معدل Novita AI.

قد تتغير الأسعار وحدود المعدل. تحقق من صفحة نموذج Hy3 و صفحة تسعير Novita AI قبل الالتزام بأي تقدير للتكلفة.

الخطوة 4: إرسال أول طلب لك

ابدأ بطلب نصي بسيط لتأكيد المصادقة، توجيه النموذج، وتحليل الاستجابة. اجعل المطالبة قصيرة حتى تختبر الاتصال، وليس جودة المخرجات.

مثال باستخدام cURL

curl "https://api.novita.ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${NOVITA_API_KEY}" \
  -d '{
    "model": "tencent/hy3",
    "messages": [
      {
        "role": "system",
        "content": "You are a concise technical assistant."
      },
      {
        "role": "user",
        "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

الاستجابة الناجحة تعيد الشكل القياسي لإكمال المحادثة: مصفوفة choices، رسالة تحتوي على content، بيانات وصفية للنموذج والتاريخ، وكائن usage يحتوي على عدد رموز المطالبة والإكمال والإجمالي.

استخدم هذا الاختبار للتحقق من:

• مفتاح API صالح ورأس الترخيص منسق بشكل صحيح.
• قبول معرف النموذج tencent/hy3 دون خطأ 404 أو عدم العثور على النموذج.
• قدرة عميلك على تحليل choices[0].message.content.
• تسجيل استخدام الرموز لمراقبة التكاليف من الطلب الأول.

مثال باستخدام Python

يعمل OpenAI Python SDK مع Novita AI عند تعيين عنوان URL الأساسي:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {
            "role": "user",
            "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

print(response.choices[0].message.content)
print("Tokens used:", response.usage.total_tokens)

الخطوة 5: قراءة الرد

يتبع الرد تنسيق إكمال المحادثة القياسي من OpenAI:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "MoE models activate only a fraction of their total parameters..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

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

المعاملات الرئيسية

المعامل	النوع	التأثير
model	نص	يجب أن يكون tencent/hy3
messages	مصفوفة	تاريخ المحادثة. الأدوار المدعومة: system, user, assistant.
max_tokens	عدد صحيح	الحد الأقصى لرموز الإخراج. قم بتعيينه صراحة؛ القيمة الافتراضية قد تختلف حسب العميل.
temperature	عائم (0–2)	القيم المنخفضة تنتج مخرجات أكثر حتمية. استخدم 0.1–0.3 للكود والمهام الواقعية؛ 0.7–1.0 للمخرجات الإبداعية أو المتنوعة.
top_p	عائم (0–1)	بديل عن temperature لأخذ العينات. تجنب تعيين كليهما معًا.
stream	منطقي	اضبط true لاستقبال الرموز كتدفق. يتطلب معالجة أحداث مرسلة من الخادم على عميلك.
tools	مصفوفة	تعريفات الأدوات لاستدعاء الدوال. راجع قسم استدعاء الدوال أدناه.
tool_choice	نص أو كائن	يتحكم في الأداة التي سيستدعيها النموذج. "auto" يسمح للنموذج بتحديد.

لأعباء العمل طويلة السياق، يدعم Hy3 ما يصل إلى 262,144 رمز إدخال. قم بإدارة استخدام الرموز لكل استدعاء وراقب التكلفة التراكمية إذا كنت تعالج مستندات كبيرة أو تواريخ محادثة طويلة.

استدعاء الدوال

يدعم Hy3 استدعاء الدوال من خلال معامل tools. استخدمه عندما تريد أن يعيد النموذج وسيطات منظمة بدلاً من النثر — توجيه طلب إلى إجراء معين، تحليل إدخال المستخدم إلى حقول محددة النوع، أو تشغيل سير عمل متعدد الخطوات.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_knowledge_base",
            "description": "Search a product knowledge base for answers to customer queries.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The customer's question or topic to search for.",
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Maximum number of results to return. Default is 5.",
                    },
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant. Use the search tool to find relevant answers."},
        {
            "role": "user",
            "content": "What is your return policy for electronics purchased in the last 30 days?",
        },
    ],
    tools=tools,
    tool_choice="auto",
    temperature=0.1,
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(f"Tool: {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Arguments: {args}")
else:
    print(message.content)

عندما يعيد النموذج استدعاء أداة، يقوم تطبيقك بتنفيذ الدالة، ثم يرسل النتيجة مرة أخرى في المحادثة:

# After executing your search function, send the result back
tool_result = "Returns accepted within 30 days with original receipt. Electronics must be unopened."

follow_up = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant."},
        {"role": "user", "content": "What is your return policy for electronics purchased in the last 30 days?"},
        message,  # the assistant's tool call message
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": tool_result,
        },
    ],
    temperature=0.1,
)

print(follow_up.choices[0].message.content)

اختبر مخططات أدواتك على استفسارات تمثيلية قبل توجيه حركة الإنتاج. جودة استخراج وسيطات الدالة تعتمد على مدى وضوح وصف كل معامل وقيمه المتوقعة.

وضع التفكير

يسرد Hy3 التفكير كميزة مدعومة على صفحة نموذج Novita AI. النماذج القادرة على التفكير تفكر في المشكلة قبل إنتاج إجابة نهائية، مما يمكن أن يحسن جودة المخرجات في المشكلات المعقدة متعددة الخطوات — تصحيح الأخطاء البرمجية، الرياضيات متعددة الخطوات، تحليل المستندات الطويلة، ومهام التخطيط.

تدعم واجهة برمجة تطبيقات إكمال المحادثة من Novita AI معاملات ذات صلة بالتفكير (separate_reasoning, enable_thinking) لنماذج محددة. ما إذا كانت هذه المعاملات مقبولة من قبل tencent/hy3 وشكل الطلب الدقيق غير مؤكد في وثائق Novita الحالية. قبل بناء سلوك التفكير في سير عمل إنتاجي مع Hy3، قم بإجراء استدعاء اختباري وتحقق مما إذا كان الرد يتضمن حقل reasoning_content في choices[0].message.

للحصول على أسماء المعاملات المؤكدة ومعرفات النماذج المدعومة، راجع مرجع API لإكمال المحادثة من Novita AI و دليل نماذج التفكير.

استخدام السياق الطويل

نافذة السياق 256 ألف رمز في Hy3 هي ميزة عملية للمهام التي تتطلب الاحتفاظ بكمية كبيرة من النص في استدعاء واحد. حالات الاستخدام حيث يكون هذا مهمًا:

• تحليل المستندات: أرسل عقدًا كاملاً، ورقة بحثية، أو مواصفات كسياق واطرح أسئلة مستهدفة دون تجزئة.
• مراجعة قاعدة الأكواد: مرر ملفًا كبيرًا أو عدة ملفات ذات صلة واطلب ملاحظات حول البنية، أنماط الأخطاء، أو اقتراحات إعادة الهيكلة.
• تاريخ محادثة طويل: يمكن لسير العمل الوكيلية التي تتراكم العديد من الجولات البقاء في السياق لفترة أطول قبل الحاجة إلى التلخيص أو الاقتطاع.

للاستدعاءات طويلة السياق، قم بتعيين max_tokens بشكل صريح بناءً على طول الإخراج المتوقع. إرسال 200 ألف رمز من الإدخال وترك ميزانية رمز الإخراج على القيمة الافتراضية يهدر ميزانية السياق وقد ينتج ردودًا مبتورة.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

with open("large_document.txt") as f:
    document_text = f.read()

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {
            "role": "system",
            "content": "You are a document analysis assistant. Provide specific, referenced answers.",
        },
        {
            "role": "user",
            "content": f"Here is the document:\n\n{document_text}\n\nSummarize the key obligations and deadlines in this document.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

print(response.choices[0].message.content)

راقب usage.prompt_tokens في الرد لتتبع عدد الرموز التي تستهلكها مدخلاتك. لأعباء العمل التي ترسل نفس المطالبة النظامية أو ديباجة المستند بشكل متكرر، فإن تخطيط حدود المعدل والتكلفة يعتمد على عدد رموز المطالبة الفعلية، وليس فقط عدد أحرف المستند.

استكشاف الأخطاء وإصلاحها

401 غير مصرح: مفتاح API مفقود، منتهي الصلاحية، أو منسق بشكل غير صحيح. تحقق من أن رأس Authorization يقرأ Bearer <your_key> بمسافة وبدون أحرف إضافية.

404 أو النموذج غير موجود: معرف النموذج خاطئ. تأكد من أن السلسلة الدقيقة tencent/hy3 تطابق المعرف المعروض على صفحة نموذج Novita AI. معرفات النماذج حساسة لحالة الأحرف.

429 تجاوز حد المعدل: لقد تجاوزت عدد الطلبات أو الرموز في الدقيقة لمستواك. أضف منطق إعادة المحاولة مع التراجع الأسي، أو اطلب مستوى أعلى إذا كان عبء العمل الخاص بك يتطلب ذلك باستمرار.

finish_reason: length: تم اقتطاع الرد لأنه وصل إلى max_tokens. ارفع قيمة max_tokens إذا كنت بحاجة إلى مخرجات أطول، لكن تذكر أن رموز الإخراج تؤثر على التكلفة وزمن الاستجابة.

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

استدعاء الأداة يعيد وسيطات غير متوقعة: راجع مخطط أداتك. أضف أوصافًا أكثر تحديدًا لكل معامل، قم بتضمين قيم أمثلة في حقل الوصف، واذكر الحقول المطلوبة صراحة. اختبر بمخططات مبسطة أولاً، ثم أضف التعقيد.

الأسئلة الشائعة

هل Hy3 متاح على Novita AI؟

نعم. يسرد Novita AI Hy3 كنموذج LLM بدون خادم بمعرف API tencent/hy3.

ما هو معرف النموذج الصحيح؟

استخدم tencent/hy3 في جميع استدعاءات API. استخدم “Hy3” في النصوص الموجهة للمستخدم.

ما نقطة النهاية التي يجب استخدامها؟

استخدم نقطة نهاية إكمال المحادثة المتوافقة مع OpenAI: POST https://api.novita.ai/openai/v1/chat/completions. قم بتعيين عنوان URL الأساسي إلى https://api.novita.ai/openai عند استخدام OpenAI SDK.

ما حجم نافذة السياق؟

يدعم Hy3 نافذة سياق بحجم 262,144 رمزًا وما يصل إلى 262,144 رمز إخراج، كما هو مدرج على صفحة نموذج Novita AI.

هل يدعم Hy3 استدعاء الدوال؟

نعم. يدعم Hy3 استدعاء الدوال من خلال معامل tools في طلب إكمال المحادثة. يسرد Novita استدعاء الدوال والمخرجات المنظمة كميزات مدعومة.

هل يدعم Hy3 التفكير؟

التفكير مدرج كميزة على صفحة نموذج Novita AI. معاملات الطلب المحددة لتفعيل التفكير مع tencent/hy3 غير مؤكدة في وثائق Novita الحالية. تحقق من مرجع API لإكمال المحادثة من Novita AI وقم بإجراء استدعاء اختباري للتحقق من تنسيق المعامل قبل بناء سلوك التفكير في الإنتاج.

ما المدخلات التي يقبلها Hy3؟

يقبل Hy3 مدخلات نصية فقط. لا يسرد وسائط الصور أو الفيديو على صفحة نموذج Novita AI.

ما هي بنية Hy3؟

يستخدم Hy3 بنية MoE (خليط الخبراء) بإجمالي 295 مليار معامل و21 مليار معامل نشط لكل تمريرة أمامية. هذا يسمح له بخدمة طلبات كبيرة السياق بتكلفة حسابية أقل مقارنة بالنماذج الكثيفة ذات الجودة المماثلة.

كيف يمكنني الحصول على حد معدل أعلى؟

تختلف حدود المعدل حسب مستوى الحساب. يتم سرد عتبات وحدود المستوى الحالية في وثائق حدود معدل Novita AI. اتصل بدعم Novita AI لخيارات الترقية.

مقالات موصى بها

• استدعاء الدوال والمخرجات المنظمة على Novita AI
• كيفية تطوير سير عمل وكيل للبحث العميق باستخدام LangChain وواجهة LLM API من Novita AI
• واجهة Hunyuan Image 3 API على Novita AI: دليل توليد الصور من النص