كيفية ربط Tencent Hunyuan Hy4 API؟ تشغيل أول طلب باستخدام OpenAI SDK وتقدير التكلفة

كيفية ربط Tencent Hunyuan Hy4 API؟ تشغيل أول طلب باستخدام OpenAI SDK وتقدير التكلفة

腾讯混元 Hy4 API 接入:用 OpenAI SDK 跑通第一个纯文本请求

摘要:本文用 OpenAI Python SDK 以非流式方式调用腾讯混元 Hy4 API,跑通第一个纯文本请求,并说明怎样验收结果、估算费用、核对账单和处理常见报错。

الإجابة المباشرة: يمكن الوصول إلى واجهة Tencent Hunyuan Hy4 API عبر الواجهة المتوافقة مع OpenAI التي توفرها APIYI. يكفي تجهيز ثلاثة إعدادات لإرسال أول طلب:

  • المفتاح: أنشئه على api.apiyi.com/token، واحفظه في متغير البيئة APIYI_API_KEY.
  • عنوان URL الأساسي للـ SDK: https://api.apiyi.com/v1.
  • معرّف النموذج: hy4.

نقطة نهاية HTTP المقابلة هي POST https://api.apiyi.com/v1/chat/completions. حتى تاريخ 2026-11-21، كان سعر Hy4 في جدول التسعير لكل مليون token كما يلي: الإدخال دون إصابة الذاكرة المؤقتة 0.85 دولار، والإخراج 2.55 دولار، وقراءة الذاكرة المؤقتة 0.045 دولار. الفاتورة الفعلية تُحدَد وفق جدول تسعير APIYI على العنوان docs.apiyi.com/models (تصنيف Tencent).

الخط الزمني كما يلي: أصدرت Tencent النسخة الرسمية من Hy4 في 4 نوفمبر، وفتحت الأوزان في 20 نوفمبر. وقد أدرجت APIYI هذا الطراز قبل فتح الأوزان، وإعلان الإدراج متاح على docs.apiyi.com/news/hy4-launch. يتضمن الإعلان مثالاً للاستدعاء المتدفق، لذلك سيتناول هذا المقال أربعة أمور أخرى فقط: الاستدعاء غير المتدفق، والتحقق من النتائج، ومراجعة الفاتورة، واستكشاف الأخطاء وإصلاحها. يذكر الإعلان أن Hy4 يدعم إدخال الصور، لكن هذا المقال يعرض النصوص فقط. الفيديو، وواجهة Responses، وComputer Use كلها خارج نطاق هذا المقال، كما لا توجد فيه أي بيانات قياس فعلية.

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-ar-image-0

خريطة معرفية وترتيب قراءة لدمج Hy4 API من Tencent Hunyuan

تنقسم العملية بأكملها إلى أربع خطوات، وناتج كل خطوة هو مدخل الخطوة التالية. يُنصح بالقراءة وفق الترتيب المرقّم. ويمكن الرجوع إلى القسم 4 وحده عند ظهور خطأ.

الخطوة القسم المقابل في النص لماذا هنا معيار القبول
تجهيز الطلب 1.1، 1.2 إذا أخطأت في كتابة نقطة النهاية أو اسم النموذج أو المفتاح، فستفشل الخطوات اللاحقة يمكن استيراد SDK، ويُقرأ المفتاح من متغير البيئة، ولا يوجد مفتاح صريح في الشيفرة
أول استدعاء 2.1، 2.2 استخدم أولًا نصًا قصيرًا لا يحتوي على بيانات عملاء للتأكد من أن المسار يعمل يكون المحتوى المُعاد «المنتج=Hunyuan، الإصدار=Hy4»، من دون اقتطاع، مع حفظ usage وrequest ID
مطابقة الفاتورة 3.1، 3.2 بعد نجاح المسار، قدّر التكلفة لتقرر ما إذا كان يمكن توسيع حجم الاستدعاءات تتطابق القيمة التقديرية بندًا ببند مع سجل الاستهلاك في لوحة التحكم
تشخيص الأعطال 4 عند فشل أي خطوة، حدّد السبب من خلال رمز الخطأ وجسم الاستجابة الخطأ القدرة على التمييز بين خطأ الإعداد، ومشكلة الصلاحيات، وتحديد المعدل، والمهلة، وتحديد ما إذا كانت إعادة المحاولة ممكنة

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-ar-image-1

للعلم: مصطلحات Hy4 API ذات الصلة

