Aracılığıyla paylaş

OpenAPI belirtimlerinden eklenti ekleme

Genellikle bir kuruluşta, gerçek iş gerçekleştiren bir dizi API'niz vardır. Bunlar, insanların etkileşimde olduğu diğer otomasyon hizmetleri veya güç ön uç uygulamaları tarafından kullanılabilir. Anlam Çekirdeği'nde, aracılarınızın da kullanabilmesi için bu API'leri eklentilerle tamamen aynı şekilde ekleyebilirsiniz.

Örnek OpenAPI belirtimi

Örneğin ampullerin durumunu değiştirmenize olanak tanıyan bir API alın. Bu API için Swagger Belirtimi veya yalnızca Swagger olarak bilinen OpenAPI belirtimi şöyle görünebilir:

{
   "openapi": "3.0.1",
   "info": {
      "title": "Light API",
      "version": "v1"
   },
   "paths": {
      "/Light": {
         "get": {
            "summary": "Retrieves all lights in the system.",
            "operationId": "get_all_lights",
            "responses": {
               "200": {
                  "description": "Returns a list of lights with their current state",
                  "application/json": {
                     "schema": {
                        "type": "array",
                        "items": {
                              "$ref": "#/components/schemas/LightStateModel"
                        }
                     }
                  }
               }
            }
         }
      },
      "/Light/{id}": {
         "post": {
               "summary": "Changes the state of a light.",
               "operationId": "change_light_state",
               "parameters": [
                  {
                     "name": "id",
                     "in": "path",
                     "description": "The ID of the light to change.",
                     "required": true,
                     "style": "simple",
                     "schema": {
                           "type": "string"
                     }
                  }
               ],
               "requestBody": {
                  "description": "The new state of the light and change parameters.",
                  "content": {
                     "application/json": {
                           "schema": {
                              "$ref": "#/components/schemas/ChangeStateRequest"
                           }
                     }
                  }
               },
               "responses": {
                  "200": {
                     "description": "Returns the updated light state",
                     "content": {
                           "application/json": {
                              "schema": {
                                 "$ref": "#/components/schemas/LightStateModel"
                              }
                           }
                     }
                  },
                  "404": {
                     "description": "If the light is not found"
                  }
               }
         }
      }
   },
   "components": {
      "schemas": {
         "ChangeStateRequest": {
               "type": "object",
               "properties": {
                  "isOn": {
                     "type": "boolean",
                     "description": "Specifies whether the light is turned on or off.",
                     "nullable": true
                  },
                  "hexColor": {
                     "type": "string",
                     "description": "The hex color code for the light.",
                     "nullable": true
                  },
                  "brightness": {
                     "type": "integer",
                     "description": "The brightness level of the light.",
                     "format": "int32",
                     "nullable": true
                  },
                  "fadeDurationInMilliseconds": {
                     "type": "integer",
                     "description": "Duration for the light to fade to the new state, in milliseconds.",
                     "format": "int32",
                     "nullable": true
                  },
                  "scheduledTime": {
                     "type": "string",
                     "description": "Use ScheduledTime to synchronize lights. It's recommended that you asynchronously create tasks for each light that's scheduled to avoid blocking the main thread.",
                     "format": "date-time",
                     "nullable": true
                  }
               },
               "additionalProperties": false,
               "description": "Represents a request to change the state of the light."
         },
         "LightStateModel": {
               "type": "object",
               "properties": {
                  "id": {
                     "type": "string",
                     "nullable": true
                  },
                  "name": {
                     "type": "string",
                     "nullable": true
                  },
                  "on": {
                     "type": "boolean",
                     "nullable": true
                  },
                  "brightness": {
                     "type": "integer",
                     "format": "int32",
                     "nullable": true
                  },
                  "hexColor": {
                     "type": "string",
                     "nullable": true
                  }
               },
               "additionalProperties": false
         }
      }
   }
}

Bu belirtim, API'yi ve bununla nasıl etkileşim kurulduğunu anlamak için yapay zekanın ihtiyaç duyduğu her şeyi sağlar. API iki uç nokta içerir: biri tüm ışıkları almak için, diğeri de ışığın durumunu değiştirmek için. Ayrıca aşağıdakileri de sağlar:

  • Uç noktalar ve parametreleri için anlamsal açıklamalar
  • Parametrelerin türleri
  • Beklenen yanıtlar

Yapay zeka aracısı bu belirtimi anlayabileceğinden aracıya eklenti olarak ekleyebilirsiniz.

Semantic Kernel, OpenAPI sürüm 2.0 ve 3.0'ı destekler ve sürüm 3.1 belirtimlerini sürüm 3.0'a düşürerek barındırmayı hedefler.

Bahşiş

Mevcut OpenAPI belirtimleriniz varsa, yapay zekanın bunları anlamasını kolaylaştırmak için değişiklikler yapmanız gerekebilir. Örneğin, açıklamalarda rehberlik sağlamanız gerekebilir. OpenAPI belirtimlerinizi yapay zeka kullanımına uygun hale getirme hakkında daha fazla ipucu için bkz. OpenAPI eklentileri eklemeye yönelik ipuçları ve püf noktaları.

