Gemini API-ஐ அழைத்து கட்டமைக்கப்பட்ட பதில்களைத் திருப்பும் ஒரு Python செயலியை எழுதுங்கள்

அறிமுகம்

ஒரு Python சேவையை முதல் முறையாக Gemini API-உடன் இணைக்கும்போது, API key-ஐ ஒரு constant-இல் போட்டு, ஒரு request-ஐ உங்கள் route handler-இல் ஒட்டி, ship செய்துவிடுவதற்கான ஆசை வரும். அது ஒருமுறை வேலை செய்யும் — அதை deploy செய்ய வேண்டிய வரை. Hardcode செய்யப்பட்ட secret-கள் containerize செய்த கணமே உடைகின்றன, ad-hoc பிழை கையாளுதல் ஒவ்வொரு Gemini தடுமாற்றத்தையும் ஒரு 500 போலக் காட்டுகிறது, மேலும் ஒவ்வொரு request-க்கும் client-ஐ init செய்வது ஒவ்வொரு அழைப்பிலும் latency-ஐ வீணாக்குகிறது. இந்த ஒழுங்கைத் தவிர்க்கும் குழுக்கள், ஒரு key-ஐ rotate செய்ய image-ஐ மீண்டும் build செய்யும் நிலைக்கும், சீரான பிழை வடிவமே இல்லாத இடைவிடாத தோல்விகளைத் துரத்தும் நிலைக்கும் வந்து சேர்கின்றன.

இந்தப் பாடத்தின் முடிவில், environment variable-களிலிருந்து தனது Gemini உள்ளமைவை ஏற்றும், FastAPI-இன் lifespan hook வழியாக client-ஐ சரியாக ஒருமுறை மட்டும் initialize செய்யும், Gemini API-க்கு prompt-களை அனுப்பும், மற்றும் கணிக்கக்கூடிய பிழைச் சொற்பொருளுடன் கட்டமைக்கப்பட்ட JSON பதில்களைத் திருப்பித் தரும் ஒரு Python பயன்பாட்டை நீங்கள் எழுத முடியும் — அடுத்த பாடத்தில் ஒரு container-இல் போடத் தயாராக.

முக்கிய சொற்கள்

• Gemini API — Gemini குடும்பத்தின் பெரிய மொழி மாதிரிகளுக்கான Google-இன் HTTPS endpoint. இந்தப் பாடத்தின் பயன்பாடு இதற்கு ஒரு prompt-ஐ அனுப்பி உருவாக்கப்பட்ட உரையைத் திருப்பித் தருகிறது; இதன் request/response வடிவத்தை அறிந்திருப்பதே கீழே உள்ள wrapper code-ஐ அர்த்தமுள்ளதாக்குகிறது.
• google-generativeai — Gemini HTTP API-ஐ wrap செய்யும் அதிகாரப்பூர்வ Python SDK; prompt-in / text-out அழைப்புகளுக்காக GenerativeModel.generate_content-ஐ வெளிப்படுத்துகிறது. கீழே உள்ள GeminiClient class இதன் மேல் ஒரு மெல்லிய அடுக்கு.
• FastAPI — வெளிப்புற அழைப்பாளர்கள் Gemini SDK-ஐ நேரடியாகப் பயன்படுத்தாமல் HTTP வழியாக prompt-களைச் சமர்ப்பிக்க, ஒரு /generate endpoint-ஐ வெளிப்படுத்த இங்கே பயன்படுத்தப்படும் async Python web framework.
• Pydantic BaseSettings — Gemini API key, model பெயர் மற்றும் timeout-ஐ environment variable-களிலிருந்து படித்து, தேவையான எந்த மதிப்பும் இல்லாவிட்டால் startup-இலேயே விரைவாகத் தோல்வியடையும் உள்ளமைவு ஏற்றி.
• lifespan context — பயன்பாட்டின் வாழ்நாளைச் சுற்றி setup மற்றும் teardown-ஐ இயக்கும் ஒரு FastAPI hook. ஒவ்வொரு request-இலும் அல்லாமல், startup-இல் ஒருமுறை மட்டும் Gemini client-ஐ உருவாக்க இங்கே பயன்படுத்தப்படுகிறது.

