Exercício: criar um conversor de moeda

  • 10 minutos

Para este exercício, você criará um plug-in que permite ao usuário converter os valores monetários de uma moeda para outra. Como o modelo não pode acessar a Internet para determinar a taxa de câmbio atual, você precisa fornecer as taxas de câmbio em seu plug-in. Neste exercício, você usará um arquivo currencies.txt existente para fornecer as taxas de câmbio.

Importante

Você precisa concluir as instruções de Instalação na unidade anterior, Preparar, antes de iniciar este exercício.

Criar uma função nativa

Nesta tarefa, crie uma função nativa que pode converter um valor de uma moeda base para uma moeda de destino.

  1. Crie um novo arquivo chamado CurrencyConverter.cs na pasta Plugins/ConvertCurrency

  2. No arquivo CurrencyConverter.cs, adicione o seguinte código para criar uma função de plug-in:

    using AITravelAgent;

class CurrencyConverter
{
    [KernelFunction, 
    Description("Convert an amount from one currency to another")]
    public static string ConvertAmount()
    {
        var currencyDictionary = Currency.Currencies;
    }
}

    Nesse código, use o decorador KernelFunction para declarar sua função nativa. Você também usará o decorador Description para adicionar uma descrição do que a função faz. Você pode usar Currency.Currencies para obter um dicionário de moedas e suas taxas de câmbio. Em seguida, adicione alguma lógica para converter um determinado valor de uma moeda para outra.

  3. Modifique sua função ConvertAmount com o seguinte código:

    [KernelFunction, Description("Convert an amount from one currency to another")]
public static string ConvertAmount(
    [Description("The target currency code")] string targetCurrencyCode, 
    [Description("The amount to convert")] string amount, 
    [Description("The starting currency code")] string baseCurrencyCode)
{
    var currencyDictionary = Currency.Currencies;

    Currency targetCurrency = currencyDictionary[targetCurrencyCode];
    Currency baseCurrency = currencyDictionary[baseCurrencyCode];

    if (targetCurrency == null)
    {
        return targetCurrencyCode + " was not found";
    }
    else if (baseCurrency == null)
    {
        return baseCurrencyCode + " was not found";
    }
    else
    {
        double amountInUSD = Double.Parse(amount) * baseCurrency.USDPerUnit;
        double result = amountInUSD * targetCurrency.UnitsPerUSD;
        return @$"${amount} {baseCurrencyCode} is approximately 
            {result.ToString("C")} in {targetCurrency.Name}s ({targetCurrencyCode})";
    }
}

    Nesse código, use o dicionário Currency.Currencies para obter o objeto Currency para as moedas de destino e base. Em seguida, use o objeto Currency para converter o valor da moeda base para a moeda de destino. Por fim, retorne uma cadeia de caracteres com o valor convertido. Em seguida, vamos testar seu plug-in.

    Observação

    Ao usar o SDK do Kernel Semântico em seus próprios projetos, não é necessário codificar os dados em arquivos se você tiver acesso a APIs RESTful. Em vez disso, você pode usar o plug-in Plugins.Core.HttpClient para recuperar dados de APIs.

  4. No arquivo Program.cs, importe e invoque sua nova função de plug-in com o seguinte código:

    kernel.ImportPluginFromType<CurrencyConverter>();
kernel.ImportPluginFromType<ConversationSummaryPlugin>();
var prompts = kernel.ImportPluginFromPromptDirectory("Prompts");

var result = await kernel.InvokeAsync("CurrencyConverter", 
    "ConvertAmount", 
    new() {
        {"targetCurrencyCode", "USD"}, 
        {"amount", "52000"}, 
        {"baseCurrencyCode", "VND"}
    }
);

Console.WriteLine(result);

    Nesse código, use o método ImportPluginFromType para importar seu plug-in. Em seguida, use o método InvokeAsync para invocar sua função de plug-in. O método InvokeAsync recebe o nome do plug-in, o nome da função e um dicionário de parâmetros. Por fim, imprima o resultado no console. Em seguida, execute o código para ter certeza de que está funcionando.

  5. Insira dotnet run no terminal. A seguinte saída deve ser exibida:

    $52000 VND is approximately $2.13 in US Dollars (USD)

    Agora que o plug-in está funcionando corretamente, vamos criar um prompt de linguagem natural que possa detectar quais moedas e valores o usuário deseja converter.

Criar um prompt

Nesta tarefa, crie um prompt que analise a entrada do usuário para identificar a moeda de destino, a moeda base e o valor a ser convertido.

  1. Crie uma nova pasta chamada GetTargetCurrencies na pasta Prompts

  2. Na pasta GetTargetCurrencies, crie um novo arquivo chamado config.json

  3. Insira o seguinte texto no arquivo config.json:

    {
    "schema": 1,
    "type": "completion",
    "description": "Identify the target currency, base currency, and amount to convert",
    "execution_settings": {
        "default": {
            "max_tokens": 800,
            "temperature": 0
        }
    },
    "input_variables": [
        {
            "name": "input",
            "description": "Text describing some currency amount to convert",
            "required": true
        }
    ]
}

  4. Na pasta GetTargetCurrencies, crie um novo arquivo chamado skprompt.txt

  5. Insira o texto a seguir no arquivo skprompt.txt:

    <message role="system">Identify the target currency, base currency, and 
amount from the user's input in the format target|base|amount</message>

For example: 

<message role="user">How much in GBP is 750.000 VND?</message>
<message role="assistant">GBP|VND|750000</message>

<message role="user">How much is 60 USD in New Zealand Dollars?</message>
<message role="assistant">NZD|USD|60</message>

<message role="user">How many Korean Won is 33,000 yen?</message>
<message role="assistant">KRW|JPY|33000</message>

<message role="user">{{$input}}</message>
<message role="assistant">target|base|amount</message>

Verifique seu trabalho

Nesta tarefa, execute seu aplicativo e verifique se o código está funcionando corretamente.

  1. Teste o novo prompt atualizando o arquivo Program.cs com o seguinte código:

    kernel.ImportPluginFromType<CurrencyConverter>();
var prompts = kernel.ImportPluginFromPromptDirectory("Prompts");

var result = await kernel.InvokeAsync(prompts["GetTargetCurrencies"],
    new() {
        {"input", "How many Australian Dollars is 140,000 Korean Won worth?"}
    }
);

Console.WriteLine(result);

  2. Insira dotnet run no terminal. A seguinte saída deve ser exibida:

    AUD|KRW|140000

    Observação

    Se o código não produzir a saída esperada, você poderá revisar o código na pasta Solução. Talvez seja necessário ajustar o prompt no arquivo skprompt.txt para produzir resultados mais exatos.

Agora você tem um plug-in que pode converter um valor de uma moeda para outra e um prompt que pode ser usado para analisar a entrada do usuário em um formato que a função ConvertAmount pode usar. No próximo exercício, você poderá usar a intenção do usuário para executar suas funções.