OpenAPI eklentisini ekleme

Birkaç kod satırıyla OpenAPI eklentisini aracınıza ekleyebilirsiniz. Aşağıdaki kod parçacığı, yukarıdaki OpenAPI belirtiminden light eklentisinin nasıl ekleneceğini gösterir:

await kernel.ImportPluginFromOpenApiAsync(
   pluginName: "lights",
   uri: new Uri("https://example.com/v1/swagger.json"),
   executionParameters: new OpenApiFunctionExecutionParameters()
   {
      // Determines whether payload parameter names are augmented with namespaces.
      // Namespaces prevent naming conflicts by adding the parent parameter name
      // as a prefix, separated by dots
      EnablePayloadNamespacing = true
   }
);

Anlam Çekirdeği ile, URL, dosya veya akış gibi çeşitli kaynaklardan OpenAPI eklentileri ekleyebilirsiniz. Buna ek olarak, eklentiler bir kez oluşturulabilir ve birden çok çekirdek örneğinde veya aracıda yeniden kullanılabilir.

// Create the OpenAPI plugin from a local file somewhere at the root of the application
KernelPlugin plugin = await OpenApiKernelPluginFactory.CreateFromOpenApiAsync(
    pluginName: "lights",
    filePath: "path/to/lights.json"
);

// Add the plugin to the kernel
Kernel kernel = new Kernel();
kernel.Plugins.Add(plugin);

await kernel.add_plugin_from_openapi(
   plugin_name="lights",
   openapi_document_path="https://example.com/v1/swagger.json",
   execution_settings=OpenAPIFunctionExecutionParameters(
         # Determines whether payload parameter names are augmented with namespaces.
         # Namespaces prevent naming conflicts by adding the parent parameter name
         # as a prefix, separated by dots
         enable_payload_namespacing=True,
   ),
)

String yaml = EmbeddedResourceLoader.readFile("petstore.yaml", ExamplePetstoreImporter.class);

KernelPlugin plugin = SemanticKernelOpenAPIImporter
   .builder()
   .withPluginName("petstore")
   .withSchema(yaml)
   .withServer("http://localhost:8090/api/v3")
   .build();

Kernel kernel = ExampleOpenAPIParent.kernelBuilder()
   .withPlugin(plugin)
   .build();

Daha sonra, eklentiyi yerel bir eklentiymiş gibi aracınızda kullanabilirsiniz.

OpenAPI eklenti parametrelerini işleme

Anlam Çekirdeği, OpenAPI belgelerinde tanımlanan tüm parametreler için ad, açıklama, tür ve şema gibi meta verileri otomatik olarak ayıklar. Bu meta veriler, her OpenAPI işlemi için KernelFunction.Metadata.Parameters özelliğinde depolanır ve işlev çağrıları için doğru bağımsız değişkenleri oluşturma amacıyla, istemle birlikte LLM'ye verilir.

Varsayılan olarak, özgün parametre adı LLM'ye sağlanır ve Semantic Kernel tarafından LLM'nin sağladığı bağımsız değişkenler listesinde karşılık gelen bağımsız değişkeni aramak üzere kullanılır. Ancak, OpenAPI eklentisinin aynı ada sahip birden çok parametreye sahip olduğu durumlar olabilir. LLM'ye bu parametrenin meta verilerinin sağlanması, karışıklığa yol açarak LLM'nin fonksiyon çağrılarında doğru argümanları oluşturmasını engelleyebilir.

Ayrıca, her OpenAPI işlemi için benzersiz olmayan parametre adlara izin vermeyen bir çekirdek işlevi oluşturulduğundan, böyle bir eklentinin eklenmesi bazı işlemlerin kullanım dışı olmasına neden olabilir. Özel olarak, benzersiz olmayan parametre adlarına sahip işlemler atlanır ve buna karşılık gelen bir uyarı günlüğe kaydedilir. Çekirdek işlevine aynı ada sahip birden çok parametre eklemek mümkün olsa bile, bu durum bağımsız değişken seçimi işleminde belirsizliğe neden olabilir.

Tüm bunları göz önünde bulundurarak Anlam Çekirdeği, benzersiz olmayan parametre adlarına sahip eklentileri yönetmek için bir çözüm sunar. API'nin kendisi değiştirilemediğinde, ister üçüncü taraf bir hizmet isterse eski bir sistem olsun, bu çözüm özellikle kullanışlıdır.

Aşağıdaki kod parçacığı, OpenAPI eklentisinde benzersiz olmayan parametre adlarının nasıl işleneceğini gösterir. change_light_state işleminin mevcut "id" parametresiyle aynı ada sahip ek bir parametresi varsa (özellikle, ışığın kimliğini temsil eden geçerli "id" ile birlikte bir oturum kimliğini temsil etmek için) aşağıda gösterildiği gibi işlenebilir:

OpenApiDocumentParser parser = new();

using FileStream stream = File.OpenRead("path/to/lights.json");

// Parse the OpenAPI document
RestApiSpecification specification = await parser.ParseAsync(stream);