கருத்துகள்

அடுக்கு கட்டமைப்பு

இந்தச் சேவை மூன்று அடுக்குகளாகப் பிரிகிறது, ஒவ்வொன்றுக்கும் அதன் சொந்த உள்ளமைவு பொறுப்பு உள்ளது. FastAPI, HTTP மற்றும் Pydantic validation-ஐக் கையாளுகிறது; ஒரு GeminiClient class, API தொடர்பு மற்றும் பிழை மொழிமாற்றத்தை உடைமையாகக் கொண்டுள்ளது; ஒரு Settings module, environment variable-களிலிருந்து உள்ளமைவை ஏற்றுகிறது. இந்தப் பிரிப்பு secret-ஐ (API key) request கையாளும் logic-இலிருந்து தனிமைப்படுத்துகிறது, மேலும் code-ஐத் தொடாமல் அழைப்பு வடிவத்தை (timeout, max tokens) tune செய்ய அனுமதிக்கிறது.

Validation உள்ளீட்டை நிராகரித்தால் — prompt இல்லாமை, வெற்று string, வரம்பைத் தாண்டிய prompt — எந்த Gemini அழைப்பும் செய்யப்படுவதற்கு முன்பே FastAPI ஒரு 422-ஐத் திருப்பித் தருகிறது, இது quota பயன்பாட்டைக் கணிக்கக்கூடியதாக வைத்திருக்கிறது.

Environment Variable-கள் வழியாக உள்ளமைவு

pydantic_settings-இலிருந்து வரும் BaseSettings, ஒவ்வொரு config field-ஐயும் ஒரு type, ஒரு default மற்றும் எண் வரம்பு validator-களுடன் அறிவிக்கிறது. Startup-இல் இது environment variable-களிலிருந்து உண்மையான மதிப்புகளைப் படிக்கிறது, development-இல் ஒரு .env கோப்பிற்கு fallback ஆகிறது. தேவையான field-கள் ...-ஐ default ஆகப் பயன்படுத்துகின்றன, எனவே GEMINI_API_KEY இல்லாதபோது முதல் request-இல் தெளிவற்ற runtime பிழையை உருவாக்குவதற்குப் பதிலாக startup உடனடியாகத் தோல்வியடைகிறது. (Code Walkthrough பார்க்கவும்.)

Lifespan-ஆல் நிர்வகிக்கப்படும் Client Initialization

FastAPI-இன் lifespan async context manager, பயன்பாட்டின் வாழ்நாளைச் சுற்றி ஒருமுறை இயங்குகிறது. எடுத்துக்காட்டு இதைப் பயன்படுத்தி ஒரு GeminiClient-ஐ உருவாக்கி app.state-இல் சேமிக்கிறது. ஒவ்வொரு request-ம் ஒவ்வொரு அழைப்பிலும் மீண்டும் initialize செய்வதற்குப் பதிலாக அந்த client-ஐயும் — SDK-இன் அடிப்படை connection pool-ஐயும் — மீண்டும் பயன்படுத்துகிறது. இதன் பொருள், credential தோல்விகள் பயனர் traffic-இன் போது அல்லாமல் startup-இலேயே வெளிப்படும்.

எல்லையில் பிழை மொழிமாற்றம்

Gemini SDK, network timeout-கள், auth தோல்விகள் மற்றும் rate limit-களில் throw செய்யக்கூடும். generate method அழைப்பை try/except-இல் wrap செய்து HTTPException(502) ஆக மீண்டும் raise செய்கிறது, ஒவ்வொரு SDK தோல்வி முறையையும் ஒரே கணிக்கக்கூடிய HTTP பதிலுக்கு map செய்கிறது. Gemini எந்த part-ம் இல்லாத ஒரு பதிலைத் திருப்பித் தரும் நிலையை (பொதுவாக safety-filter செய்யப்பட்ட வெளியீடு) ஒரு தனி guard கையாண்டு, SDK-இன் தெளிவற்ற ValueError-க்குப் பதிலாக தெளிவான செய்தியுடன் அதே 502-ஐ உருவாக்குகிறது.

