Kjo faqe është përkthyer nga Cloud Translation API.

Integrimet e partnerëve dhe bibliotekave

Ky udhëzues përshkruan strategjitë arkitekturore për ndërtimin e bibliotekave, platformave dhe portave në krye të Gemini API. Ai detajon kompromiset teknike midis përdorimit të SDK-ve zyrtare të GenAI, Direct API (REST/gRPC) dhe shtresës së përputhshmërisë OpenAI.

Përdoreni këtë udhëzues nëse po ndërtoni mjete për zhvillues të tjerë, të tilla si korniza me burim të hapur, porta hyrëse për ndërmarrje ose agregues SaaS, dhe duhet të optimizoni për higjienën e varësisë, madhësinë e paketës ose barazinë e veçorive.

Çfarë është integrimi i partnerëve?

Një partner është kushdo që ndërton një integrim midis Gemini API dhe zhvilluesve të përdoruesve fundorë. Ne i kategorizojmë partnerët në katër arketipe. Identifikimi i atij që ju përshtatet më shumë do t'ju ndihmojë të zgjidhni rrugën e duhur të integrimit.

Korniza e ekosistemit

Kush jeni ju: Mirëmbajtës i një kuadri me burim të hapur (p.sh., LangChain, LlamaIndex, Spring AI) ose klientëve specifikë të gjuhës.
Qëllimi juaj: Përputhshmëri e gjerë. Ju dëshironi që biblioteka juaj të funksionojë në çdo mjedis që zgjedh përdoruesi juaj pa shkaktuar konflikte.

Platforma Runtime dhe Edge

Kush jeni ju: Platformat SaaS, AI Gateways ose ofruesit e infrastrukturës cloud (p.sh., Vercel, Cloudflare, Zapier) ku ekzekutimi i kodit ndodh në mjedise të kufizuara.
Qëllimi juaj: Performanca. Ju nevojitet vonesë e ulët, madhësi minimale e paketës dhe nisje të shpejta të ftohta.

Agregues

Kush jeni ju: Platforma, proksi ose "Kopshte Model" të brendshme që normalizojnë aksesin në shumë ofrues të ndryshëm të LLM (p.sh. OpenAI, Anthropic, Google) në një ndërfaqe të vetme.
Qëllimi juaj: Transportueshmëri dhe uniformitet.

Porta e Ndërmarrjes

Kush jeni ju: Ekipet e Inxhinierisë së Platformës së Brendshme në kompani të mëdha që ndërtojnë "Shtigje të Arta" për qindra zhvillues të brendshëm.
Qëllimi juaj: Standardizimi, qeverisja dhe autentifikimi i unifikuar.

Krahasimi në një shikim

Praktika më e mirë globale: Të gjithë partnerët duhet të dërgojnë kokën x-goog-api-client pavarësisht nga rruga e zgjedhur.

Nëse je...	Shtegu i rekomanduar	Përfitimi kryesor	Kompromisi kryesor	Praktika më e mirë
Porta e ndërmarrjes, korniza e ekosistemit	SDK e Google GenAI	Pariteti dhe shpejtësia e verteksit. Trajtimi i integruar për llojet, autorizimin dhe veçoritë komplekse (p.sh., ngarkimet e skedarëve). Migrim pa probleme në Google Cloud.	Pesha e varësisë. Varësitë kalimtare mund të jenë komplekse dhe jashtë kontrollit tuaj. I kufizuar në gjuhët e mbështetura (Python/Node/Go/Java).	Kyç versionet. Ngjit versionet e SDK-së në imazhet bazë të brendshme për të siguruar stabilitet në të gjitha ekipet.
Korniza e ekosistemit, platformat e skajit dhe agreguesit	API i drejtpërdrejtë (REST / gRPC)	Pa varësi. Ju kontrolloni klientin HTTP dhe madhësinë e saktë të paketës. Qasje e plotë në të gjitha veçoritë e API-t dhe modelit.	Mbingarkesë e lartë për zhvilluesit. Strukturat JSON mund të jenë të ndërthurura thellë dhe kërkojnë validim të rreptë manual dhe kontroll të tipit.	Përdorni specifikimet OpenAPI. Automatizoni gjenerimin e llojeve duke përdorur specifikimet tona zyrtare në vend që t'i shkruani ato me dorë.
Agregues që përdor SDK-të OpenAI që kërkojnë vetëm rrjedha pune të bazuara në tekst (Optimizimi për portabilitet të trashëguar)	Pajtueshmëria me OpenAI	Transportueshmëri e menjëhershme. Ripërdorni kodin ose bibliotekat ekzistuese të pajtueshme me OpenAI.	Kufiri i veçorive. Karakteristikat specifike të modelit (video native, Caching) mund të mos jenë të disponueshme.	Plani i migrimit. Përdoreni këtë për validim të shpejtë, por planifikoni të përmirësoni në Direct API për funksionin e plotë të API-t.