// Get the change_light_state operation
RestApiOperation operation = specification.Operations.Single(o => o.Id == "change_light_state");

// Set the 'lightId' argument name to the 'id' path parameter that represents the ID of the light
RestApiParameter idPathParameter = operation.Parameters.Single(p => p.Location == RestApiParameterLocation.Path && p.Name == "id");
idPathParameter.ArgumentName = "lightId";

// Set the 'sessionId' argument name to the 'id' header parameter that represents the session ID
RestApiParameter idHeaderParameter = operation.Parameters.Single(p => p.Location == RestApiParameterLocation.Header && p.Name == "id");
idHeaderParameter.ArgumentName = "sessionId";

// Import the transformed OpenAPI plugin specification
kernel.ImportPluginFromOpenApi(pluginName: "lights", specification: specification);

Bu kod parçacığı, OpenAPI belgesini ayrıştırmak ve belgeyi temsil eden OpenApiDocumentParser model nesnesine erişmek için RestApiSpecification sınıfını kullanır. Parametrelere bağımsız değişken adları atar ve dönüştürülen OpenAPI eklenti belirtimini çekirdeğe aktarır. Anlam Çekirdeği, özgün adlar yerine LLM'ye bağımsız değişken adları sağlar ve bunları LLM tarafından sağlanan listede karşılık gelen bağımsız değişkenleri aramak için kullanır.

OpenAPI işlemi çağrılırken bağımsız değişken adlarının özgün adların yerine kullanılmadığını unutmayın. Yukarıdaki örnekte, yol parametresindeki 'id' parametresi, LLM tarafından 'lightId' bağımsız değişkeni için döndürülen bir değerle değiştirilecektir. Aynı durum 'id' üst bilgi parametresi için de geçerlidir; LLM tarafından 'sessionId' bağımsız değişkeni için döndürülen değer, 'id' adlı üst bilgi için değer olarak kullanılır.

OpenAPI eklentileri yükünü işleme

OpenAPI eklentileri POST, PUT veya PATCH işlemlerini kullanarak sistemin durumunu değiştirebilir. Bu işlemler genellikle isteğe bir yük eklenmesini gerektirir.

Semantik Çekirdek, senaryonuza ve API gereksinimlerinize bağlı olarak OpenAPI eklentileri için yük işlemeyi yönetmek için birkaç seçenek sunar.

Dinamik yük yapısı

Dinamik yük oluşturma, OpenAPI işlemlerinin yüklerinin LLM tarafından sağlanan yük şemasına ve bağımsız değişkenlerine göre dinamik olarak oluşturulmasını sağlar. Bu özellik varsayılan olarak etkindir, ancak bir OpenAPI eklentisi eklerken özelliği EnableDynamicPayload nesne içinde false olarak ayarlanarak OpenApiFunctionExecutionParameters devre dışı bırakılabilir.

Örneğin, aşağıdaki gibi yapılandırılmış bir yük gerektiren change_light_state işlemini göz önünde bulundurun:

{
   "isOn": true,
   "hexColor": "#FF0000",
   "brightness": 100,
   "fadeDurationInMilliseconds": 500,
   "scheduledTime": "2023-07-12T12:00:00Z"
}

Işığın durumunu değiştirmek ve yük özelliklerine ilişkin değerleri almak için Anlam Çekirdeği, LLM'ye işlemin meta verilerini sağlayarak bunun nedenini belirlemesini sağlar:

{
    "name":"lights-change-light-state",
    "description": "Changes the state of a light.",
    "parameters":[
        { "name": "id", "schema": {"type":"string", "description": "The ID of the light to change.", "format":"uuid"}},
        { "name": "isOn", "schema": { "type": "boolean", "description": "Specifies whether the light is turned on or off."}},
        { "name": "hexColor", "schema": { "type": "string", "description": "Specifies whether the light is turned on or off."}},
        { "name": "brightness", "schema": { "type":"string", "description":"The brightness level of the light.", "enum":["Low","Medium","High"]}},
        { "name": "fadeDurationInMilliseconds", "schema": { "type":"integer", "description":"Duration for the light to fade to the new state, in milliseconds.", "format":"int32"}},
        { "name": "scheduledTime", "schema": {"type":"string", "description":"The time at which the change should occur.", "format":"date-time"}},
    ]
}

Semantik Çekirdek, LLM'ye işlem meta verileri sağlamaya ek olarak aşağıdaki adımları gerçekleştirir:

  1. LLM çağrısını OpenAPI işlemine yönlendirerek, yükü şemaya uygun ve LLM özellik değerleriyle belirlenen şekilde oluşturun.
  2. Yükü içeren HTTP isteğini API'ye gönderin.

Dinamik yük oluşturma sınırlamaları

Dinamik yük yapısı, görece basit yük yapıları olan API'ler için en etkilidir. Aşağıdaki özellikleri sergileyen API yükleri için güvenilir bir şekilde çalışmayabilir veya hiç çalışmayabilir.

  • Özelliklerin konumundan bağımsız olarak benzersiz olmayan özellik adlarına sahip veri yükleri. Örneğin, biri gönderici nesne, diğeri alıcı nesne için adlandırılan iki özellik id - json { "sender": { "id": ... }, "receiver": { "id": ... }}
  • oneOf, anyOfve allOfbileşik anahtar sözcüklerinden herhangi birini kullanan yük şemaları.
  • Özyinelemeli başvurular içeren yük şemaları. Örneğin, json { "parent": { "child": { "$ref": "#parent" } } }

