Sdílet prostřednictvím

Kurz: Prozkoumání Azure OpenAI v Microsoft Foundry modelech, embeddingy a vyhledávání dokumentů

Tento kurz vás provede používáním rozhraní API Azure OpenAI embeddings API k provádění dokumentového vyhledávání kde zadáte dotaz na knowledge base a najdete nejrelevantnější dokument.

V tomto návodu se naučíte, jak:

  • Stáhněte si ukázkovou datovou sadu a připravte ji na analýzu.
  • Vytvořte proměnné prostředí pro koncový bod prostředků a klíč rozhraní API.
  • Použijte jeden z následujících modelů: text-embedding-ada-002 (verze 2), text-embedding-3-large, text-embedding-3-small models.
  • K řazení výsledků hledání použijte kosinusovou podobnost .

Předpoklady

Nastavení

Knihovny Pythonu

Pokud jste to ještě neudělali, musíte nainstalovat následující knihovny:

pip install openai num2words matplotlib plotly scipy scikit-learn pandas tiktoken

Stažení datové sady BillSum

BillSum je datová sada United States kongresových a kaliforniových státních faktur. Pro ilustraci se podíváme jenom na faktury v USA. Korpus se skládá z návrhů zákonů ze sněmovních zasedání 103.-115. kongresu (1993-2018). Data byla rozdělena na 18 949 faktur za vlak a 3 269 zkušebních faktur. Korpus BillSum se zaměřuje na právní předpisy střední délky od 5 000 do 20 000 znaků. Další informace o project a původním akademickém dokumentu, ze kterého je tato datová sada odvozena, najdete v úložišti BillSum project GitHub

V tomto kurzu se používá soubor bill_sum_data.csv, který si můžete stáhnout z našich ukázkových dat GitHub.

Ukázková data si můžete stáhnout také spuštěním následujícího příkazu na místním počítači:

curl "https://raw.githubusercontent.com/Azure-Samples/Azure-OpenAI-Docs-Samples/main/Samples/Tutorials/Embeddings/data/bill_sum_data.csv" --output bill_sum_data.csv

Poznámka:

ověřování na základě Microsoft Entra ID se v současné době nepodporuje pro vkládání pomocí rozhraní API v1.

Získání klíče a koncového bodu

K úspěšnému volání Azure OpenAI potřebujete endpoint a key.

Název proměnné Hodnota
ENDPOINT Koncový bod služby najdete v části Klíče a koncový bod při prohlížení vašeho prostředku na portálu Azure. Koncový bod najdete také na stránce Nasazení na portálu Microsoft Foundry. Příkladem koncového bodu je: https://docs-test-001.openai.azure.com/.
API-KEY Tuto hodnotu najdete v sekci Klíče a koncový bod při zkoumání vašeho prostředku z portálu Azure. Použít můžete předponu KEY1 nebo KEY2.

Přejděte na svůj prostředek v Azure portálu. Část Klíče a koncový bod najdete v části Správa prostředků. Zkopírujte koncový bod a přístupový klíč, protože budete potřebovat obojí pro ověřování volání rozhraní API. Použít můžete předponu KEY1 nebo KEY2. Vždy mít dva klíče vám umožní bezpečně otáčet a znovu vygenerovat klíče, aniž by to způsobilo přerušení služeb.

Screenshot přehledového uživatelského rozhraní pro prostředek Azure OpenAI v Azure Portalu s koncovým bodem a umístěním přístupových klíčů zakroužkovaných červeně.

Proměnné prostředí

Vytvořte a přiřaďte pro klíč rozhraní API trvalé systémové proměnné.

Důležité

Používejte klíče rozhraní API s opatrností. Nezahrnujte klíč API přímo do svého kódu a nikdy ho nezveřejňujte veřejně. Pokud používáte klíč rozhraní API, bezpečně ho uložte do Azure Key Vault. Další informace o bezpečném používání klíčů API v aplikacích najdete v tématu KLÍČEAPI s Azure Key Vault.

Další informace o zabezpečení služeb AI najdete v tématu Ověření požadavků na služby Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

Po nastavení proměnných prostředí možná budete muset zavřít a znovu otevřít poznámkové bloky Jupyter nebo jakékoli prostředí IDE, které používáte, aby byly proměnné prostředí přístupné. I když důrazně doporučujeme používat poznámkové bloky Jupyter, pokud je z nějakého důvodu nemůžete použít, budete muset upravit jakýkoli kód, který vrací datový rámec pandas, a to tak, že použijete print(dataframe_name) namísto toho, abyste přímo volali dataframe_name, jak se často dělá na konci bloku kódu.

V preferovaném integrovaném vývojovém prostředí Pythonu spusťte následující kód:

Import knihoven