Integrimi i SDK-së së Google GenAI

Për framework-et, zbatimi i Google GenAI SDK është shpesh rruga më e thjeshtë, duke pasur parasysh numrin më të vogël të rreshtave të kodit në gjuhët e mbështetura.

Për ekipet e platformave të brendshme, rezultati kryesor i dorëzimit është shpesh një "rrugë e artë" që u lejon inxhinierëve të produkteve të veprojnë shpejt, duke respektuar njëkohësisht politikat e sigurisë.

Përfitimet:

Ndërfaqe e unifikuar për migrimin e Vertex AI: Zhvilluesit e brendshëm shpesh krijojnë prototipa duke përdorur Çelësat API (Gemini API) dhe i vendosin në Vertex AI (IAM) për pajtueshmëri me prodhimin. SDK i abstrakton këto ndryshime të vërtetimit. Në mënyrë të ngjashme për kornizat, ju mund të implementoni një shteg kodi dhe të mbështesni dy grupe përdoruesish.
Ndihmës nga ana e klientit: SDK përfshin shërbime idiomatike që zvogëlojnë funksionimin standard për detyra komplekse.
- Shembuj: Mbështetja e objekteve të imazhit PIL direkt në kërkesa, thirrja automatike e funksioneve dhe llojet gjithëpërfshirëse.
Qasje në veçoritë që nga dita zero: Karakteristikat e reja të API-t janë të disponueshme në kohën e lançimit përmes SDK-ve.
Mbështetje e përmirësuar për gjenerimin e kodit: Instalimi i SDK-së lokale ekspozon përkufizimet e tipit dhe docstrings ndaj asistentëve të kodimit (p.sh., Cursor, Copilot). Ky kontekst përmirëson saktësinë e gjenerimit të kodit krahasuar me gjenerimin e kërkesave të papërpunuara REST.

Kompromisi:

Pesha dhe kompleksiteti i varësisë: SDK-të kanë varësitë e tyre, të cilat mund të rrisin madhësinë e paketës dhe potencialisht rrezikun e zinxhirit të furnizimit.
Versionimi: Karakteristikat e reja të API-t shpesh fiksohen në versionet minimale të SDK-së. Mund t'ju duhet të shtyni përditësime për përdoruesit për të aksesuar karakteristika ose modele të reja, të cilat në disa raste mund të kërkojnë ndryshime në varësitë kalimtare që ndikojnë te përdoruesit tuaj.
Kufizimet e protokollit: SDK-të mbështesin vetëm HTTPS për API-në kryesore dhe WebSockets (WSS) për API-në Live. gRPC nuk mbështetet duke përdorur klientët SDK të nivelit të lartë.
Mbështetje gjuhësore: SDK-të mbështesin versionet aktuale të gjuhëve. Nëse keni nevojë të mbështesni versionet EOL (p.sh., Python 3.9), do t'ju duhet të mirëmbani një degëzim.

Praktika më e mirë:

Kyç versionet: Ngjit versionin e SDK-së në imazhet bazë të brendshme për të siguruar stabilitet në të gjitha ekipet.

Integrim i drejtpërdrejtë i API-t

Nëse po shpërndani një bibliotekë për mijëra zhvillues, po ekzekutoni në një mjedis të kufizuar ose po ndërtoni një agregator që kërkon veçoritë më të përparuara të Gemini, mund t'ju duhet të integroheni direkt me API-n duke përdorur REST ose gRPC.

Përfitimet:

Qasje e plotë në funksione: Ndryshe nga shtresa e përputhshmërisë OpenAI, përdorimi i API-t aktivizon drejtpërdrejt funksionet specifike të Gemini, të tilla si ngarkimi në File API, krijimi i ruajtjes së përmbajtjes në memorje dhe përdorimi i Live API-t dypalësh.
Varësi minimale: Në një mjedis ku varësitë janë të ndjeshme për shkak të madhësisë ose kostove të auditimit. Përdorimi i API-t direkt përmes një biblioteke standarde si fetch ose përmes një mbështjellësi si httpx siguron që biblioteka juaj të mbetet e lehtë.
Agnostik ndaj gjuhës: Kjo është e vetmja rrugë për gjuhët që nuk mbulohen nga SDK-të, të tilla si Rust, PHP dhe Ruby, pasi nuk ka kufizime gjuhësore.
Performanca: API-ja Direct nuk ka kosto inicializimi, duke minimizuar nisjet e ftohta në funksionet pa server.