المصطلح شرح موجز
غير متدفق (stream=False) يعيد النموذج النتيجة الكاملة دفعة واحدة بعد اكتمال التوليد، ما يسهّل فحص المحتوى والاستخدام إجمالًا
finish_reason سبب انتهاء التوليد في هذه المرة. تعني stop انتهاءً طبيعيًا، بينما تعني length بلوغ حد الطول ومن ثم الاقتطاع
usage حقل استهلاك الرموز (tokens) في الاستجابة، ويشمل عادةً prompt_tokens (الإدخال) وcompletion_tokens (الإخراج)
request ID معرّف الطلب الواحد، ويُستخدم لتحديد هذا الاستدعاء في السجلات. لا ترافقه كل استجابة بالضرورة
قراءة من ذاكرة التخزين المؤقت الجزء من الإدخال الموجود في ذاكرة التخزين المؤقت، ويُحتسب بسعر قراءة ذاكرة التخزين المؤقت المنفصل
المجموعة (Default/SVIP) المجموعة التي ينتمي إليها الرمز، وهي التي تحدد النماذج التي يمكن لهذا الرمز استدعاؤها

1. تحضير طلب واجهة برمجة تطبيقات Tencent Hunyuan Hy4

1.1 إعداد نموذج Hy4 ونقطة النهاية

يرجى التحقق من عناصر الإعداد واحدًا تلو الآخر أولاً. معظم حالات فشل الاستدعاء الأول تحدث في هذه الخطوة.

عنصر الإعداد القيمة الوصف
SDK base_url https://api.apiyi.com/v1 اكتب فقط حتى /v1، وسيقوم SDK بإضافة /chat/completions تلقائيًا
نقطة نهاية HTTP POST https://api.apiyi.com/v1/chat/completions استخدم هذا العنوان عند إرسال طلب HTTP مباشرة دون استخدام SDK
معرّف النموذج hy4 اسم الطراز للإصدار الرسمي، يُكتب بأحرف صغيرة كما هو
المجموعات المتاحة Default、SVIP يجب أن تتضمن مجموعة الرمز المميز Hy4
طريقة الإخراج stream=False يستخدم هذا المقال الوضع غير التدفقي بالكامل

الخطأ الأكثر شيوعًا هو إدخال نقطة النهاية الكاملة في base_url. سيقوم SDK بإضافة /chat/completions مرة أخرى بعد هذا العنوان، مما يؤدي إلى تكرار المسار وإرجاع خطأ 404. للحصول على الشرح الكامل لواجهة البرمجة المتوافقة، راجع docs.apiyi.com/api-capabilities/openai/compatible.

1.2 تثبيت OpenAI SDK وحفظ المفتاح بأمان

عنوان مشروع SDK الرسمي لـ Python هو github.com/openai/openai-python. يُنصح بالتثبيت في بيئة افتراضية لتجنب التعارض مع إصدارات الحزم الموجودة في النظام:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install openai

يتم إنشاء المفتاح في api.apiyi.com/token. عند الإنشاء، يرجى التأكد من أن المجموعة التي ينتمي إليها الرمز المميز يمكنها استدعاء Hy4. بعد الحصول على المفتاح، اكتبه في متغيرات البيئة للطرفية الحالية، ولا تكتبه في ملفات الكود:

export APIYI_API_KEY="你的令牌"     # Windows PowerShell: $env:APIYI_API_KEY="你的令牌"

انتبه للنقاط التالية عند إدارة المفتاح:

  • يقرأ الكود المفتاح فقط عبر os.environ['APIYI_API_KEY']. عند عدم تعيين متغير البيئة، استخدم getpass للإدخال التفاعلي، ولن يظهر المحتوى المُدخل على الشاشة.
  • إذا كنت تستخدم ملف .env لحفظ المفتاح، فأضفه إلى .gitignore لتجنب إرساله إلى المستودع.
  • عند ظهور المفتاح في لقطات الشاشة أو السجلات أو تذاكر الدعم، استبدله أولاً بقناع مثل sk-***.

التحقق: شغّل في الطرفية python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))". إذا ظهر رقم الإصدار وTrue، فهذا يعني أن هذه الخطوة قد اكتملت.

2. إرسال أول طلب Hy4 باستخدام OpenAI SDK

2.1 مثال Python كامل غير تدفقي

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

import os
import re
from getpass import getpass
from openai import OpenAI

key = os.environ.get("APIYI_API_KEY") or getpass("输入 APIYI_API_KEY:")