Benzersiz olmayan özellik adlarıyla yükleri işlemek için aşağıdaki alternatifleri göz önünde bulundurun:

  • Her benzersiz olmayan özellik için, AçıkAPI eklenti parametrelerinin ele alınışı bölümünde anlatılan yönteme benzer bir yöntem kullanarak benzersiz bir bağımsız değişken adı sağlayın.
  • Adlandırma çakışmalarını önlemek için ad alanlarını kullanın; bu, sonraki bölümde Payload alan adı kullanımıbaşlığı altında açıklanmıştır.
  • Dinamik yük oluşturmayı devre dışı bırakın ve Yük parametresi bölümünde açıklandığı gibi LLM'nin yükü şemasına göre oluşturmasına izin verin.

Yük şemaları herhangi bir oneOf, anyOf veya allOf bileşik anahtar kelime ya da özyinelemeli başvuru kullanıyorsa, dinamik yük oluşturmayı devre dışı bırakmayı ve Yük parametresi bölümünde açıklandığı gibi yükü şemasına göre LLM'nin oluşturmasına izin vermeyi düşünebilirsiniz.

oneOf ve anyOf Anahtar Sözcükleriyle ilgili not

anyOf ve oneOf anahtar sözcükleri, bir yükün birden çok şema tarafından tanımlanan özelliklerden oluşabileceğini varsayar. anyOf anahtar sözcüğü, yükün bir veya daha fazla şemada tanımlanan özellikleri içermesine izin verirken, oneOf yükü sağlanan çok sayıda şema arasında yalnızca bir şemanın özelliklerini içerecek şekilde kısıtlar. Daha fazla bilgi için oneOf ve anyOf ile ilgili Swagger belgelerine başvurabilirsiniz.

Yük yapısına alternatifler sunan hem anyOf hem de oneOf anahtar sözcüklerle, bu anahtar sözcüklerle yükleri tanımlayan işlemleri çağırırken çağıranın hangi alternatifi seçeceğini tahmin etmek mümkün değildir. Örneğin, çağıranın Bir Köpek veya Kedi nesnesiyle veya anyOf örneklerde oneOf açıklanan PetByAge ve PetByType şemalarındaki bazı veya belki de tüm özelliklerden oluşan bir nesneyle bir işlemi çağırıp çağırmayacağını önceden belirlemek mümkün değildir. Sonuç olarak, Anlam Çekirdeği'nin bu tür işlemler için eklenti işlevi oluşturmak için kullanabileceği önceden bilinen bir parametre kümesi olmadığından, Anlam Çekirdeği işlemden çok sayıda olası alternatifi açıklayan bir şemaya sahip olan tek bir yük parametresine sahip bir işlev oluşturur ve yük oluşturma işlemini çağırana boşaltılır: LLM veya çağırma kodu işlevi çağırmak için kullanılabilir alternatiflerden birini bilmek için tüm bağlamı olması gerekir.

Yük ad alanı

Payload namespacing, OpenAPI eklentisi yüklerindeki benzersiz olmayan özellik adlarından dolayı oluşabilecek adlandırma çakışmalarını önlemeye yardımcı olur.

Ad alanı belirleme etkinleştirildiğinde, Semantic Kernel, LLM'ye artırılmış özellik adlarını içeren OpenAPI işlem meta verilerini sağlar. Bu genişletilmiş adlar, ebeveyn özellik adı alt özellik adlarına noktayla ayrılmış bir ön ek olarak eklenmek suretiyle oluşturulur.

Örneğin, change_light_state işlemi offTimer özelliği olan iç içe geçmiş bir scheduledTime nesnesi içermiş olsaydı:

{
  "isOn": true,
  "hexColor": "#FF0000",
  "brightness": 100,
  "fadeDurationInMilliseconds": 500,
  "scheduledTime": "2023-07-12T12:00:00Z",
  "offTimer": {
      "scheduledTime": "2023-07-12T12:00:00Z"
  }
}

Semantik Çekirdek, LLM'ye aşağıdaki özellik adlarını içeren işlem için meta veriler sağlardı:

{
    "name":"lights-change-light-state",
    "description": "Changes the state of a light.",
    "parameters":[
        { "name": "id", "schema": {"type":"string", "description": "The ID of the light to change.", "format":"uuid"}},
        { "name": "isOn", "schema": { "type": "boolean", "description": "Specifies whether the light is turned on or off."}},
        { "name": "hexColor", "schema": { "type": "string", "description": "Specifies whether the light is turned on or off."}},
        { "name": "brightness", "schema": { "type":"string", "description":"The brightness level of the light.", "enum":["Low","Medium","High"]}},
        { "name": "fadeDurationInMilliseconds", "schema": { "type":"integer", "description":"Duration for the light to fade to the new state, in milliseconds.", "format":"int32"}},
        { "name": "scheduledTime", "schema": {"type":"string", "description":"The time at which the change should occur.", "format":"date-time"}},
        { "name": "offTimer.scheduledTime", "schema": {"type":"string", "description":"The time at which the device will be turned off.", "format":"date-time"}},
    ]
}

