> ## 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.

# Przewodnik po integracji Go SDK

> Platform API guide - Ace Data Cloud

[`github.com/AceDataCloud/SDK/go`](https://pkg.go.dev/github.com/AceDataCloud/SDK/go) to oficjalne Go SDK Ace Data Cloud, które opakowuje chat completions / images / video / music / search z `api.acedata.cloud` w stylu łańcucha metod `client.OpenAI().Chat().Completions().Create(...)`, z wbudowanym strumieniem SSE (opartym na kanale), automatycznym ponownym próbowaniem z opóźnieniem i typowanymi błędami.

Styl jest zgodny z `context.Context` + opcjami funkcyjnymi, co czyni go odpowiednim do umieszczenia w dowolnej usłudze backendowej Go lub CLI.

Kod źródłowy i dokumentacja:

* Repozytorium SDK: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* Moduł Go: [https://pkg.go.dev/github.com/AceDataCloud/SDK/go](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)

## Instalacja

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

Czyste wyjście z kontroli wersji modułu Go:

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

Wyjaśnienie wyników:

* Obecnie nie ma oznaczonego tagu semver, `go get` pobiera wersję pseudo-commit `v0.0.0-<timestamp>-<sha>`; ta wersja zostanie zablokowana w `go.sum`, a członkowie zespołu pobierający ten sam kod mogą uzyskać dokładnie te same zależności.
* Go SDK obecnie koncentruje się na `chat.completions` (synchronizacja + strumień) jako głównym stabilnym ścieżce, zasoby multimedialne (`images` / `video` / `audio`) oraz `TaskHandle` w trybie polling są w fazie alfa. W przypadku potrzeby tych funkcji, proszę najpierw wybrać [TypeScript SDK](https://platform.acedata.cloud/documents/sdk-typescript) lub [Python SDK](https://platform.acedata.cloud/documents/sdk-python).

## Przygotowanie tokena API

Proszę zapoznać się z [Przegląd SDK - Uzyskiwanie tokena API](https://platform.acedata.cloud/documents/acedatacloud-sdk#申请-api-token) w celu uzyskania tokena, a następnie w shellu `export`:

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

Podczas konstruowania klienta należy jawnie wstrzyknąć przez opcję `WithAPIToken(...)`; Go SDK nie odczytuje automatycznie zmiennych środowiskowych, co wymaga, aby kod biznesowy użył `os.Getenv`, co czyni go bardziej kontrolowanym w scenariuszach z wieloma kontami lub testami.

## Przykład 1: chat.completions (nie-strumieniowe)

```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": "Odpowiedz dokładnie: 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"])
}
```

Wynik działania programu:

```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
```

Wyjaśnienie wyników:

* `id` to identyfikator odpowiedzi zgodny z OpenAI, który można znaleźć w konsoli [użycie historii](https://platform.acedata.cloud/console/usages).
* `content ADC_GO_SDK_OK` to rzeczywiste wyjście modelu, co dowodzi, że SDK nie zmieniło odpowiedzi.
* Większość 6.4 sekundy to pierwsze nawiązanie TLS + generowanie modelu, po ponownym użyciu instancji klienta opóźnienie jest zgodne z TS / Python (około 2\~3 sekundy).
* Odpowiedź jest zawsze `map[string]any`, co wymaga samodzielnego wykonania asercji typów; to jest obecny wybór projektowy Go SDK — brak wprowadzenia ogólnych struktur ma na celu umożliwienie routingu wielu modeli bez silnej zależności od pojedynczego schematu odpowiedzi.

## Przykład 2: chat.completions (SSE strumieniowe)

`CreateStream` zwraca dwa kanały: `&lt;-chan map[string]any` to zdekodowane fragmenty SSE, a `&lt;-chan error` będzie miało czytelne elementy dopiero po zakończeniu strumienia (normalnie lub w przypadku błędu).

```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": "Policz od 1 do 5 oddzielając spacjami. Tylko liczby."}},
        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)
}
```

Wynik działania programu:

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

Wyjaśnienie wyników:

* Pierwsza klatka 1633 ms, 13 fragmentów dotarło w sumie w 1816 ms — pozostałe 12 klatek zajęło tylko 183 ms.
* `range chunks` naturalnie zakończy pętlę po zakończeniu strumienia; kanał `errs` zawsze zwraca maksymalnie jeden element, co pozwala na sprawdzenie błędu przy użyciu `ok`.
* Zaletą tego stylu kanałów jest możliwość bezpośredniego użycia `select` w połączeniu z `context.Context` dla timeoutów/anulacji, bez potrzeby dodatkowego opakowywania.

## Przykład 3: typowane przetwarzanie błędów

```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": "cześć"}},
        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("inny błąd:", err)
        }
    }
}
```

`adc.APIError` jednocześnie pokrywa 401 / 403 / 404 / 422 / 429 / 5xx, kod biznesowy używa `errors.As`, aby uzyskać zorganizowane pola. Kody statusu HTTP, `code` i `message` serwera pozostają bez zmian. Błędy warstwy sieciowej (błąd DNS, odrzucenie połączenia itp.) są obsługiwane przez `context.DeadlineExceeded`, `net.OpError` i inne standardowe błędy Go, nie będą tłumione.

## Opcje konfiguracyjne (opcje funkcjonalne)

```go theme={null}
client, err := adc.NewClient(
    // Wymagane: token API; zaleca się odczyt z zmiennej środowiskowej
    adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")),

    // Podstawowy adres API platformy, domyślnie https://api.acedata.cloud
    adc.WithBaseURL("https://api.acedata.cloud"),

    // Czas oczekiwania na pojedyncze żądanie, domyślnie 5 minut
    adc.WithTimeout(60*time.Second),

    // Liczba automatycznych prób, domyślnie 2
    adc.WithMaxRetries(2),

    // Niestandardowe nagłówki żądania
    adc.WithHeader("x-app", "my-service/1.0"),
)
```

`NewClient` zwraca `(*Client, error)`: gdy token jest pusty **i** nie przekazano `WithPaymentHandler` (X402), natychmiast zgłasza błąd, co ułatwia wykrycie brakującej konfiguracji podczas uruchamiania usługi.

## Zaawansowane: ponowne użycie klienta

SDK Go wewnętrznie używa jednego `*http.Client` + `http.Transport`, z wbudowanym pulą połączeń i wielokrotnym użyciem HTTP/2. **Zaleca się utworzenie tylko jednego `*adc.Client` w cyklu życia procesu**, a następnie współdzielenie go między goroutine — wszystkie metody są bezpieczne dla współbieżności.

```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
}
```

## Ograniczenia i mapa drogowa

Obecnie stabilne / zalecane do użycia w produkcji:

* ✅ `client.OpenAI().Chat().Completions().Create` synchronizowane, nie strumieniowe
* ✅ `client.OpenAI().Chat().Completions().CreateStream` strumieniowe SSE
* ✅ `errors.As` + obsługa błędów `APIError`
* ✅ Automatyczne ponawianie + wykładnicze opóźnienie

Wciąż w fazie alpha:

* 🚧 `client.Images()` / `client.Video()` / `client.Audio()` — interfejsy są w trakcie rozwoju, zaleca się bezpośrednie użycie HTTP
* 🚧 `TaskHandle` asynchroniczne sprawdzanie — jeszcze nie udostępnione w warstwie SDK Go
* 🚧 `WithPaymentHandler` (X402 płatność na łańcuchu) — w planach, obecnie X402 obsługuje tylko [TypeScript](https://platform.acedata.cloud/documents/x402-typescript-sdk) i [Python](https://platform.acedata.cloud/documents/x402-python-sdk)

## Jak sprawdzić pozostały limit

Można sprawdzić aktualny limit konta przez [konsolę Ace Data Cloud - lista aplikacji](https://platform.acedata.cloud/console/applications).

Można sprawdzić całą historię użycia i szczegóły opłat przez [konsolę Ace Data Cloud - historia użycia](https://platform.acedata.cloud/console/usages).

## Dowiedz się więcej

* 🟦 [`github.com/AceDataCloud/SDK/go` na pkg.go.dev](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)
* 🗂 [Kod źródłowy SDK](https://github.com/AceDataCloud/SDK/tree/main/go)
* 📘 [Przewodnik po integracji SDK TypeScript](https://platform.acedata.cloud/documents/sdk-typescript)
* 🐍 [Przewodnik po integracji SDK Python](https://platform.acedata.cloud/documents/sdk-python)
* 🔌 [SDK + X402 haki płatności](https://platform.acedata.cloud/documents/sdk-x402-payment)


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