PROMPT = "仅从这句话提取产品和版本:腾讯混元 Hy4 正式版已上线。请只写一行:产品=…;版本=…"

with OpenAI(
    base_url="https://api.apiyi.com/v1",   # واجهة APIYI المتوافقة مع OpenAI
    api_key=key,
    timeout=60.0,
    max_retries=0,                         # تعطيل إعادة المحاولة التلقائية؛ عند الفشل يقرر الإنسان ما إذا كان سيعيد الإرسال
) as client:
    result = client.chat.completions.create(
        model="hy4",
        messages=[{"role": "user", "content": PROMPT}],
        stream=False,
    )

request_id = getattr(result, "_request_id", None)
print("request_id:", request_id if request_id else "响应未提供")

if not result.choices:
    raise SystemExit("未通过:choices 为空,没有返回正文")

choice = result.choices[0]
content = (choice.message.content or "").strip()
print("finish_reason:", choice.finish_reason)
print("content:", content)

usage = getattr(result, "usage", None)
prompt_tokens = getattr(usage, "prompt_tokens", None) if usage else None
completion_tokens = getattr(usage, "completion_tokens", None) if usage else None
print("prompt_tokens:", prompt_tokens if prompt_tokens is not None else "缺失(不按 0 处理)")
print("completion_tokens:", completion_tokens if completion_tokens is not None else "缺失(不按 0 处理)")


def accept(text: str, finish_reason) -> tuple[bool, str]:
    if not text:
        return False, "正文为空"
    if finish_reason == "length":
        return False, "输出被截断"
    t = re.sub(r"\s+", "", text)
    t = t.replace(":", "=").replace(":", "=").replace(";", ";")
    prod = re.search(r"产品=([^;\n]+)", t)
    ver = re.search(r"版本=([^;\n]+)", t)
    if not prod or not ver:
        return False, "缺少产品或版本字段"
    strip_punct = lambda s: re.sub(r"[。..,,、!!??\"“”'‘’]", "", s)
    if "混元" not in strip_punct(prod.group(1)):
        return False, f"产品值错误:{prod.group(1)}"
    if strip_punct(ver.group(1)) != "Hy4":
        return False, f"版本值错误:{ver.group(1)}"
    return True, "通过"


ok, reason = accept(content, choice.finish_reason)
print("验收:", reason)

هناك عدة إعدادات في المثال تحتاج إلى توضيح:

  • max_retries=0 يعطّل إعادة المحاولة التلقائية في SDK. وكما سنرى في القسم 4، قد يكون الخادم قد نفّذ الطلب بالفعل بعد انتهاء المهلة، وقد تؤدي إعادة الإرسال التلقائية إلى احتساب رسوم مكررة؛ لذلك يجب أن يقرر الإنسان ما إذا كان سيعيد المحاولة أم لا.
  • عبارة with تغلق الاتصال بعد انتهاء الاستدعاء.
  • عندما يكون حقل usage مفقودًا، يطبع الكود صراحةً «مفقود» ولا يعامله على أنه 0، وذلك لتجنب تفويت تكلفة عند حساب الفاتورة لاحقًا.

لمزيد من التفاصيل حول بنية الاستجابة، راجع docs.apiyi.com/api-capabilities/openai/response-handling.

2.2 معايير قبول أول طلب Hy4

عند القبول، لا ننظر إلا إلى حقلين داخل message.content: قيمة المنتج يجب أن تحتوي على «混元»، وقيمة الإصدار يجب أن تكون «Hy4». الاختلافات في النقطتين الرأسيتين والفاصلة المنقوطة بين الشكلين كامل العرض ونصف العرض، وكذلك اختلافات علامات الترقيم في نهاية الجملة، مقبولة. فيما يلي سطر مخرجات مطابق للمتطلبات، وهو تنسيق توضيحي فقط وليس استجابة فعلية من الخدمة:

产品=腾讯混元;版本=Hy4

تُعد الحالات التالية مرفوضة دائمًا، ولا يجوز قبولها لمجرد أنها «تبدو متقاربة»:

