Azure AI-Keresés REST API-referencia

  • Cikk

Az Azure AI Keresés (korábbi nevén Azure Cognitive Search) egy teljes körűen felügyelt felhőalapú keresési szolgáltatás, amely a felhasználó tulajdonában lévő tartalmakon keresztül biztosít információt.

Az adatsík REST API-jait indexelési és lekérdezési munkafolyamatokhoz használjuk, és ezeket ebben a szakaszban dokumentáljuk.

A vezérlősík műveleteit egy külön felügyeleti REST API-val érheti el.

Verziószámozott API-dokumentumok

A REST API-dokumentumok már verziószámozottak. Amikor megnyit egy API-referencialapot, egy verzióválasztó jelenik meg a tartalomjegyzék felett. Győződjön meg arról, hogy az API-referencia a Referencia > adatsík mappából származik.

Képernyőkép a verzióválasztóról.

Fő fogalmak

Az Azure AI Keresés a keresési szolgáltatások, az indexek, a dokumentumok, az indexelők, az adatforrások, a képességcsoportok és a szinonimák leképezéseinek fogalmait tartalmazza.

  • A keresési szolgáltatás az indexeket, az indexelőket, az adatforrásokat, a képességcsoportokat és a szinonimákat legfelső szintű objektumokként tárolja.
  • A keresési index a keresési dokumentumok állandó tárolását biztosítja. Keresés dokumentumok a mezők gyűjteményeként tagolt, külső forrásokból betöltött és indexbe leküldett adatok, hogy kereshetővé tegyék őket.
  • A keresési indexelő automatizálja az adatokat natív formátumban, és szerializálja azokat JSON-ra.
  • Az indexelő rendelkezik adatforrással, és egy indexre mutat.
  • Az indexelők olyan képességcsoportokkal is rendelkezhetnek, amelyek AI-bővítést és integrált vektorizációt adnak hozzá az indexelési folyamathoz. A képességcsoportok mindig indexelőhöz vannak csatolva. Gépi tanulást indítanak a szöveg kinyeréséhez vagy darabolásához, a tartalom vektorizálásához, a funkciók kikövetkeztetéséhez vagy a tartalom szerkezetének hozzáadásához, hogy a keresési szolgáltatás indexelhesse azt.

A keresési szolgáltatásban összesen a következő objektumokat hozhatja létre:

Objektumokat Description
Adatforrások Az indexelő által az indexeléshez használt dokumentumok lekéréséhez és frissítéséhez használt adatforrás-kapcsolat. Az adatforrások rendelkeznek egy type. Partnereken keresztül használhatja a Microsoft által biztosított Kapcsolatokat az Azure-hoz vagy külső összekötőkhöz. A teljes listát az Adatforrások gyűjteményben találja.
Dokumentumok Elméletileg a dokumentum egy entitás az indexben. Ennek a koncepciónak a leképezése ismerősebb adatbázis-megfelelőkre: a keresési index egy táblának felel meg, a dokumentumok pedig nagyjából egyenértékűek a tábla soraival. A dokumentumok csak egy indexben léteznek, és csak az index dokumentumgyűjteményét (/docs) megcélzott lekérdezéseken keresztül kérik le. A gyűjteményen végrehajtott összes művelet, például a dokumentumok feltöltése, egyesítése, törlése vagy lekérdezése egyetlen index kontextusában történik, így az URL-formátumú dokumentumműveletek mindig egy adott indexnévhez tartoznak /indexes/[index name]/docs .
Indexek Az indexek a keresési szolgáltatásban vannak tárolva, és olyan JSON-dokumentumokkal vannak feltöltve, amelyek indexeltek és jogkivonatosak az információk lekéréséhez. Az index mezőgyűjteménye határozza meg a keresési dokumentum szerkezetét. A mezők névvel, adattípusokkal és attribútumokkal rendelkeznek, amelyek meghatározzák a használat módját. A mezőket például searchable teljes szöveges keresésben használják, így tokenizálva vannak az indexelés során. Az index egyéb szerkezeteket is definiál, például pontozási profilokat a relevanciahangoláshoz, javaslattevőket, szemantikai konfigurációkat és egyéni elemzőket.
Indexelők Az indexelők biztosítják az indexelés automatizálását. Az indexelő csatlakozik egy adatforráshoz, beolvassa az adatokat, és átadja azt egy keresőmotornak, hogy indexeljen egy célkeresési indexbe. Az indexelők egy külső forrásból olvasnak egy adatforrás kapcsolati adataival, és jSON-keresési dokumentumokba szerializálják a bejövő adatokat. Az adatforráson kívül az indexelőknek indexre is szükségük van. Az index határozza meg a keresési dokumentumok mezőit és attribútumait.
Készségek A képességcsoport külső feldolgozási lépéseket ad hozzá az indexelő végrehajtásához, és általában AI- vagy mélytanulási modellek hozzáadásával elemzi vagy átalakítja a tartalmat, hogy az indexben kereshető legyen. A képességcsoport tartalma egy vagy több képesség, amely a Microsoft által létrehozott beépített készségek , egyéni készségek vagy mindkettő kombinációja lehet. Beépített képességek állnak rendelkezésre a képelemzéshez, beleértve az OCR-t és a természetes nyelvi feldolgozást. A beépített képességekre további példák lehetnek többek között az entitások felismerése, a kulcskifejezések kinyerése, a szöveg logikai oldalakra való darabolása. A képességcsoport egy magas szintű önálló objektum, amely indexekkel, indexelőkkel és adatforrásokkal egyenértékű szinten létezik, de csak az indexelőfeldolgozáson belül működik. Magas szintű objektumként egy képességcsoportot egyszer tervezhet meg, majd több indexelőben hivatkozhat rá.
Szinonimák térképe A szinonimák leképezése szolgáltatásszintű objektum, amely felhasználó által definiált szinonimákat tartalmaz. Ezt az objektumot a rendszer a keresési indexektől függetlenül tartja karban. Feltöltés után bármely kereshető mezőt a szinonimatérképre irányíthat (mezőnként egyet).