import os
import re
import requests
import sys
from num2words import num2words
import os
import pandas as pd
import numpy as np
import tiktoken
from openai import OpenAI

Teď potřebujeme přečíst soubor CSV a vytvořit datový rámec pandas. Po vytvoření počátečního datového rámce můžeme zobrazit obsah tabulky spuštěním dfpříkazu .

df=pd.read_csv(os.path.join(os.getcwd(),'bill_sum_data.csv')) # This assumes that you have placed the bill_sum_data.csv in the same directory you are running Jupyter Notebooks
df

Výstup:

Snímek obrazovky s počáteční tabulkou datového rámce ze souboru CSV

Počáteční tabulka obsahuje více sloupců, než potřebujeme, vytvoříme nový menší datový rámec, df_bills který bude obsahovat pouze sloupce pro text, summarya title.

df_bills = df[['text', 'summary', 'title']]
df_bills

Výstup:

Snímek obrazovky menší tabulky výsledků datového rámce se zobrazenými pouze textovými, souhrny a záhlavími sloupci.

V dalším kroku provedeme čištění lehkých dat odebráním nadbytečných prázdných znaků a vyčištěním interpunkce pro přípravu dat na tokenizaci.

pd.options.mode.chained_assignment = None #https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#evaluation-order-matters

# s is input text
def normalize_text(s, sep_token = " \n "):
    s = re.sub(r'\s+',  ' ', s).strip()
    s = re.sub(r"\. ,","",s) 
    # remove all instances of multiple spaces
    s = s.replace("..",".")
    s = s.replace(". .",".")
    s = s.replace("\n", "")
    s = s.strip()
    
    return s

df_bills['text']= df_bills["text"].apply(lambda x : normalize_text(x))

Teď potřebujeme odebrat všechny faktury, které jsou pro limit tokenu příliš dlouhé (8 192 tokenů).

tokenizer = tiktoken.get_encoding("cl100k_base")
df_bills['n_tokens'] = df_bills["text"].apply(lambda x: len(tokenizer.encode(x)))
df_bills = df_bills[df_bills.n_tokens<8192]
len(df_bills)

20

Poznámka:

V tomto případě jsou všechny faktury pod limitem vstupního tokenu modelu vložení, ale výše uvedenou techniku můžete použít k odebrání položek, které by jinak způsobily selhání vkládání. Pokud se setkáte s obsahem, který překračuje limit vkládání, můžete obsah také zakládat na menší části a pak je vložit po jednom.

Znovu prozkoumáme df_bills.

df_bills

Výstup:

Snímek obrazovky datového rámce s novým sloupcem s názvem n_tokens

Pokud chcete porozumět n_tokens sloupci trochu víc a zjistit, jak se text nakonec tokenizuje, může být užitečné spustit následující kód:

sample_encode = tokenizer.encode(df_bills.text[0]) 
decode = tokenizer.decode_tokens_bytes(sample_encode)
decode

Pro naše dokumenty záměrně zkracujeme výstup, ale spuštění tohoto příkazu ve vašem prostředí vrátí celý text z indexu nula tokenizovaných do bloků dat. Vidíte, že v některých případech je celé slovo reprezentováno jedním tokenem, zatímco v jiných částech slov jsou rozdělené mezi více tokenů.