الحالة التقييم السبب
أن تكون choices فارغة، أو أن يكون content سلسلة نصية فارغة لا يجتاز لم نصل إلى النص الأساسي، ما يعني أن المسار لم يعمل فعليًا من البداية إلى النهاية
أن تكون قيمة finish_reason هي length لا يجتاز تم قطع المخرجات، والنتيجة غير مكتملة
أن يُكتب الإصدار بقيمة أخرى مثل Hy3 أو Hunyuan لا يجتاز قيمة الحقل خاطئة
أن يقتصر الاختلاف على علامات الترقيم أو المسافات أو النقطتين الرأسيتين بين كاملة العرض ونصف العرض يجتاز يُعد اختلافًا تنسيقيًا مسموحًا به

بعد اجتياز القبول، سجّل request ID (إن وُجد في الاستجابة)، ووقت الطلب، واسم النموذج، وprompt_tokens وcompletion_tokens. ستُستخدم هذه المعلومات عند مطابقة الفاتورة في القسم 3.2.

3. تقدير تكلفة Hy4 API والتحقق منها

3.1 تقدير تكلفة مهمة دفعية واحدة وفق جدول التسعير

المدخلات في الطلب الأول قصيرة جدًا، وتكلفتها ضئيلة لا تُذكر، لذا فإن استخدامها لتقدير التكلفة لا يحمل قيمة كبيرة. لننتقل بدلاً من ذلك إلى سيناريو افتراضي لا علاقة له بالطلب القصير في المثال: مهمة ما مدخلاتها 100 ألف token، جميعها لم تُصيب الذاكرة المؤقتة، ومخرجاتها 20 ألف token. تُحسب المدخلات والمخرجات كلٌّ على حدة بسعر وحدته:

بند الفوترة الاستخدام المفترض سعر الوحدة (لكل مليون token) التكلفة
مدخلات لم تصب الذاكرة المؤقتة 100,000 $0.85 $0.085
المخرجات 20,000 $2.55 $0.051
الإجمالي — — $0.136

عملية الحساب هي 0.1 × 0.85 + 0.02 × 2.55 = 0.136. ويجب الانتباه إلى نقطتين عند التقدير:

  • سعر وحدة المخرجات يعادل 3 أضعاف سعر وحدة المدخلات التي لم تصب الذاكرة المؤقتة. وفي المهام ذات حجم مخرجات كبير، تتحدد التكلفة أساسًا بالمخرجات.
  • إذا كان completion_tokens يشمل بالفعل جزء التفكير الخاص بالنموذج، فلا تُضِف تكلفة التفكير مرة أخرى بشكل منفصل، وإلا فستحسبها مرتين.

3.2 التمييز بين حاوية الذاكرة المؤقتة وسجل الاستهلاك الفعلي

“قراءة الذاكرة المؤقتة” بندٌ يُحتسب بشكل منفصل، لكن طريقة تقسيم الحقول قد تختلف من استجابة لأخرى، لذا لا يوجد اسم حقلٍ عام يمكن أن يضمن دقة النتيجة. والطريقة الموثوقة هي التأكد أولاً من الفاتورة: هل الرموز (tokens) التي أصابت الذاكرة المؤقتة محسوبة ضمن إجمالي المدخلات؟

إذا أكّدت الفاتورة أن جزء الذاكرة المؤقتة مُدرجٌ ضمن إجمالي المدخلات، فاخصم جزء الذاكرة المؤقتة مرة واحدة من إجمالي المدخلات، ثم احسب سعر كل جزء على حدة. نُكمل هنا بفرضية البند 3.1، ونفترض كذلك أن 40 ألفًا من أصل 100 ألف مدخل أصابت الذاكرة المؤقتة:

بند الفاتورة الاستخدام المفترض سعر الوحدة (لكل مليون token) التكلفة
مدخلات لم تصب الذاكرة المؤقتة 60,000 $0.85 $0.051
قراءة الذاكرة المؤقتة 40,000 $0.045 $0.0018
المخرجات 20,000 $2.55 $0.051
الإجمالي — — $0.1038

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-ar-image-2

القيم التقديرية للاستدلال فقط، والمعتمد النهائي هو سجل الاستهلاك. طريقة التحقق هي تصفية السجلات المقابلة في وحدة التحكم عبر api.apiyi.com/log:

  1. تضييق النطاق حسب وقت الطلب.
  2. إذا وفّرت الاستجابة request ID، فاستخدمه لتحديد هذا الطلب بدقة.
  3. تأكّد من أن النموذج هو hy4، وأن الرمز المميز (token) مطابق للرمز المستخدم فعليًا في الشيفرة.
  4. قارن استخدام المدخلات والذاكرة المؤقتة والمخرجات ومبلغ الخصم في السجل مع القيم التقديرية للتحقق من التطابق.

