> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# دليل دمج Go SDK

> Platform API guide - Ace Data Cloud

[`github.com/AceDataCloud/SDK/go`](https://pkg.go.dev/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.

المصدر والوثائق:

* مستودع SDK: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* وحدة Go: [https://pkg.go.dev/github.com/AceDataCloud/SDK/go](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)

## التثبيت

```bash theme={null}
go get github.com/AceDataCloud/SDK/go
```

إخراج فحص إصدار وحدة Go النظيفة:

```text theme={null}
$ go list -m github.com/AceDataCloud/SDK/go
github.com/AceDataCloud/SDK/go v0.0.0-20260505072132-4a3d921f9bb4
```

تفسير النتائج:

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

## إعداد رمز API

يرجى الرجوع إلى [نظرة عامة على SDK - طلب رمز API](https://platform.acedata.cloud/documents/acedatacloud-sdk#申请-api-token) للحصول على الرمز، ثم في shell قم بـ `export`:

```bash theme={null}
export ACEDATACLOUD_API_TOKEN={token}
```

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

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

```go theme={null}
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    res, err := client.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Reply with exactly: ADC_GO_SDK_OK"}},
        MaxTokens: 20,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("id", res["id"])
    fmt.Println("model", res["model"])
    choices := res["choices"].([]any)
    msg := choices[0].(map[string]any)["message"].(map[string]any)
    fmt.Println("content", msg["content"])
    usage := res["usage"].(map[string]any)
    fmt.Printf("usage prompt=%v completion=%v total=%v\n",
        usage["prompt_tokens"], usage["completion_tokens"], usage["total_tokens"])
}
```

نتيجة تشغيل البرنامج:

```text theme={null}
elapsed_ms 6436
id chatcmpl-89DHExvFvBc4ciIPfolZYUOy7ivxv
model gpt-4o-mini
content ADC_GO_SDK_OK
usage prompt=16 completion=5 total=21
```

تفسير النتائج:

* `id` هو معرف استجابة متوافق مع OpenAI، يمكن العثور عليه في [استخدامات التاريخ](https://platform.acedata.cloud/console/usages) في وحدة التحكم.
* `content ADC_GO_SDK_OK` هو الإخراج الحقيقي للنموذج، مما يثبت أن SDK لم يعدل الاستجابة.
* كانت معظم الـ 6.4 ثانية هي أول عملية TLS handshake + توليد النموذج، بعد إعادة استخدام مثيل العميل، كانت التأخيرات متوافقة مع TS / Python (حوالي 2\~3 ثوانٍ).
* الاستجابة موحدة كـ `map[string]any`، مما يتطلب إجراء تأكيد نوع بنفسك؛ هذا هو اختيار تصميم SDK Go الحالي - عدم إدخال هيكل عام لتجنب الاعتماد القوي على مخطط استجابة واحد.

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

`CreateStream` يعيد قناتين: `&lt;-chan map[string]any` هي قطع SSE المحللة إطارًا بإطار، و`&lt;-chan error` لن تحتوي على عناصر قابلة للقراءة إلا بعد انتهاء التدفق (بشكل طبيعي أو بخطأ).

```go theme={null}
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    chunks, errs := client.OpenAI().Chat().Completions().CreateStream(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Count from 1 to 5 separated by spaces. Just the numbers."}},
        MaxTokens: 30,
    })

    first := int64(-1)
    cnt := 0
    collected := ""
    for chunk := range chunks {
        if first < 0 {
            first = time.Since(t0).Milliseconds()
        }
        cnt++
        if ch, ok := chunk["choices"].([]any); ok && len(ch) > 0 {
            if c0, ok := ch[0].(map[string]any); ok {
                if d, ok := c0["delta"].(map[string]any); ok {
                    if s, ok := d["content"].(string); ok {
                        collected += s
                    }
                }
            }
        }
    }
    if e, ok := <-errs; ok && e != nil {
        fmt.Println("stream_err", e)
    }
    fmt.Println("total_elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("first_chunk_ms", first)
    fmt.Println("chunks", cnt)
    fmt.Println("collected", collected)
}
```

نتيجة تشغيل البرنامج:

```text theme={null}
total_elapsed_ms 1816
first_chunk_ms 1633
chunks 13
collected 1 2 3 4 5
```

تفسير النتائج:

* كانت أول إطار 1633 مللي ثانية، واستغرق جمع جميع الـ 13 قطعة 1816 مللي ثانية - حيث استغرق الـ 12 إطارًا المتبقية 183 مللي ثانية فقط.
* `range chunks` ستخرج من الحلقة بشكل طبيعي عند انتهاء التدفق؛ قناة `errs` ست yield عنصر واحد كحد أقصى، ويمكن استخدام `ok` للتحقق من الأخطاء.
* فائدة هذه المجموعة من أسلوب القناة هي أنه يمكن استخدام `select` مع `context.Context` للمهل / الإلغاء، دون الحاجة إلى تغليف إضافي.

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

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    bad, _ := adc.NewClient(adc.WithAPIToken("definitely-not-a-real-token"))
    _, err := bad.OpenAI().Chat().Completions().Create(context.Background(), adc.ChatCompletionRequest{
        Model:    "gpt-4o-mini",
        Messages: []map[string]any{{"role": "user", "content": "hi"}},
        MaxTokens: 5,
    })
    if err != nil {
        var apiErr *adc.APIError
        if errors.As(err, &apiErr) {
            fmt.Println("status:", apiErr.StatusCode)
            fmt.Println("code:", apiErr.Code)
            fmt.Println("message:", apiErr.Message)
        } else {
            fmt.Println("other err:", err)
        }
    }
}
```

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

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

```go theme={null}
client, err := adc.NewClient(
    // مطلوب: رمز API؛ يُنصح بقراءته من متغيرات البيئة
    adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")),

    // عنوان جذر API للمنصة، الافتراضي https://api.acedata.cloud
    adc.WithBaseURL("https://api.acedata.cloud"),

    // مهلة الطلب الواحد، الافتراضي 5 دقائق
    adc.WithTimeout(60*time.Second),

    // عدد محاولات إعادة التشغيل التلقائية، الافتراضي 2
    adc.WithMaxRetries(2),

    // رأس الطلب المخصص
    adc.WithHeader("x-app", "my-service/1.0"),
)
```

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

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

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

```go theme={null}
// pkg/acelearn/client.go
var sharedClient *adc.Client

func init() {
    var err error
    sharedClient, err = adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        log.Fatal(err)
    }
}

func Chat(ctx context.Context, model, prompt string) (string, error) {
    res, err := sharedClient.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:    model,
        Messages: []map[string]any{{"role": "user", "content": prompt}},
    })
    if err != nil {
        return "", err
    }
    return res["choices"].([]any)[0].(map[string]any)["message"].(map[string]any)["content"].(string), nil
}
```

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

الحالي المستقر / الموصى به للاستخدام الإنتاجي:

* ✅ `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](https://platform.acedata.cloud/documents/x402-typescript-sdk) و [Python](https://platform.acedata.cloud/documents/x402-python-sdk)

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

من خلال [لوحة تحكم Ace Data Cloud - قائمة التطبيقات](https://platform.acedata.cloud/console/applications)، يمكنك عرض الرصيد المتبقي الحالي للحساب.

من خلال [لوحة تحكم Ace Data Cloud - تاريخ الاستخدام](https://platform.acedata.cloud/console/usages) يمكنك عرض جميع تاريخ الاستخدام وتفاصيل الخصم.

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

* 🟦 [`github.com/AceDataCloud/SDK/go` على pkg.go.dev](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)
* 🗂 [شفرة SDK المصدر](https://github.com/AceDataCloud/SDK/tree/main/go)
* 📘 [دليل تكامل SDK TypeScript](https://platform.acedata.cloud/documents/sdk-typescript)
* 🐍 [دليل تكامل SDK Python](https://platform.acedata.cloud/documents/sdk-python)
* 🔌 [SDK + X402 خطاف الدفع](https://platform.acedata.cloud/documents/sdk-x402-payment)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.