استخدام قوالب مطالبات المقابض

مكتمل

يدعم Kernel الدلالي استخدام بناء جملة قالب Handlebars للمطالبات. تعد المقابض لغة تقزم مباشرة تستخدم بشكل أساسي لإنشاء HTML، ولكن يمكنها أيضا إنشاء تنسيقات نصية أخرى. تتكون قوالب المقابض من نص عادي يتخلله تعبيرات المقابض.

لاستخدام قالب Handlebars مع Kernel الدلالي، ابدأ بتثبيت الحزمة:

dotnet add package Microsoft.SemanticKernel.PromptTemplates.Handlebars --version 1.30.0

pip install --upgrade semantic-kernel

بعد ذلك، قم باستيراد الحزمة إلى التعليمات البرمجية الخاصة بك:

using Microsoft.SemanticKernel.PromptTemplates.Handlebars;

تتضمن جميع عبارات المستوى الأعلى المضافة ما يلي:

using Microsoft.SemanticKernel; // Core Semantic Kernel SDK
using Microsoft.SemanticKernel.Connectors.AI.OpenAI; // Azure OpenAI connector
using Microsoft.SemanticKernel.PromptTemplates; // For prompt template configuration
using Microsoft.SemanticKernel.PromptTemplates.Handlebars; // For Handlebars template support
using System; // For Console and basic types
using System.Collections.Generic; // For Dictionary and KernelArguments
using System.IO; // For file operations (e.g., loading YAML)
using System.Threading.Tasks; // For async/await support

from semantic_kernel.prompt_template.handlebars_prompt_template import HandlebarsPromptTemplate   

تتضمن جميع عبارات المستوى الأعلى المضافة ما يلي:

from semantic_kernel.prompt_template import PromptTemplateConfig      # for prompt_config
from semantic_kernel.prompt_template.handlebars_prompt_template import HandlebarsPromptTemplate  # for function
import json      # for loading appsettings.json
import yaml      # for loading HandlebarsPrompt.yaml
import asyncio   # for running async main
from semantic_kernel import Kernel      #  Needed (for kernel)
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion  # for chat_service

يوضح المثال التالي قالب موجه الدردشة الذي يستخدم بناء جملة Handlebars. يحتوي القالب على تعبيرات مقابض، مشروحة بواسطة {{ و }}. عند تنفيذ القالب، يتم استبدال هذه التعبيرات بقيم من كائن إدخال.

const string HandlebarsTemplate = """
    <message role="system">You are an AI assistant designed to help with image recognition tasks.</message>
    <message role="user">
        <text>{{request}}</text>
        <image>{{imageData}}</image>
    </message>
    """;

handlebars_template = """
<message role="system">You are an AI assistant designed to help with image recognition tasks.</message>
<message role="user">
    <text>{{request}}</text>
    <image>{{imageData}}</image>
</message>
"""

في هذا المثال، هناك كائنان إدخال:

• request - يحتوي على الطلب الذي يجب أن يكمله المساعد.
• imageData - يحتوي على بيانات صورة base64.

لاستخدام قالب المطالبة، تحتاج إلى إنشاء كائن PromptTemplateConfig يحتوي على القالب وتنسيقه. بعد ذلك، يمكنك إنشاء كائن KernelFunction من تكوين القالب وتحديد مصنع قالب Handlebars. إليك مثال:

// Create the prompt template configuration
var templateFactory = new HandlebarsPromptTemplateFactory();
var promptTemplateConfig = new PromptTemplateConfig()
{
    Template = HandlebarsTemplate,
    TemplateFormat = "handlebars",
    Name = "Vision_Chat_Prompt",
};

// Create a function from the Handlebars template configuration
var function = kernel.CreateFunctionFromPrompt(promptTemplateConfig, templateFactory);

# Load Azure OpenAI config from a JSON file
with open('appsettings.json', 'r') as f:
    config = json.load(f)

model_id = config["modelId"]
endpoint = config["endpoint"]
api_key = config["apiKey"]

# Set up Semantic Kernel and Azure OpenAI service
kernel = Kernel()
chat_service = AzureChatCompletion(
    deployment_name=model_id,
    endpoint=endpoint,
    api_key=api_key
)
kernel.add_service(chat_service, "chat_completion")

# Create the prompt template config and function
prompt_config = PromptTemplateConfig(
    template=handlebars_template,
    template_format="handlebars",
    name="Vision_Chat_Prompt"
)
function = HandlebarsPromptTemplate(prompt_template_config=prompt_config)

