ai_query دالة

ينطبق على: Databricks SQL Databricks Runtime

استدعاء نقطة نهاية خدمة نموذج Azure Databricks موجودة وتحليلها وإرجاع استجابتها.

راجع الدلائل التالية لمعرفة كيفية استخدام ai_query حالات الاستخدام المختلفة:

• إجراء استدلال دفعي باستخدام ai_query
• الاستعلام عن نموذج خارجي باستخدام ai_query()
• الاستعلام عن نموذج تم تقديمه باستخدام ai_query()

المتطلبات

• هذه الدالة غير متوفرة على Azure Databricks SQL Classic.
• يجب تمكين Azure Private Link لاستخدام هذه الميزة على مستودعات SQL pro.
• يوصى باستخدام Databricks Runtime 15.3 أو أعلى. قد يؤدي استخدام Databricks Runtime 15.2 أو أقل إلى سرعات أداء أبطأ.
• لا تستخدم قناة مستودع DLT الحالية أحدث إصدار Databricks Runtime الذي يدعم ai_query(). pipelines.channel قم بتعيين في خصائص الجدول لاستخدام 'preview' ai_query(). راجع أمثلة لاستعلام عينة.
• نموذج موجود يخدم نقطة نهاية مع تحميل النموذج الخاص بك. راجع إنشاء نقاط نهاية خدمة نموذج مخصص.
• يجب أن تكون مساحة العمل الخاصة بك في منطقة خدمة النموذج المدعومة.
• يتم تمكين الاستعلام عن واجهات برمجة التطبيقات لنموذج الأساس بشكل افتراضي. للاستعلام عن نقاط النهاية التي تخدم نماذج مخصصة أو نماذج خارجية:
  • تمكين الذكاء الاصطناعي_Query للنماذج المخصصة والنماذج الخارجية في واجهة مستخدم معاينات Databricks.
  • راجع الاستعلام عن نموذج خارجي باستخدام ai_query().
  • راجع إجراء استدلال دفعي باستخدام ai_query

بناء الجملة

للاستعلام عن نقطة نهاية تخدم نموذجا خارجيا أو نموذجا تأسيسيا:

ai_query(endpointName, request)

للاستعلام عن نقطة نهاية خدمة نموذج مخصص مع مخطط نموذج:

ai_query(endpointName, request)

للاستعلام عن نقطة نهاية خدمة نموذج مخصص بدون مخطط نموذج:

ai_query(endpointName, request, returnType, failOnError)

الوسيطات

• endpointName: سلسلة حرفية، اسم نقطة نهاية خدمة نموذج Databricks Foundation، أو نموذج خارجي يخدم نقطة نهاية أو نقطة نهاية نموذج مخصص في نفس مساحة العمل للادعاءات. يجب أن يكون لدى المحدد إذن CAN QUERY على نقطة النهاية.
• request: تعبير، الطلب المستخدم لاستدعاء نقطة النهاية.
  • إذا كانت نقطة النهاية عبارة عن نموذج خارجي يخدم نقطة نهاية أو نقطة نهاية واجهات برمجة تطبيقات نموذج Databricks Foundation، يجب أن يكون الطلب سلسلة.
  • إذا كانت نقطة النهاية هي نموذج مخصص يخدم نقطة النهاية، يمكن أن يكون الطلب عمودا واحدا أو تعبير بنية. يجب أن تتطابق أسماء حقول البنية مع أسماء ميزات الإدخال المتوقعة بواسطة نقطة النهاية.
• returnType: تعبير، نوع الإرجاع المتوقع من نقطة النهاية. يشبه هذا معلمة المخطط في الدالة from_json، والتي تقبل كلا من تعبير سلسلة أو استدعاء الدالة schema_of_json.
  • في Databricks Runtime 14.2 وما فوق، إذا لم يتم توفير هذا التعبير، ai_query() يستنتج تلقائيا نوع الإرجاع من مخطط النموذج لنقطة نهاية خدمة النموذج المخصص.
  • في Databricks Runtime 14.1 والإصدارات أدناه، هذا التعبير مطلوب للاستعلام عن نموذج مخصص يخدم نقطة النهاية.
