درس تعليمي: استكشف Azure OpenAI في تضمين Microsoft Foundry Models والبحث عن المستندات

سيرشدك هذا الدرس خلال استخدام واجهة برمجة التطبيقات Azure OpenAI embeddings لإجراء search document حيث ستقوم بالاستعلام عن قاعدة معرفة للعثور على أكثر مستند صلة.

في هذا الدرس، تتعلم كيف:

  • قم بتحميل مجموعة بيانات نموذجية وجهزها للتحليل.
  • أنشئ متغيرات البيئة لنقطة نهاية الموارد ومفتاح واجهة برمجة التطبيقات الخاصة بك.
  • استخدم أحد النماذج التالية: نص-تضمين-ada-002 (الإصدار 2)، نص-تضمين-3-كبير، نص-تضمين-3-صغير.
  • استخدم تشابه جيب تمام لترتيب نتائج البحث.

المتطلبات الأساسية

الإعداد

مكتبات Python

إذا لم تفعل ذلك بعد، عليك تثبيت المكتبات التالية:

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

حمل مجموعة بيانات BillSum

BillSum هو مجموعة بيانات لمشاريع قوانين الكونغرس United States وقوانين ولاية كاليفورنيا. لأغراض توضيحية، سننظر فقط إلى الفواتير الأمريكية. يتكون هذا المجموع من مشاريع قوانين من الدورة 103 إلى 115 (1993-2018) للكونغرس. تم تقسيم البيانات إلى 18,949 فاتورة قطار و3,269 فاتورة اختبار. يركز مجموعة BillSum على التشريعات متوسطة الطول التي يتراوح طولها بين 5,000 إلى 20,000 حرف. يمكن العثور على مزيد من المعلومات حول المشروع والورقة الأكاديمية الأصلية التي اشتقت منها هذه المجموعة في مستودع GitHub لمشروع BillSum

يستخدم هذا الدرس ملف bill_sum_data.csv الذي يمكن تنزيله من بياناتنا النموذجية GitHub.

يمكنك أيضا تنزيل بيانات العينة عن طريق تشغيل الأمر التالي على جهازك المحلي:

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

ملاحظة

المصادقة المعتمدة على Microsoft Entra ID غير مدعومة حاليا للتضمينات مع واجهة برمجة التطبيقات v1.

استرجاع المفتاح ونقطة النهاية

لإجراء قرار ناجح ضد Azure OpenAI، تحتاج إلى endpoint وkey.

اسم المتغيرات القيمة
ENDPOINT يمكن العثور على نقطة نهاية الخدمة في Keys & Keys قسم Endpoint عند فحص موردك من بوابة Azure. بدلا من ذلك، يمكنك العثور على نقطة النهاية عبر صفحة Deployments في بوابة Microsoft Foundry. مثال على نقطة النهاية هو: https://docs-test-001.openai.azure.com/.
API-KEY يمكن العثور على هذه القيمة في Keys & قسم Endpoint عند فحص موردك من بوابة Azure. يمكنك استخدام أي منهما KEY1 أو KEY2.

اذهب إلى مصدرك في بوابة Azure. يمكن العثور على قسم المفاتيح والنهاية في قسم إدارة الموارد . انسخ نقطة النهاية ومفتاح الوصول لأنك ستحتاج إلى كلاهما لمصادقة استدعاءات واجهة برمجة التطبيقات الخاصة بك. يمكنك استخدام أي منهما KEY1 أو KEY2. دائما وجود مفتاحين يسمح لك بتدوير وإعادة توليد المفاتيح بأمان دون التسبب في تعطيل للخدمة.

لقطة شاشة لواجهة العرض العامة لمورد Azure OpenAI في بوابة Azure مع تحديد موقع نقطة النهاية ومفاتيح الوصول باللون الأحمر.

متغيرات البيئة

أنشئ وعين متغيرات البيئة الدائمة لمفتاح واجهة برمجة التطبيقات الخاصة بك.