LLM'ye artırılmış özellik adlarıyla işlem meta verileri sağlamanın yanı sıra Anlam Çekirdeği aşağıdaki adımları gerçekleştirir:

  1. OpenAPI işlemi için LLM çağrısını işleyin ve genişletilmiş özellik adlarını kullanarak, gerekirse özgün özellik adlarına geri dönerek LLM tarafından sağlananlar arasında yük içerisindeki tüm özelliklere uygun olan argümanları bulun.
  2. Özgün özellik adlarını anahtar olarak ve çözümlenen bağımsız değişkenleri değer olarak kullanarak yükü oluşturma.
  3. Http isteğini, api'ye, yüklenen yükle birlikte gönderin.

Varsayılan olarak, yük isimlendirme alanı seçeneği devre dışıdır. Bir OpenAPI eklentisi eklerken EnablePayloadNamespacing'ü etkinleştirmek için true nesnesinde OpenApiFunctionExecutionParameters özelliği olarak ayarlanabilir.

await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "lights",
    uri: new Uri("https://example.com/v1/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        EnableDynamicPayload = true, // Enable dynamic payload construction. This is enabled by default.
        EnablePayloadNamespacing = true // Enable payload namespacing
    });

Bilgi

Bu EnablePayloadNamespace seçenek yalnızca dinamik yük yapısı da etkinleştirildiğinde geçerlilik kazanır; aksi takdirde hiçbir etkisi olmaz.

Yük parametresi

Semantik Çekirdek, payload parametresini kullanarak LLM tarafından oluşturulan yüklerle çalışabilir. Bu, yük şeması karmaşık olduğunda ve benzersiz olmayan özellik adları içerdiğinde yararlıdır; bu da Anlam Çekirdeği'nin yükü dinamik olarak oluşturmasını mümkün kılamaz. Böyle durumlarda LLM'nin şemayı anlama ve geçerli bir yük oluşturma yeteneğine güveneceksiniz. Gibi gpt-4o son modeller geçerli JSON yükleri oluşturmada etkilidir.

payload parametresini etkinleştirmek için, bir OpenAPI eklentisi eklerken EnableDynamicPayload nesnesinin içinde false özelliğini OpenApiFunctionExecutionParameters olarak ayarlayın.

await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "lights",
    uri: new Uri("https://example.com/v1/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        EnableDynamicPayload = false, // Disable dynamic payload construction
    });

Payload parametresi etkinleştirildiğinde Anlam Çekirdeği, LLM'ye yükün şemalarını ve content_type parametrelerini içeren işlem meta verilerini sağlayarak LLM'nin yük yapısını anlamasına ve buna göre oluşturmasına olanak tanır:

{
    "name": "payload",
    "schema":
    {
        "type": "object",
        "properties": {
            "isOn": {
                "type": "boolean",
                "description": "Specifies whether the light is turned on or off."
            },
            "hexColor": {
                "type": "string",
                "description": "The hex color code for the light.",
            },
            "brightness": {
                "enum": ["Low", "Medium", "High"],
                "type": "string",
                "description": "The brightness level of the light."
            },
            "fadeDurationInMilliseconds": {
                "type": "integer",
                "description": "Duration for the light to fade to the new state, in milliseconds.",
                "format": "int32"
            },
            "scheduledTime": {
                "type": "string",
                "description": "The time at which the change should occur.",
                "format": "date-time"
            }
        },
        "additionalProperties": false,
        "description": "Represents a request to change the state of the light."
    },
    {
        "name": "content_type",
        "schema":
        {
            "type": "string",
            "description": "Content type of REST API request body."
        }
    }
}

LLM'ye yük ve içerik türü parametreleri için şema ile işlem meta verilerini sağlamanın yanı sıra Anlam Çekirdeği aşağıdaki adımları gerçekleştirir:

  1. OpenAPI işlemine LLM çağrısını işler ve yük ile content_type parametreleri için LLM tarafından sağlanan bağımsız değişkenleri kullanır.
  2. Sağlanan yük ve içerik türüyle HTTP isteğini API'ye gönderin.

Sunucu temel url'si

Semantik Çekirdek OpenAPI eklentileri, API istekleri yaparken uç noktaların yollarının başına eklenmek üzere bir temel URL'ye ihtiyaç duyar. Bu temel URL OpenAPI belgesinde belirtilebilir, belge bir URL'den yüklenerek örtük olarak alınabilir veya eklenti çekirdeğe eklenirken sağlanabilir.

OpenAPI belgesinde belirtilen URL

OpenAPI v2 belgeleri, , schemesve host alanlarını kullanarak sunucu URL'sini basePathtanımlar:

{
   "swagger": "2.0",
   "host": "example.com",
   "basePath": "/v1",
   "schemes": ["https"]
   ...
}

Semantik Çekirdek sunucu URL'sini olarak https://example.com/v1oluşturur.

Buna karşılık, OpenAPI v3 belgeleri şu alanı kullanarak sunucu URL'sini servers tanımlar:

{
   "openapi": "3.0.1",
   "servers": [
      {
         "url": "https://example.com/v1"
      }
   ],
   ...
}

Anlam Çekirdeği, belgede belirtilen ilk sunucu URL'sini temel URL olarak kullanır: https://example.com/v1.

OpenAPI v3 ayrıca küme ayraçları tarafından belirtilen değişkenleri kullanarak parametreli sunucu URL'lerine izin verir:

{
   "openapi": "3.0.1",
   "servers": [
      {
         "url": "https://{environment}.example.com/v1",
         "variables": {
            "environment": {
               "default": "prod"
            }
         }
      }
   ],
   ...  
}

Bu durumda Semantik Çekirdek, değişken yer tutucusunun yerini, değişken için bağımsız değişken olarak sağlanan değerle veya bağımsız değişken sağlanmazsa varsayılan değerle değiştirerek şu URL'yi verir: https://prod.example.com/v1.

OpenAPI belgesi sunucu URL'si belirtmiyorsa, Anlam Çekirdeği OpenAPI belgesinin yüklendiği sunucunun temel URL'sini kullanır:

await kernel.ImportPluginFromOpenApiAsync(pluginName: "lights", uri: new Uri("https://api-host.com/swagger.json"));

Temel URL olacaktır https://api-host.com.

Sunucu URL'sini geçersiz kılma

Bazı durumlarda, OpenAPI belgesinde belirtilen sunucu URL'si veya belgenin yüklendiği sunucu OpenAPI eklentisini içeren kullanım örnekleri için uygun olmayabilir.

Semantik Çekirdek, çekirdekte OpenAPI eklentisini eklerken özel bir temel URL sağlayarak sunucu URL'sini geçersiz kılmanıza olanak tanır:

await kernel.ImportPluginFromOpenApiAsync(  
    pluginName: "lights",  
    uri: new Uri("https://example.com/v1/swagger.json"),  
    executionParameters: new OpenApiFunctionExecutionParameters()  
    {  
        ServerUrlOverride = new Uri("https://custom-server.com/v1")  
    });

Bu örnekte temel URL https://custom-server.com/v1, OpenAPI belgesinde belirtilen sunucu URL'sini ve belgenin yüklendiği sunucu URL'sini geçersiz kılarak olur.

Kimlik doğrulama

Rest API'lerin çoğu kaynaklarına erişmek için kimlik doğrulaması gerektirir. Anlam Çekirdeği, OpenAPI eklentileri için gereken çeşitli kimlik doğrulama yöntemlerini tümleştirmenizi sağlayan bir mekanizma sağlar.

Bu mekanizma, her API isteği öncesinde çağrılan bir kimlik doğrulama geri çağırma işlevine dayanır. Bu geri çağırma işlevinin, API'ye gönderilecek HTTP isteğini temsil eden HttpRequestMessage nesnesine erişimi vardır. bu nesneyi kullanarak isteğe kimlik doğrulaması kimlik bilgileri ekleyebilirsiniz. Kimlik bilgileri, API tarafından kullanılan kimlik doğrulama yöntemine bağlı olarak üst bilgi, sorgu parametresi veya istek gövdesine eklenebilir.

Çekirdeğe OpenAPI eklentisini eklerken bu geri çağırma işlevini kaydetmeniz gerekir. Aşağıdaki kod parçacığı, istekleri kimlik doğrulama için nasıl kaydedeceğinizi gösterir.

static Task AuthenticateRequestAsyncCallback(HttpRequestMessage request, CancellationToken cancellationToken = default)
{
    // Best Practices:  
    // * Store sensitive information securely, using environment variables or secure configuration management systems.  
    // * Avoid hardcoding sensitive information directly in your source code.  
    // * Regularly rotate tokens and API keys, and revoke any that are no longer in use.  
    // * Use HTTPS to encrypt the transmission of any sensitive information to prevent interception.  

    // Example of Bearer Token Authentication  
    // string token = "your_access_token";  
    // request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);  

    // Example of API Key Authentication  
    // string apiKey = "your_api_key";  
    // request.Headers.Add("X-API-Key", apiKey);    

    return Task.CompletedTask;  
}

await kernel.ImportPluginFromOpenApiAsync(  
    pluginName: "lights",  
    uri: new Uri("https://example.com/v1/swagger.json"),  
    executionParameters: new OpenApiFunctionExecutionParameters()  
    {  
        AuthCallback = AuthenticateRequestAsyncCallback
    });

BIR API tarafından desteklenen kimlik doğrulama şemalarının ayrıntılarına dinamik erişim gerektiren daha karmaşık kimlik doğrulama senaryoları için, bu bilgileri almak için belge ve işlem meta verilerini kullanabilirsiniz. Diğer ayrıntılar için bkz . Belge ve işlem meta verileri.

Yanıt içeriği okuma özelleştirmesi