الآن يمكنك إنشاء KernelArguments الكائن مع بيانات الإدخال واستدعاء الدالة الخاصة بك.

var arguments = new KernelArguments(new Dictionary<string, object?>
{
    {"request","Describe this image:"},
    {"imageData", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAAXNSR0IArs4c6QAAACVJREFUKFNj/KTO/J+BCMA4iBUyQX1A0I10VAizCj1oMdyISyEAFoQbHwTcuS8AAAAASUVORK5CYII="}
});

var response = await kernel.InvokeAsync(function, arguments);

arguments = {
    "request": "Describe this image:",
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAAXNSR0IArs4c6QAAACVJREFUKFNj/KTO/J+BCMA4iBUyQX1A0I10VAizCj1oMdyISyEAFoQbHwTcuS8AAAAASUVORK5CYII="
}

async def main():
    result = await kernel.invoke_prompt(
        prompt=prompt_config.template,
        request=arguments["request"],
        imageData=arguments["imageData"],
        service_id="chat_completion",
        template_format="handlebars"
    )
    print("Kernel result:", result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

ستكون الاستجابة لهذه المطالبة مشابهة للإخراج التالي:

The image is a solid block of bright red color. There are no additional features, shapes, or textures present.

استخدام قوالب المقابض في مطالبات YAML

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

التعليمات البرمجية التالية هي مثال على تمثيل YAML لمطالبة الدردشة المستخدمة في القسم السابق:

name: Vision_Chat_Prompt
template: |
    <message role="system">
        You are an AI assistant designed to help with image recognition tasks.
    </message>
    <message role="user">
        <text>{{request}}</text>
        <image>{{imageData}}</image>
    </message>
template_format: handlebars
description: Vision chat prompt template.
input_variables:
  - name: request
    description: Request details.
    is_required: true
  - name: imageData
    description: Base64 image data.
    is_required: true

لاستخدام هذه المطالبة، يمكنك تحميلها كمورد مضمن، وتحويلها إلى دالة ثم استدعاؤها.

// Load prompt from resource
var handlebarsPromptYaml = EmbeddedResource.Read("HandlebarsPrompt.yaml");

// Create the prompt function from the YAML resource
var templateFactory = new HandlebarsPromptTemplateFactory();
var function = kernel.CreateFunctionFromPromptYaml(handlebarsPromptYaml, templateFactory);

// Input data for the prompt rendering and execution
var arguments = new KernelArguments(new Dictionary<string, object?>
{
    {"request","Describe this image:"},
    {"imageData", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAAXNSR0IArs4c6QAAACVJREFUKFNj/KTO/J+BCMA4iBUyQX1A0I10VAizCj1oMdyISyEAFoQbHwTcuS8AAAAASUVORK5CYII="}
});

// Invoke the prompt function
var response = await kernel.InvokeAsync(function, arguments);

import yaml

# Load YAML prompt from file
with open("HandlebarsPrompt.yaml", "r") as f:
    yaml_prompt = yaml.safe_load(f)

prompt_config = PromptTemplateConfig(
    template=yaml_prompt["template"],
    template_format="handlebars",
    name=yaml_prompt.get("name", "Vision_Chat_Prompt")
)

function = HandlebarsPromptTemplate(prompt_template_config=prompt_config)

arguments = {
    "request": "Describe this image:",
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAAXNSR0IArs4c6QAAACVJREFUKFNj/KTO/J+BCMA4iBUyQX1A0I10VAizCj1oMdyISyEAFoQbHwTcuS8AAAAASUVORK5CYII="
}

async def main():
    result = await kernel.invoke_prompt(
        prompt=prompt_config.template,
        request=arguments["request"],
        imageData=arguments["imageData"],
        service_id="chat_completion",
        template_format="handlebars"
    )
    print("Kernel result:", result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

يعد استخدام قوالب المقابض مع Kernel الدلالي طريقة بسيطة وفعالة لإنشاء مطالبات ديناميكية لتطبيقاتك. يعد بناء جملة Handlebars سهل الاستخدام ويسمح لك بتضمين المتغيرات وإدارة المطالبات في YAML لتنظيم أفضل ودمج الوظائف المستندة إلى الذكاء الاصطناعي بسلاسة. يجعل هذا الأسلوب مطالباتك أكثر مرونة وقابلية لإعادة الاستخدام وأسهل في الصيانة.

يمكنك معرفة المزيد حول قوالب مطالبات Handlebars من "دليل المقابض".