مهم

استخدم مفاتيح API بحذر. لا تدرج مفتاح واجهة برمجة التطبيقات مباشرة في كودك، ولا تنشره علنا أبدا. إذا كنت تستخدم مفتاح API، خزنه بأمان في Azure Key Vault. لمزيد من المعلومات حول استخدام مفاتيح API بأمان في تطبيقاتك، راجع <مفاتيح ال c0>API مع Azure Key Vault.

لمزيد من المعلومات حول أمان خدمات الذكاء الاصطناعي، راجع التحقق من الطلبات إلى خدماتالذكاء الاصطناعي في Azure.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

بعد تعيين متغيرات البيئة، قد تحتاج إلى إغلاق وإعادة فتح دفاتر Jupyter أو أي بيئة تطوير تستخدمها لكي تكون متغيرات البيئة متاحة. بينما نوصي بشدة باستخدام Jupyter Notebooks، إذا لم تستطع لأي سبب من الأسباب، فستحتاج إلى تعديل أي كود يعيد إطار بيانات pandas باستخدام print(dataframe_name) بدلا من استدعائه dataframe_name مباشرة كما يحدث غالبا في نهاية كتلة الكود.

شغل الكود التالي في بيئة تطوير Python المفضلة لديك:

مكتبات الاستيراد

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

الآن نحتاج إلى قراءة ملف csv الخاص بنا وإنشاء بياندا DataFrame. بعد إنشاء إطار البيانات الأولي، يمكننا عرض محتويات الجدول عن طريق تشغيل df.

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

المخرج:

لقطة شاشة لجدول DataFrame الأولي من ملف csv.

الجدول الأولي يحتوي على أعمدة أكثر مما نحتاج، سننشئ DataFrame أصغر جديد يسمى df_bills والذي سيحتوي فقط على الأعمدة ل text، summary، و title.

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

المخرج:

لقطة شاشة لجدول DataFrame الأصغر مع عرض أعمدة النص والملخص والعنوان فقط.

بعد ذلك سنقوم ببعض التنظيف الخفيف للبيانات عن طريق إزالة المساحات البيضاء الزائدة وتنظيف علامات الترقيم لتحضير البيانات للترميز.

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))

الآن نحتاج إلى إزالة أي مشاريع قوانين طويلة جدا على حد الرمز (8,192 رمزا).

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

ملاحظة

في هذه الحالة، جميع الأوراق المالية تحت حد رمز إدخال نموذج التضمين، لكن يمكنك استخدام التقنية أعلاه لإزالة الإدخالات التي قد تؤدي إلى فشل التضمين. عند مواجهة محتوى يتجاوز حد التضمين، يمكنك أيضا تقسيم المحتوى إلى أجزاء أصغر ثم تضمين الأجزاء واحدة تلو الأخرى.

سنفحص df_bills مرة أخرى.

df_bills

المخرج:

لقطة شاشة لإطار البيانات مع عمود جديد يسمى n_tokens.

لفهم عمود n_tokens بشكل أعمق وكيفية تحويل النص في النهاية، قد يكون من المفيد تشغيل الكود التالي:

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

بالنسبة لوثائقنا، نحن نقص المخرجات عمدا، لكن تشغيل هذا الأمر في بيئتك سيعيد النص الكامل من index zero المرمز إلى أجزاء. يمكنك أن ترى أنه في بعض الحالات يتم تمثيل كلمة كاملة برمز واحد، بينما في حالات أخرى يتم تقسيم أجزاء الكلمات عبر عدة رموز متعددة.

