Integracje z partnerami i bibliotekami

Ten przewodnik zawiera strategie architektoniczne dotyczące tworzenia bibliotek, platform i bram na podstawie Gemini API. Opisuje kompromisy techniczne między korzystaniem z oficjalnych pakietów SDK GenAI, interfejsu Direct API (REST/gRPC) i warstwy zgodności z OpenAI.

Skorzystaj z tego przewodnika, jeśli tworzysz narzędzia dla innych programistów, takie jak platformy open source, bramy dla przedsiębiorstw lub agregatory SaaS, i musisz zoptymalizować je pod kątem czystości zależności, rozmiaru pakietu lub równoważności funkcji.

Co to jest integracja z partnerem?

Partner to każda osoba, która tworzy integrację między interfejsem Gemini API a programistami będącymi użytkownikami końcowymi. Dzielimy partnerów na 4 archetypy. Określenie, do którego z nich pasujesz najbardziej, pomoże Ci wybrać odpowiednią ścieżkę integracji.

Platforma ekosystemu

• Kim jesteś: opiekunem platformy open source (np. LangChain, LlamaIndex, Spring AI) lub klientów w określonym języku.
• Cel: szeroki zakres zgodności. Chcesz, aby Twoja biblioteka działała w dowolnym środowisku wybranym przez użytkownika bez powodowania konfliktów.

Środowisko wykonawcze i platforma brzegowa

• Kim jesteś: platformy SaaS, bramy AI lub dostawcy infrastruktury chmurowej (np. Vercel, Cloudflare, Zapier), w których wykonywanie kodu odbywa się w ograniczonych środowiskach.
• Twój cel: skuteczność. Potrzebujesz małego opóźnienia, minimalnego rozmiaru pakietu i szybkiego uruchamiania „na zimno”.

Właściciel witryny

• Kim jesteś: platformy, serwery proxy lub wewnętrzne „Model Gardens”, które normalizują dostęp do wielu różnych dostawców LLM (np. OpenAI, Anthropic, Google) w jednym interfejsie.
• Cel: przenośność i jednolitość.

Brama Enterprise

• Kim jesteś: wewnętrzne zespoły inżynierów platformy w dużych firmach, które tworzą „złote ścieżki” dla setek wewnętrznych programistów.
• Twój cel: standaryzacja, zarządzanie i ujednolicone uwierzytelnianie.

Krótkie porównanie

Sprawdzona metoda na całym świecie: wszyscy partnerzy muszą wysyłać x-goog-api-clientnagłówek niezależnie od wybranej ścieżki.

Integracja pakietu Google GenAI SDK

W przypadku platform najprostszym rozwiązaniem jest często wdrożenie pakietu Google GenAI SDK, ponieważ wymaga on najmniejszej liczby wierszy kodu w obsługiwanych językach.

W przypadku wewnętrznych zespołów platformy głównym produktem jest często „złota ścieżka”, która umożliwia inżynierom produktów szybkie działanie przy jednoczesnym zachowaniu zgodności z zasadami bezpieczeństwa.

Korzyści:

• Ujednolicony interfejs do migracji Vertex AI: deweloperzy wewnętrzni często tworzą prototypy za pomocą kluczy API (Gemini API) i wdrażają je w Vertex AI (IAM) w celu zapewnienia zgodności z wymaganiami produkcyjnymi. Pakiet SDK ukrywa te różnice w uwierzytelnianiu. Podobnie w przypadku platform możesz wdrożyć jedną ścieżkę kodu i obsługiwać 2 grupy użytkowników.
• Pomocnicze funkcje po stronie klienta: pakiet SDK zawiera idiomatyczne narzędzia, które zmniejszają ilość kodu szablonowego w przypadku złożonych zadań.
  • Przykłady: obsługa PIL obiektów obrazu bezpośrednio w promptach, automatyczne wywoływanie funkcji i kompleksowe typy.
• Dostęp do funkcji od pierwszego dnia: nowe funkcje interfejsu API są dostępne od momentu wprowadzenia na rynek za pomocą pakietów SDK.
• Ulepszona obsługa generowania kodu: lokalna instalacja pakietu SDK udostępnia definicje typów i ciągi dokumentacyjne asystentom kodowania (np. Cursor, Copilot). Ten kontekst zwiększa dokładność generowania kodu w porównaniu z generowaniem surowych żądań REST.

Kompromis:

• Waga i złożoność zależności: pakiety SDK mają własne zależności, które mogą zwiększać rozmiar pakietu i potencjalnie ryzyko związane z łańcuchem dostaw.
• Wersjonowanie: nowe funkcje interfejsu API są często powiązane z minimalnymi wersjami pakietu SDK. Aby uzyskać dostęp do nowych funkcji lub modeli, może być konieczne przesłanie aktualizacji do użytkowników. W niektórych przypadkach może to wymagać zmian w zależnościach przechodnich, które mają wpływ na użytkowników.
• Limity protokołu: pakiety SDK obsługują tylko protokół HTTPS w przypadku głównego interfejsu API i protokół WebSocket (WSS) w przypadku interfejsu Live API. gRPC nie jest obsługiwany w przypadku klientów pakietu SDK wysokiego poziomu.
• Obsługa języków: pakiety SDK obsługują aktualne wersje językowe. Jeśli musisz obsługiwać wersje, których okres wsparcia dobiegł końca (np. Python 3.9), musisz utrzymywać fork.

Sprawdzona metoda:

• Blokowanie wersji: przypinaj wersję pakietu SDK w wewnętrznych obrazach bazowych, aby zapewnić stabilność w różnych zespołach.

Bezpośrednia integracja interfejsu API

Jeśli rozpowszechniasz bibliotekę wśród tysięcy deweloperów, działasz w ograniczonym środowisku lub tworzysz agregator, który wymaga najnowszych funkcji Gemini, możesz potrzebować bezpośredniej integracji z interfejsem API za pomocą REST lub gRPC.

Korzyści:

• Pełny dostęp do funkcji: w przeciwieństwie do warstwy zgodności z OpenAI bezpośrednie korzystanie z interfejsu API umożliwia korzystanie z funkcji specyficznych dla Gemini, takich jak przesyłanie do interfejsu File API, tworzenie pamięci podręcznej treści i korzystanie z dwukierunkowego interfejsu Live API.
• Minimalne zależności: w środowisku, w którym zależności są wrażliwe ze względu na rozmiar lub koszty audytu. Korzystanie z interfejsu API bezpośrednio za pomocą biblioteki standardowej, np. fetch, lub za pomocą otoki, np. httpx, zapewnia, że biblioteka pozostanie lekka.
• Niezależne od języka: to jedyna ścieżka dla języków nieobsługiwanych przez pakiety SDK, takich jak Rust, PHP i Ruby, ponieważ nie ma ograniczeń dotyczących języka.
• Wydajność: interfejs Direct API nie wymaga inicjowania, co minimalizuje zimne starty w funkcjach bezserwerowych.

Kompromis:

• Ręczna implementacja Vertex AI: w przeciwieństwie do pakietu SDK bezpośrednie korzystanie z interfejsu API nie obsługuje automatycznie różnic w uwierzytelnianiu między AI Studio (klucz interfejsu API) a Vertex AI (IAM). Jeśli chcesz obsługiwać oba środowiska, musisz wdrożyć osobne moduły obsługi autoryzacji.
• Brak typów natywnych i funkcji pomocniczych: nie otrzymujesz uzupełnień kodu ani sprawdzania obiektów żądań w czasie kompilacji, chyba że zaimplementujesz je samodzielnie. Nie ma „pomocników” klienta (np. konwerterów funkcji na schematy), więc musisz samodzielnie napisać tę logikę.

Sprawdzona metoda

Udostępniamy specyfikację w formacie czytelnym dla maszyn, której możesz użyć do wygenerowania definicji typów dla swojej biblioteki, dzięki czemu nie musisz ich pisać ręcznie. Pobierz specyfikację podczas procesu kompilacji, wygeneruj typy i dostarcz skompilowany kod.

• Punkt końcowy: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

Integracja pakietu OpenAI SDK

Jeśli jesteś platformą, która stawia na ujednolicony schemat (OpenAI Chat Completions) zamiast na funkcje specyficzne dla modelu, jest to najszybsza droga.

Korzyści:

• Łatwość wdrożenia: często możesz dodać obsługę Gemini, zmieniając baseURLi apiKey. To szybki sposób na integrację implementacji „Bring Your Own Key” (BYOK), który umożliwia dodanie obsługi Gemini bez pisania nowego kodu.
• Ograniczenia: ta ścieżka jest zalecana tylko wtedy, gdy możesz korzystać tylko z pakietu OpenAI SDK i nie potrzebujesz zaawansowanych funkcji Gemini, takich jak interfejs File API, ani ręcznego dodawania obsługi narzędzi takich jak grounding z użyciem wyszukiwarki Google.

Kompromis:

• Ograniczenia funkcji: warstwa zgodności ogranicza podstawowe możliwości Gemini. Dostępne narzędzia po stronie serwera różnią się w zależności od platformy i mogą wymagać ręcznej obsługi, aby współpracować z narzędziami interfejsu Gemini API.
• Dodatkowe koszty tłumaczenia: ponieważ schemat OpenAI nie jest w pełni zgodny z architekturą Gemini, korzystanie z warstwy zgodności wiąże się z pewnymi komplikacjami, które wymagają dodatkowych prac wdrożeniowych, np. mapowania narzędzia „wyszukiwanie” użytkownika na odpowiednie narzędzie platformy. Jeśli potrzebujesz znacznej liczby wyjątków, bardziej opłaca się używać osobnego pakietu SDK lub interfejsu API dla każdej platformy.

Sprawdzona metoda

W miarę możliwości integruj się bezpośrednio z Gemini API. Aby jednak zapewnić maksymalną zgodność, warto użyć biblioteki, która rozpoznaje różnych dostawców i może obsługiwać mapowanie narzędzi i wiadomości.

Sprawdzone metody dla wszystkich partnerów: identyfikacja klienta

Podczas wywoływania interfejsu Gemini API jako platforma lub biblioteka musisz identyfikować klienta za pomocą nagłówka x-goog-api-client.

Dzięki temu Google może identyfikować konkretne segmenty ruchu, a jeśli Twoja biblioteka generuje określony wzorzec błędów, możemy się z Tobą skontaktować, aby pomóc w debugowaniu.

Użyj formatu company-product/version (np. acme-framework/1.2.0).

Przykłady implementacji

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

Dalsze kroki

• Aby dowiedzieć się więcej o pakietach SDK GenAI, zapoznaj się z przeglądem bibliotek.
• Przejrzyj dokumentację API
• Przeczytaj przewodnik po zgodności z OpenAI