Kompromisi:

Implementimi manual i Vertex AI: Ndryshe nga SDK, përdorimi direkt i API-t nuk i trajton automatikisht ndryshimet e vërtetimit midis AI Studio (Çelësi API) dhe Vertex AI (IAM). Duhet të implementoni trajtues të veçantë të autorizimit nëse doni të mbështetni të dy mjediset.
Pa lloje ose ndihmës vendas: Nuk merrni përfundime kodi ose kontrolle në kohën e kompajlimit për objektet e kërkesës, përveç nëse i zbatoni vetë. Nuk ka "ndihmës" të klientit (p.sh., konvertues funksioni-në-skemë), kështu që duhet ta shkruani manualisht vetë këtë logjikë.

Praktika më e mirë

Ne ekspozojmë një specifikim të lexueshëm nga makina që mund ta përdorni për të gjeneruar përkufizime tipesh për bibliotekën tuaj, duke ju kursyer shkrimin e tyre me dorë. Shkarkoni specifikimin gjatë procesit të ndërtimit, gjeneroni tipet dhe dërgoni kodin e kompiluar.

Pika përfundimtare: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

Integrimi i OpenAI SDK

Nëse jeni një platformë që i jep përparësi një skeme të unifikuar (Përfundimet e Chat-it OpenAI) mbi veçoritë specifike të modelit, kjo është rruga juaj më e shpejtë.

Përfitimet:

Fërkim i ulët: Shpesh mund të shtoni mbështetje për Gemini duke ndryshuar baseURL dhe apiKey . Kjo është një mënyrë e shpejtë për të integruar implementimet "Bring Your Own Key", duke shtuar mbështetje për Gemini pa shkruar kod të ri.
Kufizime: Kjo rrugë rekomandohet vetëm nëse jeni i kufizuar në OpenAI SDK dhe nuk keni nevojë për veçori të përparuara Gemini si File API, ose shtimin manual të mbështetjes për mjete si Grounding me Google Search.

Kompromisi:

Kufizimet e veçorive: Shtresa e përputhshmërisë ofron kufizime për aftësitë kryesore të Gemini. Mjetet e disponueshme në anën e serverit ndryshojnë midis platformave dhe mund të kërkojnë trajtim manual për të funksionuar me mjetet e Gemini API.
Mbivendosja e përkthimit: Meqenëse skema OpenAI nuk përputhet 1:1 me arkitekturën e Gemini, mbështetja në shtresën e përputhshmërisë sjell disa kompleksitete që kërkojnë punë shtesë zbatimi për t'u zgjidhur, siç është përputhja e një mjeti "kërkimi" të përdoruesit me mjetin e duhur të platformës. Nëse keni nevojë për një sasi të konsiderueshme të kornizës speciale, mund të jetë më e vlefshme të përdorni një SDK ose API të dedikuar për secilën platformë.

Praktika më e mirë

Kur është e mundur, integrojeni direkt me Gemini API. Megjithatë, për përputhshmëri maksimale, merrni në konsideratë përdorimin e një biblioteke që është në dijeni të ofruesve të ndryshëm dhe mund të trajtojë hartëzimin e mjeteve dhe mesazheve për ju.

Praktika më e mirë për të gjithë partnerët: identifikimi i klientit

Kur bëni thirrje në Gemini API si platformë ose bibliotekë, duhet ta identifikoni klientin tuaj duke përdorur kokën x-goog-api-client .

Kjo i lejon Google-it të identifikojë segmentet tuaja specifike të trafikut dhe, nëse biblioteka juaj po prodhon një model specifik gabimi, ne mund të kontaktojmë për të ndihmuar në korrigjimin e tij.

Përdorni formatin company-product/version (p.sh., acme-framework/1.2.0 ).

Shembuj zbatimi

SDK i GenAI

Duke ofruar klientin API, SDK-ja i shton automatikisht kokën tuaj të personalizuar kokave të saj të brendshme.

from google import genai

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

API i Drejtpërdrejtë (REST)

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 '{...}'

SDK i OpenAI

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",
    }
)

Hapat e ardhshëm

Vizitoni përmbledhjen e bibliotekës për të mësuar rreth SDK-ve GenAI
Shfletoni referencën e API-t
Lexoni udhëzuesin e përputhshmërisë së OpenAI