[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',

إذا تحققت من طول المتغير decode ، ستجد أنه يطابق الرقم الأول في عمود n_tokens.

len(decode)

1466

الآن بعد أن فهمنا أكثر عن كيفية عمل الترميز، يمكننا الانتقال إلى التضمين. من المهم ملاحظة أننا لم نقم بعد بتحويل الوثائق إلى ترميز. العمود n_tokens هو ببساطة وسيلة للتأكد من أن أيا من البيانات التي نمررها إلى النموذج للترميزين والتضمين لا تتجاوز حد الرمز المدخل البالغ 8,192. عندما نمرر المستندات إلى نموذج التضمينات، سيتم تقسيم المستندات إلى رموز مشابهة (وإن ليست بالضرورة متطابقة) للأمثلة أعلاه ثم تحول الرموز إلى سلسلة من أرقام الفاتورات العائمة التي يمكن الوصول إليها عبر البحث المتجه. يمكن تخزين هذه التضمينات محليا أو في قاعدة بيانات Azure لدعم البحث المتجه. وبالتالي، سيكون لكل ورقة نقدية متجه تضمين خاص بها في العمود الجديد ada_v2 على الجانب الأيمن من إطار البيانات.

في المثال أدناه، نستدعي نموذج التضمين مرة واحدة لكل عنصر نريد تضمينه. عند العمل مع مشاريع تضمين كبيرة، يمكنك بدلا من ذلك تمرير مصفوفة من المدخلات للنموذج ليتم تضمينها بدلا من إدخال واحد في كل مرة. عندما تمرر النموذج، يكون هناك مصفوفة من المدخلات، ويكون الحد الأقصى لعدد العناصر المدخلة لكل مكالمة إلى نقطة النهاية المضمنة هو 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

المخرج:

لقطة شاشة للنتائج المنسقة من df_bills الأمر.

أثناء تشغيل كتلة كود البحث أدناه، سندمج استعلام البحث "هل يمكنني الحصول على معلومات عن إيرادات ضرائب شركات الكابل؟" بنفس نموذج نص-embedding-ada-002 (الإصدار 2). بعد ذلك سنجد أقرب تضمين للورقة للنص المدمج حديثا من استعلامنا مصنفا حسب تشابه جيب تمام.

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)

المخرج:

لقطة شاشة للنتائج المنسقة لعملية التحديث بعد تشغيل استعلام البحث.

وأخيرا، سنعرض أعلى نتيجة من بحث المستندات بناء على استعلام المستخدم مقابل قاعدة المعرفة الكاملة. وهذا يعكس النتيجة العليا ل "قانون حق دافعي الضرائب في المشاهدة لعام 1993." هذا المستند له درجة تشابه جيب تمامي تبلغ 0.76 بين الاستعلام والوثيقة:

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."

باستخدام هذا النهج، يمكنك استخدام التضمين كآلية بحث عبر المستندات في قاعدة المعرفة. يمكن للمستخدم بعد ذلك أخذ أعلى نتيجة بحث واستخدامها في مهمته التالية، والتي دفعته للاستفسار الأولي.

استكشاف الأخطاء

  • 401/403: التحقق AZURE_OPENAI_API_KEY محدد ويطابق مفتاح الموارد الخاص بك.
  • 404: تحقق AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT من تطابق اسم النشر الخاص بك.
  • عنوان URL غير صحيح: Verify AZURE_OPENAI_ENDPOINT هو نقطة نهاية المورد الخاصة بك، على سبيل المثال https://<resource-name>.openai.azure.com.

موارد التنظيف

إذا أنشأت مورد Azure OpenAI فقط لإكمال هذا الدرس وترغب في تنظيف وإزالة مورد Azure OpenAI، فستحتاج إلى حذف النماذج التي تم نشرها، ثم حذف المورد أو مجموعة الموارد المرتبطة إذا كانت مخصصة لمورد الاختبار الخاص بك. حذف مجموعة الموارد يحذف أيضا أي موارد أخرى مرتبطة بها.

  • مدخل Azure
  • واجهة سطر الأوامر Azure (Azure CLI)

الخطوات التالية

تعرف أكثر على نماذج Azure OpenAI:

Azure نماذج OpenAI

  • Last updated on