Code Walkthrough

இந்த walkthrough நான்கு கருத்துகளையும் ஒன்றாக விளக்குகிறது: BaseSettings வழியாக environment-ஆல் இயக்கப்படும் உள்ளமைவு, lifespan-ஆல் bootstrap செய்யப்பட்ட client initialization, request validation, மற்றும் எல்லையில் பிழை மொழிமாற்றம். முதல் snippet Settings-ஐ அறிவிக்கிறது; இரண்டாவது அதை ஒரு GeminiClient-உடன் ஒரு FastAPI பயன்பாட்டில் இணைக்கிறது.

Code snippetpython
1# settings.py
2from functools import lru_cache
3
4from pydantic import Field
5from pydantic_settings import BaseSettings, SettingsConfigDict
6
7class Settings(BaseSettings):
8    model_config = SettingsConfigDict(env_file=".env", case_sensitive=False)
9
10    gemini_api_key: str = Field(..., description="API key for Gemini")
11    gemini_model: str = Field(default="gemini-1.5-flash")
12    request_timeout: int = Field(default=30, ge=5, le=120)
13    max_output_tokens: int = Field(default=1024, ge=1, le=8192)
14    temperature: float = Field(default=0.7, ge=0.0, le=2.0)
15
16@lru_cache
17def get_settings() -> Settings:
18    return Settings()

gemini_api_key தனது default ஆக ...-ஐப் பயன்படுத்துகிறது, இது அதைத் தேவையானதாக்குகிறது — GEMINI_API_KEY set செய்யப்படாவிட்டால் பயன்பாடு startup-இலேயே விரைவாகத் தோல்வியடைகிறது. ge/le validator-கள் தவறான எண் மதிப்புகள் Gemini-ஐ அடைவதற்கு முன்பே தடுக்கின்றன. @lru_cache, process முழுவதும் ஒரே பகிரப்பட்ட Settings instance-ஐ உறுதி செய்கிறது.

Code snippetpython
1# main.py
2from contextlib import asynccontextmanager
3
4import google.generativeai as genai
5from fastapi import FastAPI, HTTPException
6from pydantic import BaseModel, Field
7
8from settings import get_settings
9
10class PromptRequest(BaseModel):
11    prompt: str = Field(..., min_length=1, max_length=10000)
12    temperature: float | None = Field(default=None, ge=0.0, le=2.0)
13
14class GeminiClient:
15    def __init__(self, settings):
16        genai.configure(api_key=settings.gemini_api_key)
17        self._model = genai.GenerativeModel(settings.gemini_model)
18        self._settings = settings
19
20    def generate(self, prompt: str, temperature: float | None = None) -> dict:
21        config = genai.types.GenerationConfig(
22            max_output_tokens=self._settings.max_output_tokens,
23            temperature=temperature or self._settings.temperature,
24        )
25        try:
26            response = self._model.generate_content(
27                prompt,
28                generation_config=config,
29                request_options={"timeout": self._settings.request_timeout},
30            )
31        except Exception as exc:
32            raise HTTPException(status_code=502, detail=str(exc)) from exc
33
34        if not response.parts:
35            raise HTTPException(status_code=502, detail="Empty response from Gemini")
36
37        return {
38            "model": self._settings.gemini_model,
39            "prompt": prompt,
40            "generated_text": response.text,
41        }
42
43@asynccontextmanager
44async def lifespan(app: FastAPI):
45    app.state.client = GeminiClient(get_settings())
46    yield
47
48app = FastAPI(title="Gemini LLM Service", lifespan=lifespan)
49
50@app.post("/generate")
51async def generate_text(request: PromptRequest):
52    return app.state.client.generate(
53        prompt=request.prompt,
54        temperature=request.temperature,
55    )
56
57@app.get("/health")
58async def health_check():
59    return {"status": "healthy"}

