الانتقال إلى المحتوى الرئيسي
github.com/AceDataCloud/SDK/go هو SDK الرسمي لـ Ace Data Cloud بلغة Go، حيث يقوم بتغليف chat completions / images / video / music / search على api.acedata.cloud في سلسلة أسلوب client.OpenAI().Chat().Completions().Create(...)، ويأتي مع تدفق SSE (استنادًا إلى القناة)، وإعادة المحاولة التلقائية مع التراجع والأخطاء المخصصة. يتماشى الأسلوب مع context.Context + خيارات وظيفية، مما يجعله مناسبًا للإدماج في أي خدمة Go خلفية أو CLI. المصدر والوثائق:

التثبيت

إخراج فحص إصدار وحدة Go النظيفة:
تفسير النتائج:
  • حاليًا لا توجد علامة semver، وgo get يجلب إصدار commit الوهمي v0.0.0-<timestamp>-<sha>؛ سيتم قفل هذا الإصدار في go.sum، مما يتيح لأعضاء الفريق الحصول على نفس الاعتماد عند سحب نفس الكود.
  • SDK Go حاليًا يركز على chat.completions (متزامن + تدفق) كمسار رئيسي مستقر، بينما موارد الوسائط المتعددة (images / video / audio) وTaskHandle في مرحلة alpha. يُفضل استخدام TypeScript SDK أو Python SDK في السيناريوهات التي تتطلب هذه القدرات.

إعداد رمز API

يرجى الرجوع إلى نظرة عامة على SDK - طلب رمز API للحصول على الرمز، ثم في shell قم بـ export:
عند إنشاء العميل، يتم حقن الرمز بشكل صريح من خلال خيار WithAPIToken(...)؛ لن يقوم SDK Go بقراءة متغيرات البيئة تلقائيًا، مما يتطلب من كود الأعمال استخدام os.Getenv، مما يجعل الأمر أكثر تحكمًا في السيناريوهات متعددة الحسابات أو الاختبار الذاتي.

المثال 1: chat.completions (غير متدفق)

نتيجة تشغيل البرنامج:
توضيح النتائج:
  • id هو معرّف استجابة متوافق مع OpenAI، ويمكن العثور عليه في سجل الاستخدام في وحدة التحكم.
  • content ADC_GO_SDK_OK هو المخرجات الفعلية للنموذج، ويثبت أن SDK لم يغيّر الاستجابة.
  • معظم مدة 6.4 ثانية تُستهلك في مصافحة TLS الأولى + توليد النموذج؛ وبعد إعادة استخدام مثيل client، يصبح زمن الاستجابة مماثلًا لـ TS / Python (حوالي 2 إلى 3 ثوانٍ).
  • الاستجابة موحّدة وتأتي على هيئة map[string]any، ويلزم إجراء تأكيد النوع يدويًا.

المثال 2: chat.completions (تدفق SSE)

CreateStream يعيد قناتين: &lt;-chan map[string]any هي قطع SSE المحللة إطارًا بإطار، و&lt;-chan error لن تحتوي على عناصر قابلة للقراءة إلا بعد انتهاء التدفق (بشكل طبيعي أو بخطأ).
نتيجة تشغيل البرنامج:
تفسير النتائج:
  • كانت أول إطار 1633 مللي ثانية، واستغرق جمع جميع الـ 13 قطعة 1816 مللي ثانية - حيث استغرق الـ 12 إطارًا المتبقية 183 مللي ثانية فقط.
  • range chunks ستخرج من الحلقة بشكل طبيعي عند انتهاء التدفق؛ قناة errs ست yield عنصر واحد كحد أقصى، ويمكن استخدام ok للتحقق من الأخطاء.
  • فائدة هذه المجموعة من أسلوب القناة هي أنه يمكن استخدام select مع context.Context للمهل / الإلغاء، دون الحاجة إلى تغليف إضافي.

المثال 3: معالجة الأخطاء المخصصة

adc.APIError تغطي 401 / 403 / 404 / 422 / 429 / 5xx، يمكن لرمز العمل استخدام errors.As للحصول على الحقول الهيكلية. يتم الاحتفاظ برموز الحالة HTTP، ورمز الخدمة code و message كما هي. أخطاء طبقة الشبكة (فشل DNS، اتصال مرفوض، إلخ) تتبع context.DeadlineExceeded، net.OpError وغيرها من الأخطاء القياسية في Go، ولن يتم ابتلاعها.

خيارات التكوين (خيارات وظيفية)

NewClient تعيد (*Client, error): عندما يكون الرمز فارغًا و لم يتم تمرير WithPaymentHandler (X402) سيتم الإبلاغ عن خطأ على الفور، مما يسهل اكتشاف نقص التكوين خلال فترة بدء الخدمة.

متقدم: إعادة استخدام العميل

تستخدم مكتبة Go SDK داخليًا *http.Client + http.Transport، مع مجموعة اتصالات و HTTP/2 إعادة استخدام. يوصى بإنشاء *adc.Client واحد فقط خلال دورة حياة العملية، ثم مشاركته عبر goroutine - جميع الطرق آمنة للتزامن.

القيود وخارطة الطريق

الحالي المستقر / الموصى به للاستخدام الإنتاجي:
  • ✅ client.OpenAI().Chat().Completions().Create غير متزامن وغير متدفق
  • ✅ client.OpenAI().Chat().Completions().CreateStream تدفق SSE
  • ✅ errors.As + APIError معالجة الأخطاء
  • ✅ إعادة المحاولة التلقائية + التراجع الأسي
لا يزال في مرحلة ألفا:
  • 🚧 client.Images() / client.Video() / client.Audio() — الواجهة في تطور، يُنصح باستخدام HTTP مباشرة
  • 🚧 TaskHandle استعلام غير متزامن — لم يتم الكشف عنه بعد في واجهة Go SDK
  • 🚧 WithPaymentHandler (X402 دفع على السلسلة) — في الخطط، حاليًا X402 يدعم فقط TypeScript و Python

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

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

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