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 OpenAPI belirtimi şöyle görünebilir:
{
"openapi": "3.0.1",
"info": {
"title": "Light API",
"version": "v1"
},
"paths": {
"/Light": {
"get": {
"tags": [
"Light"
],
"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": {
"tags": [
"Light"
],
"summary": "Changes the state of a light.",
"operationId": "change_light_state",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the light to change from the get_all_lights tool.",
"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.
İpucu
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
}
);
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 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:
| Öneri | Açıklama |
|---|---|
| API belirtimlerinizi sürüm denetimi | Canlı BIR API belirtimine işaret etmek yerine Swagger dosyanızı denetlemeyi ve sürüm oluşturmayı 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 kullanma | Uç noktalarınızın ve parametrelerinizin adlarının açıklayıcı ve açıklayıcı 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 sabit listeleri gibi daha belirli türler kullanın. Bu, yapay zekanın API'yi daha iyi anlamasına yardımcı olur. |
| Açıklamalarda örnekler sağlayın | İ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. |
| Yararlı 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. Alma işlevleri için alma işlevlerini kullanma makalesine bakın. Görev otomasyonu işlevleri için , görev otomasyonu işlevlerini kullanma makalesine bakın.