Semantik Çekirdek, OpenAPI eklentilerinden http yanıtlarının içeriğini okumak ve bunları uygun .NET veri türlerine dönüştürmek için yerleşik bir mekanizmaya sahiptir. Örneğin, görüntü yanıtı bayt dizisi olarak, JSON veya XML yanıtı ise dize olarak okunabilir.

Ancak yerleşik mekanizmanın gereksinimleriniz için yetersiz olduğu durumlar olabilir. Örneğin, yanıt başka bir API'ye giriş olarak sağlanması için akış olarak okunması gereken büyük bir JSON nesnesi veya görüntüsü olduğunda. Böyle durumlarda, yanıt içeriğini dize veya bayt dizisi olarak okumak ve sonra bir akışa geri dönüştürmek verimsiz olabilir ve performans sorunlarına yol açabilir. Semantik Çekirdek, bu sorunu gidermek için özel bir içerik okuyucu sağlayarak yanıt içeriği okuma özelleştirmesine olanak tanır:

private static async Task<object?> ReadHttpResponseContentAsync(HttpResponseContentReaderContext context, CancellationToken cancellationToken)  
{  
    // Read JSON content as a stream instead of as a string, which is the default behavior.  
    if (context.Response.Content.Headers.ContentType?.MediaType == "application/json")  
    {  
        return await context.Response.Content.ReadAsStreamAsync(cancellationToken);  
    }  

    // HTTP request and response properties can be used to determine how to read the content.  
    if (context.Request.Headers.Contains("x-stream"))  
    {  
        return await context.Response.Content.ReadAsStreamAsync(cancellationToken);  
    }  

    // Return null to indicate that any other HTTP content not handled above should be read by the default reader.  
    return null;  
}  

await kernel.ImportPluginFromOpenApiAsync(  
    pluginName: "lights",  
    uri: new Uri("https://example.com/v1/swagger.json"),  
    executionParameters: new OpenApiFunctionExecutionParameters()  
    {  
        HttpResponseContentReader = ReadHttpResponseContentAsync  
    });

Bu örnekte yöntem, ReadHttpResponseContentAsync içerik türü application/json olduğunda veya istek özel üst bilgi x-streamiçerdiğinde HTTP yanıt içeriğini akış olarak okur. Yöntem, diğer içerik türleri için null döndürerek varsayılan içerik okuyucunun kullanılması gerektiğini belirtir.

Belge ve işlem meta verileri

Semantik Çekirdek, API bilgileri, güvenlik şemaları, işlem kimliği, açıklama, parametre meta verileri ve daha fazlası dahil olmak üzere OpenAPI belge ve işlem meta verilerini ayıklar. Özelliği aracılığıyla KernelFunction.Metadata.AdditionalParameters bu bilgilere erişim sağlar. Bu meta veriler, kimlik doğrulaması amacıyla api veya işlem hakkında ek bilgilerin gerekli olduğu senaryolarda yararlı olabilir:

static async Task AuthenticateRequestAsyncCallbackAsync(HttpRequestMessage request, CancellationToken cancellationToken = default)
{
    // Get the function context
    if (request.Options.TryGetValue(OpenApiKernelFunctionContext.KernelFunctionContextKey, out OpenApiKernelFunctionContext? functionContext))
    {
        // Get the operation metadata
        if (functionContext!.Function!.Metadata.AdditionalProperties["operation"] is RestApiOperation operation)
        {
            // Handle API key-based authentication
            IEnumerable<KeyValuePair<RestApiSecurityScheme, IList<string>>> apiKeySchemes = operation.SecurityRequirements.Select(requirement => requirement.FirstOrDefault(schema => schema.Key.SecuritySchemeType == "apiKey"));
            if (apiKeySchemes.Any())
            {
                (RestApiSecurityScheme scheme, IList<string> scopes) = apiKeySchemes.First();

                // Get the API key for the scheme and scopes from your app identity provider
                var apiKey = await this.identityProvider.GetApiKeyAsync(scheme, scopes);

                // Add the API key to the request headers
                if (scheme.In == RestApiParameterLocation.Header)
                {
                    request.Headers.Add(scheme.Name, apiKey);
                }
                else if (scheme.In == RestApiParameterLocation.Query)
                {
                    request.RequestUri = new Uri($"{request.RequestUri}?{scheme.Name}={apiKey}");
                }
                else
                {
                    throw new NotSupportedException($"API key location '{scheme.In}' is not supported.");
                }
            }

            // Handle other authentication types like Basic, Bearer, OAuth2, etc. For more information, see https://swagger.io/docs/specification/v3_0/authentication/
        }
    }
}

// Import the transformed OpenAPI plugin specification
var plugin = kernel.ImportPluginFromOpenApi(
    pluginName: "lights",
    uri: new Uri("https://example.com/v1/swagger.json"),
    new OpenApiFunctionExecutionParameters()
    {
        AuthCallback = AuthenticateRequestAsyncCallbackAsync
    });

await kernel.InvokePromptAsync("Test");