لمعرفة المعاني التفصيلية لحقول السجل، راجع docs.apiyi.com/faq/log-billing-explained.

4. استكشاف أعطال Hy4 API وإصلاحها

عند استكشاف الأعطال، ابدأ بفحص رمز حالة HTTP، ثم اقرأ التفاصيل الموجودة في جسم الخطأ. فالاعتماد على رمز الحالة وحده قد يقودك إلى تشخيص خاطئ؛ فمثلاً قد يكون الرمز 429 ناتجًا عن أسباب مختلفة تمامًا. التقط استثناءات SDK عند موضع الطلب الأصلي في القسم 2.1: راقب APITimeoutError عند مهلة الاتصال، وAPIConnectionError عند أي فشل اتصال آخر. وعند الحصول على استجابة خطأ، سجّل من APIStatusError كلاً من status_code وrequest_id وجسم الخطأ. حدّد أولاً نتيجة الطلب الحالي، ثم قرر ما إذا كنت بحاجة إلى إعادة المحاولة؛ وقبل الإبلاغ، أخفِ المعلومات الحساسة من جسم الخطأ. ترتيب المعالجة كما يلي:

الخطأ أول ما يجب فحصه هل تُعيد المحاولة؟
401 تحقق من صحة مفتاح API أو انتهاء صلاحيته، ومن أن base_url هو https://api.apiyi.com/v1 لا تُعد المحاولة قبل تصحيح الإعدادات
403 استنتج من جسم الخطأ ما إذا كانت المشكلة متعلقة بأذونات المجموعة، وتأكد من أن المجموعة التي ينتمي إليها الرمز تتضمن Hy4 لا تُعد المحاولة قبل تصحيح الأذونات
404 هل أُضاف /chat/completions إلى المسار مرتين؟ وهل اسم النموذج هو hy4؟ لا تُعد المحاولة قبل تصحيح الإعدادات
429 حدد من جسم الخطأ ما إذا كان الأمر يتعلق بتحديد مؤقت أم بنقص في الحصة إذا كان التحديد مؤقتًا، يمكن إعادة المحاولة بعدد محدود من المرات مع تراجع زمني؛ وإذا كانت الحصة غير كافية، فيجب الشحن أو تعديل الحصة أولاً
خطأ اتصال هل الشبكة أو الوكيل أو DNS سليم؟ وهل بروتوكول base_url ونطاقه صحيحان؟ يمكن إعادة المحاولة بعد استعادة الشبكة
مهلة ابحث أولاً في api.apiyi.com/log بحسب الوقت لتتأكد مما إذا كان الطلب قد نُفّذ بالفعل إذا نُفّذ فلا تُعد إرساله، وإذا لم يُنفّذ فأعد المحاولة

فيما يخص 429 والمهلة، هناك توضيحان مهمان:

  • إعادة المحاولة مع تراجع زمني عند 429: تنطبق فقط على التحديد المؤقت. اضبط عدد المحاولات بحد أقصى، مع زيادة الفاصل الزمني تدريجيًا في كل مرة. وإذا كانت الحصة غير كافية، فلن تنجح إعادة المحاولة مهما بلغ عددها.
  • المهلة: عدم تلقّي العميل استجابة خلال 60 ثانية لا يعني أن الخادم لم يعالج الطلب. وإذا كان الخادم قد أكمل المعالجة، فإن إعادة الإرسال مباشرة ستؤدي إلى تنفيذ الطلب مرة أخرى، وستُخصم التكلفة مرة أخرى. لذلك يجب فحص السجلات أولاً للتأكد من أن الطلب لم يُنفّذ، ثم إعادة إرساله.

إذا كنت بحاجة إلى التواصل مع الدعم الفني، فقبل الإرسال أخفِ المعلومات الحساسة من جسم الخطأ والسجلات، مثل مفتاح API وبيانات العملاء، ثم أرفق رمز الحالة ووقت الطلب واسم النموذج وrequest ID. راجع طريقة حفظ معلومات الخطأ وإرسالها على docs.apiyi.com/api-manual/error-reporting.

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

  1. أن تُخرج دالة التحقق النص «通过» (أي: نجاح).
  2. أن تكون قيمة finish_reason غير length.
  3. أن تجد في سجلات وحدة التحكم سجلًا بالوقت نفسه باسم النموذج hy4، وأن تتطابق بيانات الاستخدام فيه مع usage المسجلة محليًا.

موضوعات ذات صلة