Przewodnik po integracji API DeepSeek: Wykonywanie żądań zgodnych z OpenAI przez ECAIX

Ten przewodnik pokazuje, jak przetestować ID modelu DeepSeek przez ECAIX, korzystając z endpointu API zgodnego z OpenAI. Opisuje minimalne działające żądanie, przykłady w Pythonie i curl, weryfikację ID modelu, strumieniowanie, wyjściowe dane w strukturze JSON, narzędzia oraz ścieżkę diagnostyczną dla powszechnych błędów.

Przewodnik opisuje dostęp do ECAIX jako gateway dla modelu wystawionego obecnie w katalogu ECAIX. Nie stwierdza, że ECAIX jest oficjalnym endpointem API DeepSeek ani że wszystkie funkcje DeepSeek są dostępne przez każdą dostępną ścieżkę gatewayu. Sprawdź stronę modelu w czasie rzeczywistym oraz dokumentację dostawcy przed przeniesieniem pracy na produkcję.

Szybki start

Wykonaj tę sekwencję, jeśli już masz aplikację z SDK OpenAI:

1. Otwórz stronę DeepSeek v4.1 Flash model i potwierdź, że ID jest dostępne.
2. Utwórz klucz API ECAIX.
3. Ustaw podstawową URL zgodną z OpenAI na https://ecaix.com/api/ai/v1.
4. Zapewnij, aby SDK i kod aplikacji pozostawały niezmienione, gdzie to możliwe.
5. Wykonaj minimalne żądanie poniżej.
6. Dodaj strumieniowanie, wyjściowe dane w strukturze JSON lub narzędzia dopiero po tym, jak podstawowe żądanie działa poprawnie.

Endpoint i ID modelu

Dla klientów zgodnych z OpenAI użyj:

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

ID modelu nie jest stałym obietnicą w artykule blogowym. Potwierdź je na aktualnej stronie katalogu modeli przed każdą nową integracją lub wdrożeniem. Jeśli potrzebujesz innego modelu z rodziny DeepSeek, kopiuj dokładne ID z strony szczegółów modelu, a nie gadyj o sufixie.

Ważne jest również format endpointu. SDK powinno otrzymać ścieżkę kończącą się na /v1; klient dodaje /chat/completions lub inną ścieżkę operacji. Nie dodawaj /chat/completions do base_url, jeśli SDK już to dodaje.

Python z SDK OpenAI

Zainstaluj lub uaktualnij SDK Python OpenAI w środowisku wirtualnym:

python -m pip install --upgrade openai

Następnie użyj podanej przez ECAIX podstawy URL i klucza API:

const client = new OpenAI({
  apiKey: process.env.ECAIX_API_KEY,
  baseURL: "https://ecaix.com/api/ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

console.log(response.choices[0].message.content);

Użyj kodu serwerowego do wykonania żądania API. Aplikacja przeglądarki powinna wywoływać własny backend, a nie ekspozycjonować klucza ECAIX w kodzie JavaScript klienta.

Diagnoza żądania za pomocą curl

Jeśli SDK nie działa, usuń SDK z równania i przetestuj endpoint bezpośrednio. Zapisuj nagłówki i ciało żądania oddzielnie, aby móc rozróżnić problem HTTP od problemu z formatem odpowiedzi.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

Nie wklej zapisanych nagłówków lub odpowiedzi do publicznego wątku bez usunięcia kluczy API, identyfikatorów żądań, promptów, ścieżek repozytorium i danych klienta.

Diagnoza odpowiedzi

Postępuj zgodnie z poniższym porządkiem:

1. Kod statusu HTTP: ustal, czy żądanie dotarło do poprawnego endpointu.
2. Ciało odpowiedzi: przeczytaj kod błędu dostawcy lub gatewayu.
3. ID modelu: skopiuj dokładne ID z aktualnego katalogu modeli.
4. Autoryzacja: sprawdź nagłówek klucza, konto i uprawnienia.
5. Forma żądania: skróć ciało żądania do model, messages i małego limitu wyjściowego.
6. Pola funkcji: dodaj strumieniowanie, JSON lub narzędzia po kolei.
7. Zachowanie SDK: porównaj żądanie SDK z bezpośrednim żądaniem curl.

To zapobiega problemom z biblioteką klienta bycia mylonym z problemami routingu modelu lub uprawnień konta.

Odpowiedzi w strumieniu

Jeśli aplikacja potrzebuje wyjściowych danych w formacie strumieniowym, dodaj strumieniowanie dopiero po tym, jak standardowe żądanie działa poprawnie:

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Zachowanie zdarzeń dokładnie zależy od endpointu i SDK. Sprawdź, jak Twoje framework obsługuje pusty delta, ostatnie zdarzenie zużycia, przerwanie połączenia i zakończenie w stylu [DONE]. Nie uważaj za gotowe do produkcji implementacji strumieniowej, dopóki nie przetestowałeś przerwania połączenia i ponownego uruchomienia.

Wyjściowe dane w strukturze JSON i JSON

Jeśli potrzebujesz wyjściowych danych w formacie maszyno-czytelnym, zacznij od zwykłego żądania, a następnie dodaj najmniejszą opcję wyjściowych danych w strukturze, która jest wspierana przez endpoint i model. Waliduj zwrócone dane za pomocą prawdziwego parsera JSON. Prompt, który mówi „zwróć JSON”, nie jest taki sam jak odpowiedź z przymusem schematu.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with keys title and priority."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

Czy response_format jest akceptowany może zależeć od modelu i ścieżki. Jeśli endpoint zwraca błąd nieobsługiwanego parametru, usuń pole i sprawdź dokumentację ścieżki przed próbą innego formatu.

Wywoływanie funkcji i narzędzi

Wywoływanie narzędzi wymaga odrębnego testu od generowania tekstu. Zacznij od jednego bezpiecznego narzędzia i sprawdź zwróconą nazwę i argumenty przed wykonaniem czegoś.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

print(response.choices[0].message.tool_calls)

Model może zwrócić poprawną odpowiedź tekstową, podczas gdy wywołanie narzędzi nie działa z powodu konwersji schematu, nieobsługiwanych parametrów lub zachowania klienta. Nigdy nie wykonuj zwróconych argumentów narzędzi w systemie produkcyjnym przed walidacją schematu i dodaniem kontroli uprawnień.

Ścieżki zgodne z OpenAI i Anthropic

ECAIX wystawia różne powierzchnie zgodne dla różnych klientów:

Przeczytaj dokumentację Chat Completions, Odpowiedzi oraz Anthropic Messages przed wyborem ścieżki. To samo ID modelu może nie wystawiać identycznych pól lub zachowań na każdej powierzchni zgodnej.

Szczegóły aktualnych modeli

Użyj stron szczegółowych w czasie rzeczywistym do sprawdzenia możliwości i dostępności:

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Te strony są bardziej niezawodne niż statyczny artykuł dla aktualnych ID modeli, informacji o kontekście i linków do cen.

Powszechne błędy

Walidacja przedprodukcyjna i zarządzanie kluczami API w integracji z DeepSeek API

Podczas integracji z DeepSeek API ważne jest przeprowadzenie dokładnej walidacji przedprodukcyjnej, aby upewnić się, że system działa zgodnie z oczekiwaniami w warunkach rzeczywistych. W tym etapie należy zwrócić szczególną uwagę na bezpieczeństwo, stabilność oraz zgodność z oczekiwaniami biznesowymi.

Klucze API i ich zarządzanie

Klucze API są podstawowym mechanizmem autoryzacji dla każdej interakcji z API. W celu zapewnienia bezpieczeństwa należy:

• Przechowywać klucze w sposób zabezpieczony – unikać ich zapisywania w plikach tekstowych lub w wersjach źródłowych, które mogą być dostępne publicznie. Warto używać środowiskowych zmiennych lub systemów zarządzania kluczami (np. AWS Secrets Manager, HashiCorp Vault).
• Używać unikalnych kluczy dla różnych usług – każda aplikacja lub usługa powinna posiadać własny klucz, aby uniknąć ryzyka nieautoryzowanych dostępów.
• Regularnie aktualizować klucze – w przypadku wykrycia nieprawidłowości lub zmian w polityce bezpieczeństwa, należy natychmiast zmienić klucz API.

Walidacja modeli i identyfikatorów

DeepSeek oferuje różne modele językowe, każdy z własnym identyfikatorem (np. dseek-v1.5, dseek-v2.0). Przed integracją należy:

• Sprawdzić poprawność identyfikatorów modeli – upewnić się, że używane modele są dostępne i zgodne z aktualną dokumentacją API.
• Testować różne wersje modeli – w przypadku ewentualnych zmian w architekturze, warto przetestować nową wersję, aby upewnić się, że nie występują nieprzewidziane zachowania.

Logowanie żądań bez ujawniania danych wrażliwych

Logowanie jest niezbędne do diagnostyki, ale należy unikać zapisywania danych wrażliwych, takich jak klucze API, treści pytania lub odpowiedzi. Warto:

• Filtrować logi – wykluczyć z nich klucze API, adresy IP, oraz inne identyfikatory osobiste.
• Używać formatów logów bez sensownych danych – np. w miejsce {"question": "Jak napisać testy jednostkowe?", "response": "..."} zapisywać tylko {"action": "generate_response", "model": "dseek-v1.5"}.
• Zarządzanie logami – przechowywać je w bezpiecznych magazynach, z możliwością okresowego usuwania starych zapisków.

Retry i idempotencja w żądaniach API

DeepSeek API może czasami generować błędy czasowe (np. przeładowanie serwera). Aby zapewnić nieprzerwany przepływ pracy, należy:

• Wdrażać mechanizmy retry – w przypadku niepowodzenia żądania, warto próbować ponownie po określonym czasie (np. z eksponencjalnym wzrostem odstępu).
• Używać idempotencji – jeśli żądanie może być powtarzane bez skutku (np. generowanie odpowiedzi), należy wdrożyć flagę idempotency_key w żądaniu, aby unikać duplikatów.
• Monitorować statystyki retry – aby zidentyfikować potencjalne problemy w sieci lub serwerze API.

Zarządzanie przerwami strumieniowymi

W przypadku strumieniowych odpowiedzi (np. podczas generowania tekstu) należy:

• Monitorować połączenia – jeśli strumień zostanie przerwany (np. przez awarię sieci), należy zabezpieczyć aplikację przed utraceniem danych.
• Używać mechanizmów reconnect – automatycznie łączyć się z API po przerwaniu