• failOnError: (اختياري) القيمة الافتراضية المنطقية للقيمة الافتراضية true. تشير هذه العلامة إلى ما إذا كان يجب تضمين حالة الخطأ في الاستجابة ai_query . يختلف تنسيق الاستجابة عند تعيين هذا إلى false.
• modelParameters (اختياري): حقل بنية يحتوي على معلمات نموذج الدردشة والإكمال وتضمينها لخدمة النماذج الأساسية أو النماذج الخارجية. يجب أن تكون معلمات النموذج هذه معلمات ثابتة ولا تعتمد على البيانات. عندما لا يتم تحديد معلمات النموذج هذه أو تعيينها إلى null القيمة الافتراضية يتم استخدامها. باستثناء temperature التي لها قيمة افتراضية 0.0، القيم الافتراضية لمعلمات النموذج هذه هي نفسها تلك المدرجة في مرجع واجهة برمجة تطبيقات REST لنموذج Foundation.

المرتجعات

الاستجابة التي تم تحليلها من نقطة النهاية.

• إذا failOnError => true، ترجع الدالة نفس النتيجة مثل السلوك الحالي، وهو الاستجابة التي تم تحليلها من نقطة النهاية. يتم استنتاج نوع بيانات الاستجابة التي تم تحليلها من نوع النموذج أو نقطة نهاية مخطط النموذج أو المعلمة returnType في الدالة ai_query .
• إذا failOnError => false، ترجع الدالة الاستجابة التي تم تحليلها وسلسلة حالة الخطأ ككائن STRUCT.
  • إذا نجح استنتاج الصف، يكون errorStatus الحقل فارغا.
  • إذا فشل استنتاج الصف بسبب أخطاء نقطة نهاية النموذج، response يكون الحقل فارغا.
  • إذا فشل استنتاج الصف بسبب أخطاء أخرى، يفشل الاستعلام بأكمله.

الأمثلة

فيما يلي مثال للاستدلال الدفعي باستخدام failOnError و modelParameters مع max_tokens و temperature. يوضح هذا المثال أيضا كيفية تسلسل المطالبة بالنموذج وعمود الاستدلال باستخدام concat(). هناك طرق متعددة لتنفيذ التسلسل، مثل استخدام ||أو concat()أو format_string().

CREATE OR REPLACE TABLE ${output_table_name} AS (
  SELECT
      ${input_column_name},
      AI_QUERY(
        "${endpoint}",
        CONCAT("${prompt}", ${input_column_name}),
        failOnError => false,
        modelParameters => named_struct('max_tokens', ${num_output_tokens},'temperature', ${temperature})
      ) as response
    FROM ${input_table_name}
    LIMIT ${input_num_rows}
)

للاستعلام عن نقطة نهاية خدمة نموذج خارجي:

> SELECT ai_query(
    'my-external-model-openai-chat',
    'Describe Databricks SQL in 30 words.'
  ) AS summary

  "Databricks SQL is a cloud-based platform for data analytics and machine learning, providing a unified workspace for collaborative data exploration, analysis, and visualization using SQL queries."

للاستعلام عن نموذج أساسي مدعوم من قبل واجهات برمجة تطبيقات نموذج Databricks Foundation:

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    "Can you tell me the name of the US state that serves the provided ZIP code? zip code: " || pickup_zip
    )
  FROM samples.nyctaxi.trips
  LIMIT 10

اختياريا، يمكنك أيضا إجراء التفاف لاستدعاء ai_query() في UDF لاستدعاء الدالة كما يلي:

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));
> GRANT EXECUTE ON correct_grammar TO ds;
- DS fixes grammar issues in a batch.
> SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

للاستعلام عن نقطة نهاية خدمة نموذج مخصص:

> SELECT text, ai_query(
    endpoint => 'spam-classification-endpoint',
    request => named_struct(
      'timestamp', timestamp,
      'sender', from_number,
      'text', text),
    returnType => 'BOOLEAN') AS is_spam
  FROM messages

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

> SELECT ai_query(
    'custom-llama-2-7b-chat',
    request => named_struct("messages",
        ARRAY(named_struct("role", "user", "content", "What is ML?"))),
    returnType => 'STRUCT<candidates:ARRAY<STRING>>')

  {"candidates":["ML stands for Machine Learning. It's a subfield of Artificial Intelligence that involves the use of algorithms and statistical models to enable machines to learn from data, make decisions, and improve their performance on a specific task over time."]}

مثال استعلام لتعيين قناة DLT للمعاينة:

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages