Skip to main content
تقدم Ace Data Cloud SDK رسميًا لثلاث لغات: TypeScript / Python / Go، حيث تقوم بتغليف قدرات api.acedata.cloud مثل إكمالات الدردشة، الصور، الفيديو، الموسيقى، البحث، x402 وغيرها في طرق قوية النوع، مما يوفر عليك كتابة HTTP، SSE، استقصاء المهام، معالجة الأخطاء وتأخير إعادة المحاولة. تم تنظيم هذا الفصل وفقًا لترتيب الاتصال الحقيقي: أولاً احصل على رمز API من وحدة التحكم، ثم اختر اللغة واطلع على الفصل المقابل، وأخيرًا انظر إلى استقصاء المهام، الاستجابة المتدفقة والاستخدامات المتقدمة للدفع على سلسلة X402.

المستودع والحزم

مصفوفة القدرات للغات الثلاث

الموارد المتعددة والمهام في SDK Go حاليًا في مرحلة alpha (الإصدار الوهمي v0.0.0-20260505072132-4a3d921f9bb4)، والقدرة المستقرة هي chat.completions. يُفضل اختيار TypeScript أو Python في السيناريوهات متعددة الوسائط.

متى تستخدم SDK / MCP / HTTP الأصلي / X402

لا تتعارض SDK مع X402: تدعم SDK كل من “مسار الرمز” و”مسار paymentHandler”، انظر SDK + خطاف دفع X402.

طلب رمز API

لاستخدام SDK، يجب أولاً الذهاب إلى وحدة التحكم في Ace Data Cloud - قائمة التطبيقات لطلب رمز API: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول سيتم العودة تلقائيًا إلى الصفحة الحالية. عند الطلب لأول مرة، سيكون هناك حد مجاني متاح، يمكنك تجربة مجموعة متنوعة من خدمات الذكاء الاصطناعي التي تقدمها Ace Data Cloud مجانًا. انسخ الرمز الذي حصلت عليه، وسنعتبره موحدًا كـ {token}.

متغيرات البيئة الموحدة

تقوم SDK للغات الثلاث تلقائيًا بقراءة نفس متغير البيئة ACEDATACLOUD_API_TOKEN، يُوصى باستخدام export في shell، مما يسمح لـ SDK بالتقاطه تلقائيًا:
يمكنك أيضًا تمريرها صراحة عند إنشاء العميل، وأسماء المعلمات المقابلة لكل لغة هي:
  • TypeScript: new AceDataCloud({ apiToken: '{token}' })
  • Python: AceDataCloud(api_token="{token}")
  • Go: adc.NewClient(adc.WithAPIToken("{token}"))
ملاحظة: في مستودع مشروع AceDataCloud، يُعتبر تقليديًا ACEDATACLOUD_API_KEY (في .env / CI)، لكن هذه الثلاثة SDK نفسها تتعرف فقط على ACEDATACLOUD_API_TOKEN. إذا كان لديك فقط ACEDATACLOUD_API_KEY في بيئتك، يرجى تمريرها صراحة عند الإنشاء.

ثلاث أمثلة للبدء في 30 ثانية

تقوم الفقرات الثلاث التالية بنفس الشيء: استدعاء gpt-4o-mini، مما يجعله يرد فقط بـ ADC_*_OK. كل فقرة مرفقة بـ نتيجة تشغيل حقيقية، يمكنك استخدام رمزك الخاص لإعادة إنتاجها.

TypeScript

حاليًا، تعلن SDK أن الاستجابة هي Record<string, unknown>، وفي وقت التشغيل هي كائن JSON عادي، يمكن الوصول إليه مباشرة حسب الحقول. في مشاريع TS الصارمة، إذا واجهت أخطاء في النوع، يمكنك مؤقتًا استخدام as any، أو الرجوع إلى استقصاء المهام والاستجابة المتدفقة في SDK لإنشاء ملف تغليف مخصص.
نتيجة تشغيل البرنامج:

Python

Python SDK الحالية تعيد dict، لذا استخدم res["id"] بدلاً من res.id. هذه النقطة تختلف عن openai-python، يجب الانتباه عند الترحيل.
نتيجة تشغيل البرنامج:

Go

استجابة Go SDK موحدة هي map[string]any، ولا توجد بنية قوية، يجب إجراء تأكيد النوع بنفسك. جميع موصلات الموارد هي سلسلة من الطرق: client.OpenAI().Chat().Completions().Create(...).
نتيجة تشغيل البرنامج:
تأتي استجابات اللغات الثلاثة id، elapsed_ms، و usage من نفس المصدر: عبر PlatformGateway للتحقق → واجهة برمجة التطبيقات المتوافقة مع OpenAI المستهدفة → كتابة سجلات الفوترة. حقل content هو الإخراج الحقيقي للنموذج، واستخدام العلامة الثابتة ADC_*_OK هو لإثبات أن الاستجابة لم يتم تعديلها بواسطة SDK.

ترتيب القراءة الموصى به

  1. دليل دمج SDK TypeScript —— الكود الذي يمكن تشغيله بعد npm install.
  2. دليل دمج SDK Python —— ثلاث طرق للاستخدام: متزامن، غير متزامن، وتدفق.
  3. دليل دمج SDK Go —— أسلوب Go لـ context.Context وتدفق القنوات.
  4. استطلاع المهام واستجابة التدفق لـ SDK —— اختلافات وحدة TaskHandle، تفاصيل تنفيذ SSE، إعادة المحاولة.
  5. SDK + خطاف دفع X402 —— بدون توكن، تسوية على السلسلة حسب الاستدعاء.

كيفية عرض الرصيد المتبقي

يمكنك عرض الرصيد المتبقي الحالي لحسابك من خلال لوحة تحكم Ace Data Cloud - قائمة التطبيقات. يمكنك عرض جميع سجلات الاستخدام وتفاصيل الخصم من خلال لوحة تحكم Ace Data Cloud - تاريخ الاستخدام.

لمعرفة المزيد