Bu örnekte, AuthenticateRequestAsyncCallbackAsync yöntem işlev bağlamından işlem meta verilerini okur ve kimlik doğrulama düzenini belirlemek için işlemin güvenlik gereksinimlerini ayıklar. Ardından uygulama kimliği sağlayıcısından şema ve kapsamlar için API anahtarını alır ve istek üst bilgilerine veya sorgu parametrelerine ekler.

Aşağıdaki tabloda, KernelFunction.Metadata.AdditionalParameters sözlüğünde mevcut olan meta veriler listelenmiştir.

Anahtar Tür Açıklama
Bilgi RestApiInfo Başlık, açıklama ve sürüm gibi API bilgileri.
işlem RestApiOperation Kimlik, açıklama, yol, yöntem gibi API işlemi ayrıntıları.
güvenlik IList<RestApiSecurityRequirement> API güvenlik gereksinimleri - tür, ad, parametre, vb.

OpenAPI eklentileri eklemeye yönelik ipuçları ve püf noktaları

OpenAPI belirtimleri genellikle insanlar için tasarlandığından, yapay zekanın anlamasını kolaylaştırmak için bazı değişiklikler yapmanız gerekebilir. Bunu yapmanıza yardımcı olacak bazı ipuçları ve püf noktaları şunlardır:

Tavsiye Açıklama
API belirtimlerinizi sürüm kontrolü altına alın Canlı bir API belirtimine bağlanmak yerine Swagger dosyanızı kaydetmeyi ve sürüm kontrolünü yapmayı göz önünde bulundurun. Bu, yapay zeka araştırmacılarınızın canlı API'yi etkilemeden yapay zeka aracısı tarafından kullanılan API belirtimini test etmelerini (ve değiştirmelerini) sağlar.
Uç nokta sayısını sınırlama API'nizdeki uç nokta sayısını sınırlamayı deneyin. Karmaşıklığı azaltmak için isteğe bağlı parametrelerle benzer işlevleri tek uç noktalarda birleştirin.
Uç noktalar ve parametreler için açıklayıcı adlar kullanın Uç noktalarınızın ve parametrelerinizin adlarının açıklayıcı ve kendiliğinden anlaşılır olduğundan emin olun. Bu, yapay zekanın kapsamlı açıklamalara gerek kalmadan amacını anlamasına yardımcı olur.
Tutarlı adlandırma kurallarını kullanma API'niz genelinde tutarlı adlandırma kurallarını koruyun. Bu, karışıklığı azaltır ve yapay zekanın API'nizin yapısını daha kolay öğrenmesine ve tahmin etmenize yardımcı olur.
API belirtimlerinizi basitleştirme OpenAPI belirtimleri genellikle çok ayrıntılıdır ve yapay zeka aracısının kullanıcıya yardımcı olması için gerekli olmayan birçok bilgiyi içerir. API ne kadar basit olursa, tanımlamak için o kadar az belirteç harcamanız ve yapay zekanın istek göndermesi gereken belirteç sayısı da o kadar az olur.
Dize parametrelerinden kaçının Mümkün olduğunda, API'nizde dize parametrelerini kullanmaktan kaçının. Bunun yerine, tamsayılar, boole'lar veya numaralandırmalar gibi daha özel türler kullanın. Bu, yapay zekanın API'yi daha iyi anlamasına yardımcı olur.
Açıklamalarda örnekler sunun İnsanlar Swagger dosyalarını kullanırken genellikle örnek istekler ve yanıtlar içeren Swagger kullanıcı arabirimini kullanarak API'yi test edebilir. Yapay zeka aracısı bunu gerçekleştiremediğinden, parametrelerin açıklamalarında örnekler sağlamayı göz önünde bulundurun.
Açıklamalarda diğer uç noktalara başvurma Genellikle, yapay zekalar benzer uç noktaları karıştırır. Yapay zekanın uç noktaları birbirinden ayırt etmelerine yardımcı olmak için açıklamalarda diğer uç noktalara başvurmayı göz önünde bulundurun. Örneğin, "Bu uç nokta uç noktaya benzer get_all_lights , ancak yalnızca tek bir ışık döndürür" diyebilirsiniz.
Faydalı hata iletileri sağlayın OpenAPI belirtimi içinde olmasa da yapay zekanın kendi kendine düzeltilmesine yardımcı olan hata iletileri sağlamayı göz önünde bulundurun. Örneğin, bir kullanıcı geçersiz bir kimlik sağlıyorsa, yapay zeka aracısının uç noktadan doğru kimliği almasını öneren bir hata iletisi sağlamayı get_all_lights göz önünde bulundurun.

Sonraki adımlar

Eklenti oluşturmayı öğrendiğinize göre artık bunları yapay zeka aracınızla nasıl kullanacağınızı öğrenebilirsiniz. Eklentilerinize eklediğiniz işlevlerin türüne bağlı olarak, izlemeniz gereken farklı desenler vardır. kullanarak alma işlevleri hakkında bilgi almak için makalesine bakın. Görev otomasyonu işlevleri için görev otomasyonu işlevlerini kullanma makalesine bakın.

Geri alma işlevlerini kullanma hakkında bilgi edinin

  • Last updated on