[b'SECTION',
 b' ',
 b'1',
 b'.',
 b' SHORT',
 b' TITLE',
 b'.',
 b' This',
 b' Act',
 b' may',
 b' be',
 b' cited',
 b' as',
 b' the',
 b' ``',
 b'National',
 b' Science',
 b' Education',
 b' Tax',
 b' In',
 b'cent',
 b'ive',
 b' for',
 b' Businesses',
 b' Act',
 b' of',
 b' ',
 b'200',
 b'7',
 b"''.",
 b' SEC',
 b'.',
 b' ',
 b'2',
 b'.',
 b' C',
 b'RED',
 b'ITS',
 b' FOR',
 b' CERT',
 b'AIN',
 b' CONTRIBUT',
 b'IONS',
 b' BEN',
 b'EF',
 b'IT',
 b'ING',
 b' SC',

Pokud pak zkontrolujete délku decode proměnné, zjistíte, že odpovídá prvnímu číslu ve sloupci n_tokens.

len(decode)

1466

Teď, když rozumíme tomu, jak tokenizace funguje, můžeme přejít na vkládání. Je důležité si uvědomit, že jsme dokumenty ještě neztokenizovali. Sloupec n_tokens je jednoduše způsob, jak zajistit, aby žádná data, která předáme modelu pro tokenizaci a vkládání, překročila limit vstupního tokenu 8 192. Když dokumenty předáme embeddingovému modelu, rozdělí dokumenty na tokeny podobné (i když nemusí nutně identické) výše uvedeným příkladům a pak převede tokeny na řadu reálných čísel, která budou přístupná prostřednictvím vektorového vyhledávání. Tyto vkládání je možné ukládat místně nebo v databázi Azure pro podporu vektorového vyhledávání. V důsledku toho bude mít každý faktura svůj vlastní odpovídající vektor vložení do nového ada_v2 sloupce na pravé straně datového rámce.

V následujícím příkladu voláme model vkládání jednou pro každou položku, kterou chceme vložit. Při práci s velkými projekty vkládání můžete alternativně předat model pole vstupů pro vložení místo jednoho vstupu najednou. Když modelu předáte pole vstupů, maximální počet vstupních položek pro každé volání embedovacího endpointu je 2048.

client = OpenAI(
  api_key = os.getenv("AZURE_OPENAI_API_KEY"),  
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

def generate_embeddings(text, model="text-embedding-ada-002"): # model = "deployment_name"
    return client.embeddings.create(input = [text], model=model).data[0].embedding

df_bills['ada_v2'] = df_bills["text"].apply(lambda x : generate_embeddings (x, model = 'text-embedding-ada-002')) # model should be set to the deployment name you chose when you deployed the text-embedding-ada-002 (Version 2) model

df_bills

Výstup:

Snímek obrazovky s formátovanými výsledky z příkazu df_bills

Když níže spustíme blok vyhledávacího kódu, vložíme vyhledávací dotaz "Můžu získat informace o daňových výnosech kabelové společnosti?". se stejným modelem text-embedding-ada-002 (verze 2). V dalším kroku najdeme nejbližší vložení faktury k nově vloženému textu z dotazu seřazeného podle kosinusové podobnosti.

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def get_embedding(text, model="text-embedding-ada-002"): # model = "deployment_name"
    return client.embeddings.create(input = [text], model=model).data[0].embedding

def search_docs(df, user_query, top_n=4, to_print=True):
    embedding = get_embedding(
        user_query,
        model="text-embedding-ada-002" # model should be set to the deployment name you chose when you deployed the text-embedding-ada-002 (Version 2) model
    )
    df["similarities"] = df.ada_v2.apply(lambda x: cosine_similarity(x, embedding))

    res = (
        df.sort_values("similarities", ascending=False)
        .head(top_n)
    )
    if to_print:
        display(res)
    return res

res = search_docs(df_bills, "Can I get information on cable company tax revenue?", top_n=4)

Výstup:

Snímek obrazovky s formátovanými výsledky res po spuštění vyhledávacího dotazu

Nakonec zobrazíme nejlepší výsledek hledání dokumentů na základě uživatelského dotazu na celou knowledge base. Vrátí nejlepší výsledek pro "Právo daňového poplatníka na nahlédnutí do zákona z roku 1993". Tento dokument má skóre kosínové podobnosti 0,76 mezi dotazem a dokumentem.

res["summary"][9]

"Taxpayer's Right to View Act of 1993 - Amends the Communications Act of 1934 to prohibit a cable operator from assessing separate charges for any video programming of a sporting, theatrical, or other entertainment event if that event is performed at a facility constructed, renovated, or maintained with tax revenues or by an organization that receives public financial support. Authorizes the Federal Communications Commission and local franchising authorities to make determinations concerning the applicability of such prohibition. Sets forth conditions under which a facility is considered to have been constructed, maintained, or renovated with tax revenues. Considers events performed by nonprofit or public organizations that receive tax subsidies to be subject to this Act if the event is sponsored by, or includes the participation of a team that is part of, a tax exempt organization."

Pomocí tohoto přístupu můžete vkládání použít jako mechanismus vyhledávání v dokumentech v knowledge base. Uživatel pak může převzít nejlepší výsledek vyhledávání a použít ho pro úkol, který vedl k jejich počátečnímu dotazu.

Řešení problémů

  • 401/403: Ověřte, že hodnota AZURE_OPENAI_API_KEY je nastavena a odpovídá klíči prostředku.
  • 404: Ověřte, že AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT odpovídá vašemu názvu nasazení.
  • Invalid URL: Ověřte, AZURE_OPENAI_ENDPOINT je vaším koncovým bodem prostředku, například https://<resource-name>.openai.azure.com.

Vyčistěte zdroje

Pokud jste vytvořili prostředek Azure OpenAI výhradně pro dokončení tohoto kurzu a chcete vyčistit a odebrat prostředek Azure OpenAI, budete muset odstranit nasazené modely a potom odstranit prostředek nebo přidruženou skupinu prostředků, pokud je vyhrazený pro testovací prostředek. Smazání skupiny prostředků také smaže všechny ostatní prostředky s ní spojené.

Další kroky

Další informace o modelech OpenAI Azure:

Azure modely OpenAI

  • Last updated on