PromptRequest விளிம்பிலேயே 1 முதல் 10,000 எழுத்துகள் வரையான prompt-ஐக் கட்டாயப்படுத்துகிறது, எனவே வெற்று அல்லது அளவு மீறிய request ஒருபோதும் Gemini-ஐ அடையாது. lifespan context, startup-இல் ஒருமுறை GeminiClient-ஐ உருவாக்கி app.state-இல் சேமிக்கிறது. generate-இன் உள்ளே, try/except எந்த SDK exception-ஐயும் HTTP 502 ஆக மொழிமாற்றம் செய்கிறது, மேலும் response.parts சோதனை, .text raise செய்வதற்கு முன்பே safety-filter செய்யப்பட்ட நிலையைப் பிடிக்கிறது. /health endpoint, Gemini-ஐ அழைக்காமலே திரும்புகிறது, இது container probe-களுக்கு ஒரு மலிவான இலக்கைத் தருகிறது.

GEMINI_API_KEY-ஐ export செய்து uvicorn main:app --reload-ஐ இயக்கிய பின், Content-Type: application/json மற்றும் body {"prompt":"Say hello in one short sentence."} உடன் http://localhost:8000/generate-க்கு ஒரு POST, வெற்றல்லாத generated_text field உடன் ஒரு 200-ஐத் திருப்பித் தந்தால், அது வேலை செய்கிறது என்பதை நீங்கள் அறிவீர்கள்.

-க்கான நடைமுறையில்

மேலே உள்ள முறை — environment-ஆல் இயக்கப்படும் config, lifespan-ஆல் bootstrap செய்யப்பட்ட client, விளிம்பில் validation, எல்லையில் பிழை மொழிமாற்றம் — Gemini-ஆல் ஆதரிக்கப்படும் எந்த Python சேவைக்கும் பொருந்தும். அதை எப்படி விரிவுபடுத்துவது என்பது நீங்கள் எந்தப் பணிக்காகக் கட்டமைக்கிறீர்கள் என்பதைப் பொறுத்தது.

செய்ய வேண்டியவை மற்றும் செய்யக்கூடாதவை

செய்ய வேண்டியவை

1. API key-ஐ ஒரு environment variable-இலிருந்து ஏற்றுங்கள் — secret-ஐ source control-க்கு வெளியே வைத்து, image-ஐ மீண்டும் build செய்யாமல் ஒவ்வொரு environment-க்கும் key-களை மாற்ற அனுமதிக்கிறது.
2. Gemini client-ஐ lifespan hook-இல் ஒருமுறை மட்டும் initialize செய்யுங்கள் — SDK-இன் connection pool-ஐ மீண்டும் பயன்படுத்துகிறது, மேலும் credential தோல்விகளை traffic-இன் நடுவில் அல்லாமல் startup-இலேயே வெளிப்படுத்துகிறது.
3. SDK exception-களை HTTP 502 ஆக மொழிமாற்றம் செய்யுங்கள் — அடிப்படைப் பிரச்சினை timeout, auth தோல்வி அல்லது rate limit எதுவாக இருந்தாலும், அழைப்பாளர்களுக்கு ஒரே கணிக்கக்கூடிய தோல்வி முறையைத் தருகிறது.

செய்யக்கூடாதவை

1. API key அல்லது model பெயரை hardcode செய்யாதீர்கள் — ஒவ்வொரு environment மாற்றமும் ஒரு image rebuild ஆகிவிடும், மேலும் leak ஆன image, production credential-களை leak செய்யும்.
2. முதலில் response.parts-ஐச் சோதிக்காமல் response.text-ஐ அழைக்காதீர்கள் — safety-filter செய்யப்பட்ட Gemini பதில் part-கள் இல்லாத ஒரு செல்லுபடியான object ஆகும், மேலும் .text ஒரு தெளிவற்ற ValueError-ஐ raise செய்யும்.
3. Liveness probe-களுக்கு /generate endpoint-ஐ மீண்டும் பயன்படுத்தாதீர்கள் — ஒவ்வொரு probe-ம் Gemini quota-வை வீணாக்குகிறது; API-ஐ அழைக்காமல் திரும்பும் ஒரு தனி /health route-ஐ வெளிப்படுத்துங்கள்.