Engedélyek és hozzáférés-vezérlés

Kulcsalapú hitelesítést vagy szerepköralapú hitelesítést használhat Microsoft Entra ID keresztül.

  • A kulcsalapú hitelesítés a keresési szolgáltatáshoz létrehozott API-kulcsokra támaszkodik. Érvényes kulcs birtokában kérelmenként létesíthető megbízhatósági kapcsolat a kérést küldő alkalmazás és az azt kezelő szolgáltatás között. Az olvasási és írási műveletekhez használhat Rendszergazda API-kulcsot, illetve lekérdezési API-kulcsot a keresési index dokumentumgyűjteményéhez való olvasási hozzáféréshez.

  • Microsoft Entra ID hitelesítéshez és a szerepköralapú hozzáférés-vezérléshez rendelkeznie kell egy létrehozott bérlővel Microsoft Entra ID, amely rendelkezik rendszerbiztonsági tagokkal és szerepkör-hozzárendelésekkel. Az alábbi szerepkörök tagjai adatsík-hozzáféréssel rendelkeznek. Egyéni szerepköröket akkor hozhat létre, ha a beépített szerepkörök nem elegendőek.

    Szerepkör Access
    Keresés szolgáltatás közreműködője Hozzáférés az objektumokhoz, de nincs hozzáférés az index tartalmához. Ez a szerepkör nem tud lekérdezni egy keresési indexet, és nem adhat hozzá, távolíthat el vagy frissíthet dokumentumokat egy keresési indexben. Ez a szerepkör azoknak a rendszergazdáknak szól, akiknek kezelniük kell az objektumokat, de nem tudják megtekinteni vagy elérni az objektumadatokat.
    adatindex-közreműködő Keresés Olvasási-írási hozzáférés az indextartalomhoz. Ez a szerepkör azoknak a fejlesztőknek vagy indextulajdonosoknak szól, akiknek importálni, frissíteniük vagy le kell kérdezniük egy index dokumentumgyűjteményét.
    Keresés adatindex-olvasó Olvasási hozzáférés az indextartalomhoz. Ez a szerepkör a lekérdezéseket futtató alkalmazások és felhasználók számára készült.

Ha szerepköröket használ a kapcsolaton, az ügyfélalkalmazás egy tulajdonosi jogkivonatot jelenít meg az engedélyezési fejlécben. A beállításhoz a keresési alkalmazáshoz való hozzáférés engedélyezése Microsoft Entra ID használatával című témakörben talál segítséget.

Letilthatja a kulcsalapú hitelesítést vagy a szerepköralapú hitelesítést. Ha letiltja a szerepköralapú hitelesítést, egyes beépített szerepkörök továbbra is hozzáférhetnek. További részletekért tekintse meg az Azure AI-Keresés Microsoft Entra ID hitelesítését és szerepköralapú hozzáférés-vezérlését.

Az API-k meghívása

Az ebben a szakaszban dokumentált API-k hozzáférést biztosítanak a keresési adatokon végzett műveletekhez, például az indexek létrehozásához és a populációhoz, a dokumentumok feltöltéséhez és a lekérdezésekhez. API-k hívásakor tartsa szem előtt a következő szempontokat:

  • A kéréseket HTTPS-en keresztül kell kiállítani (az alapértelmezett 443-at).

  • A kérelem URI-jainak tartalmazniuk kell az API-verziót. Az értéket egy támogatott verzióra kell állítani, az alábbi példában látható módon formázva: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • A kérelemfejléceknek tartalmazniuk kell egy API-kulcsot vagy egy tulajdonosi jogkivonatot a hitelesített kapcsolatokhoz. Igény szerint beállíthatja a HTTP-fejléc elfogadása beállítást is. Ha a tartalomtípus fejléce nincs beállítva, a rendszer az alapértelmezett értéket feltételezi application/json.

Lásd még