Ez a cikk egy gyakorlati útmutatót ismertet arról, hogyan építsünk multimodális, agent‑alapú RAG (Retrieval‑Augmented Generation) alkalmazást úgy, hogy minden tartalomtípus — szöveg, URL, PDF, kép, hang és videó — egyetlen 768 dimenziós beágyazási térben él. A két kulcselem a Gemini Embedding 2 (minden modalitást ugyanabba a vektor‑térbe ágyaz) és a Google ADK (Agent Development Kit), amely egy kicsi koordinátor‑agentet futtat, hogy a lekért bizonyítékokból hivatkozott, megalapozott választ szintetizáljon.
Miért fontos ez
Amikor források nem csak sima szövegként érkeznek (például termék PDF‑ek, UI képernyőképek, felvételek, demo videók, support jegyzetek), a „jó darabot kiválasztani” problémája gyorsan töredezetté válik: külön‑külön csatornákra és vektor‑tárakra van szükség. A bemutatott megközelítés egyetlen beágyazási térre és egyszeri lekérésre épít, így nem kell három csővezetéket, két vektortárat és egy könnyen törékeny ragasztóréteget karbantartani.
Mit építünk
Egy működő multimodális agent‑alapú RAG demót, ahol tetszőleges fájlt vagy URL‑t feltölthetünk és kérdéseket tehetünk fel az egész indexre. Azonos retrieval‑packet táplálja az választ és a citation panelt is, így a felhasználói felület soha nem kerül ellentmondásba a modellel. Főbb jellemzők:
- Teljesen multimodális index: szöveg, URL, PDF, kép, hang és videó ugyanabban a koszinusz‑similaritás alapú 768‑dimenziós térben.
- Gemini Embedding 2 feladat prefixekkel: külön prefixek dokumentumok és kérdések számára a jobb keresési minőségért.
- Google ADK agent: koordinálja az inspect_embedding_space és retrieve_relevant_context eszközöket, majd lefordítja a lekért kontextust jól megalapozott válasszá.
- Egyetlen lekérés, két fogyasztó: /ask egyszer lekérdez, majd ugyanazt a csomagot továbbadja az agentnek és a UI‑nak.
- 3D PCA vetítési nézet: minden forrás egy pont; kérdés után a lekért források és a lekérdezés ugyanabban a projekcióban világítanak.
- SSRF‑védelem URL beolvasásnál: privát és loopback IP‑eket blokkol, kivéve ha külön engedélyezve van.
Hogyan működik lépésről lépésre
-
Források hozzáadása: szöveg/URL darabolva (chunk), fájlok egyszer feltöltve (PDF/kép/hang/videó). Minden chunk vagy fájl egy Gemini Embedding 2 vektort kap a "task: retrieval document" prefixszel; fájloknál a média vektorát egy cím/megjegyzés szövegvektorral keverik, hogy a cím is javítsa a megtalálhatóságot.
-
Kérdés feltevése: a /ask végpont a lekérdezést beágyazza a "task: question answering | query" prefixszel, kiszámolja a koszinusz‑hasonlóságot minden chunk és a lekérdezés között, forrásonként a legjobb chunkot megtartva kiválasztja a top_k találatot, és ugyanazon komponensekkel 3D PCA vetítést készít.
-
Az agent fut: run_adk_agent per‑kérés agentet épít, melynek retrieve_relevant_context eszköze bezárásként visszaadja az előzőleg számolt retrieval csomagot. Az agent először inspect_embedding_space‑t hív, majd "meghívja" a retrieval eszközt és végül legenerál egy megalapozott választ anélkül, hogy inline citációs azonosítókat illesztene.
-
A frontend renderel: az UI megjeleníti a választ, a citation panelt ugyanazokból a matches adatokból, az agent trace‑et és a frissített 3D nézetet a lekérdezés pontjával és a kiemelt forrásokkal.
A kulcselv az egyszeri‑lekérés szerződés: egy lekérdezés beágyazása, egy rangsorolt találati lista, két fogyasztó (agent és UI). Ez tartja hitelesen a hivatkozásokat.
Főbb implementációs részletek
- Konfigurációs konstansok a példában: EMBED_MODEL = "gemini-embedding-2", DEFAULT_DIMENSIONS = 768, CHUNK_WORDS ≈ 170, CHUNK_OVERLAP ≈ 35, INLINE_MEDIA_LIMIT_BYTES = 18 * 1024 * 1024.
- Szövegbeágyazás task‑prefixekkel: a dokumentumok és kérdések külön prefixet kapnak, ami mérhetően jobb retrievalt ad.
- Fájlok kezelése: kis képek és PDF‑ek inline kerülnek beágyazásra; nagyméretű fájlok, hang és videó a Gemini File API‑n keresztül. A File API feltölti, pollol a SUCCEEDED állapotra, beágyazza és végül törli a feltöltött fájlt, hogy ne szivárogjon a tároló.
- Média és annotáció keverése: a média vektort 68%/32% arányban keverik a cím/notes vektorral, hogy a cím keresési súlya megmaradjon.
- Keresés: minden chunkot pontoznak, de forrásonként csak a legjobb chunk marad meg; a backend tér és a lekérdezés PCA vetítése közösen számolt, így a frontend nem kérdez újra.
- PCA 3D vetítés: egyszerű power‑iteration módszer Pythonban, külső numerikus függőség nélkül.
- Retrieval payload: az agentnek és a frontendnek ugyanaz a struktúrájú csomag kerül továbbításra (provider, matches, citation, source, modality, similarity, evidence), ez biztosítja a következetességet.
ADK agent és a zárt lekérési eszköz
Az ADK agent rövid, két eszközzel (retrieve_relevant_context, inspect_embedding_space) és fókuszált utasítással működik. A szerver closure‑t injektál az agentbe, így az agent úgy használja a retrieval eszközt, mintha újra beágyazna, miközben valójában a már kiszámolt csomagot kapja vissza — ezzel elkerülik a redundáns embedding kört.
FastAPI szerver végepontok
A szerver felülete a következőket adja: /health, /space, /sources/text, /sources/url, /sources/file, DELETE /sources/{id}, és a kritikus POST /ask. A /ask egyszer lekérdez, létrehozza a retrieval_payload‑t, injektálja a closure retrieval_tool‑t az agentbe, futtatja az agentet, és visszaadja a választ, a matches listát, a query_point‑ot, a trace‑et és a teljes space snapshotot.
Biztonsági és működési megfontolások
- SSRF‑védelem: a URL beolvasó validálja a sémát és feloldja a hostname‑t; privát, loopback, link‑local vagy fenntartott IP esetén a beolvasás meghiúsul (AL L O W_PRIVATE_URLS csak indokolt esetben kapcsolható be).
- Blokkoló műveletek threadpoolba kerülnek (run_in_threadpool), hogy a FastAPI eseményciklus válaszképes maradjon.
- CORS konfigurálható környezeti változókból (ALLOWED_ORIGINS), alapértelmezésben a Vite dev szerverre van hangolva.
Rövid frontend leírás
A frontend egy React + Vite alkalmazás, amely három panelt tartalmaz: forráskezelő (szöveg/URL/fájl hozzáadás), Q&A panel (hívja a /ask végpontot, megjeleníti a választ és a citation listát), és egy Three.js alapú 3D embedding nézet, amely a backend által visszaadott PCA koordinátákat használja. Minden forrás egy színezett pont, modalitás szerint kódolva.
Futtatás
A bemutatott példakód backendje a http://localhost:8897 címen hallgat. Indítási lépések röviden:
- Követelmények telepítése: pip install -r requirements.txt
- Környezeti változó: export GOOGLE_API_KEY="your-google-ai-studio-key"
- Backend indítása: python server.py
- Frontend indítása: cd multimodal_agentic_rag/frontend; npm install; npm run dev -- --port 5177
Adjunk hozzá néhány forrást (szöveg, nyilvános URL, PDF, kép), nézzük meg a 3D nézetet, tegyük fel a kérdést a Q&A panelen, és ellenőrizzük a választ, a citation panelt és az agent trace‑et.
Következtetés és továbblépési lehetőségek
A bemutatott megoldás néhány száz sor Pythonban egyetlen, közös Gemini Embedding 2 térre helyezi a multimodális tartalmakat, koszinusz‑alapú keresést hajt végre chunkok felett, és egy szűkített Google ADK agentet használ a hivatkozásokkal alátámasztott válaszokhoz, külön vektortár nélkül. Távolabbi fejlesztési irányok lehetnek: perzisztens vektortár (pgvector, Qdrant, Vertex AI Vector Search), re‑ranking cross‑encoderrel vagy Gemini rerankerrel, háttér ingest folyamattal (Celery/RQ), eval készletek mérésre, többfelhasználós autentikáció és megfigyelhetőség a retrieval csomagok naplózásával.
