练习 - 创建本机函数

10 分钟

在本练习中，你将创建一个本机函数，该函数将歌曲添加到用户的“最近播放”列表中。稍后，可以使用最近播放的歌曲列表来提供自定义的建议。现在就开始吧！

准备开发环境

在这些练习中，你可以使用初学者项目。使用以下步骤设置初学者项目：

重要

必须安装 Visual Studio Code 和 .NET Framework 8.0 才能完成这些步骤。可能还需要安装 Visual Studio Code C# 开发工具包扩展。

打开 Visual Studio Code。
在 Visual Studio Code 的“开始”部分下，选择“克隆 Git 存储库”。
在 URL 栏中，输入 https://github.com/MicrosoftLearning/MSLearn-Develop-AI-Agents-with-Azure-OpenAI-and-Semantic-Kernel-SDK.git
在文件资源管理器中，在易于查找和记住的位置（例如桌面中的文件夹）中创建新文件夹。
单击“选择为存储库目标”按钮。

需要登录到 GitHub 才能成功克隆项目。
在 Visual Studio Code 中打开项目。
在资源管理器中，右键单击 M03-give-your-ai-agent-skills/M03-Project 文件夹，然后单击“在集成终端中打开”。
展开 M03-give-your-ai-agent-skills/M03-Project 文件夹。

此时应会看到“Program.cs”文件。
打开 Program.cs 文件，然后使用 Azure OpenAI 服务部署名称、API 密钥、终结点来更新以下变量。
```
string yourDeploymentName = "";
string yourEndpoint = "";
string yourKey = "";
```

现在，你已准备好开始进行练习。祝你好运！

创建音乐库插件

在“Project”目录中创建新文件夹并将其命名为“Plugins”。
在“Plugins”文件夹中，创建新文件“MusicLibrary.cs”

输入以下代码：

using System.ComponentModel;
using System.Text.Json;
using System.Text.Json.Nodes;
using Microsoft.SemanticKernel;

public class MusicLibraryPlugin
{
    [KernelFunction, 
    Description("Get a list of music recently played by the user")]
    public static string GetRecentPlays()
    {
        string dir = Directory.GetCurrentDirectory();
        string content = File.ReadAllText($"{dir}/data/recentlyplayed.txt");
        return content;
    }
}

在此代码中，你使用 KernelFunction 修饰器来声明本机函数。你还使用 Description 修饰器来添加函数功能说明。现在，你可以假设用户的最近播放歌曲的列表存储在名为“recentlyplayed.txt”的文本文件中。接下来可以添加用于将歌曲添加到列表中的代码。

将以下代码添加到 MusicLibraryPlugin 类：

[KernelFunction, Description("Add a song to the recently played list")]
public static string AddToRecentlyPlayed(
    [Description("The name of the artist")] string artist, 
    [Description("The title of the song")] string song, 
    [Description("The song genre")] string genre)
{
    // Read the existing content from the file
    string filePath = "data/recentlyplayed.txt";
    string jsonContent = File.ReadAllText(filePath);
    var recentlyPlayed = (JsonArray) JsonNode.Parse(jsonContent);

    var newSong = new JsonObject
    {
        ["title"] = song,
        ["artist"] = artist,
        ["genre"] = genre
    };

    recentlyPlayed.Insert(0, newSong);
    File.WriteAllText(filePath, JsonSerializer.Serialize(recentlyPlayed,
        new JsonSerializerOptions { WriteIndented = true }));

    return $"Added '{song}' to recently played";
}

在此代码中，你创建一个函数，接受“艺术家”、“歌曲”和“流派”作为字符串。除了函数的 Description 之外，你还添加输入变量的说明。此代码从文件中读取现有内容，对其进行分析，然后将新歌曲添加到列表中。已更新的列表此后会写回到文件中。接下来，你将使用一些示例数据创建“recentlyplayed.txt”文件。

在“M03-Project”文件夹中创建新文件夹“data”。

在“data”文件夹中创建新文件“recentlyplayed.txt”，然后粘贴以下内容：

[
    {
        "title": "Loanh Quanh",
        "artist": "Ly Hoa",
        "genre": "indie, folk"
    },
    {
        "title": "Kalam Eineh",
        "artist": "Yasemin",
        "genre": "pop, Egyptian pop"
    },
    {
        "title": "I Miss You",
        "artist": "Chishin",
        "genre": "hiphop, rap"
    },
    {
        "title": "4EVER",
        "artist": "Gaby",
        "genre": "alternative, indie"
    }
]

接下来，让我们通过导入和调用新插件来修改列表。

使用以下代码更新“Program.cs”文件：

var kernel = builder.Build();
kernel.ImportPluginFromType<MusicLibraryPlugin>();

var result = await kernel.InvokeAsync(
    "MusicLibraryPlugin", 
    "AddToRecentlyPlayed", 
    new() {
        ["artist"] = "Tiara", 
        ["song"] = "Danse", 
        ["genre"] = "French pop, electropop, pop"
    }
);

Console.WriteLine(result);

在此代码中，使用 ImportPluginFromType 将 MusicLibraryPlugin 导入到内核。然后，使用要使用的插件的名称和要调用的函数调用 InvokeAsync。还可以传入艺术家、歌曲和流派作为参数。

通过在终端中输入 dotnet run 来运行代码。

应会看到以下输出：
```
Added 'Danse' to recently played
```
打开“recentlyplayed.txt”，应会看到添加到列表中的新歌曲。干得漂亮!

练习 - 创建本机函数

准备开发环境

创建音乐库插件

反馈