Features
Azure OpenAI
The Azure OpenAI Services feature (CrestApps.OrchardCore.OpenAI.Azure) integrates seamlessly with Azure OpenAI. This module is dependency-driven, meaning it automatically enables or disables itself based on usage requirements.
Configuration
Add the following section to your appsettings.json to configure Azure OpenAI:
{
"OrchardCore": {
"CrestApps_AI": {
"Providers": {
"Azure": {
"DefaultConnectionName": "<!-- Default connection name -->",
"DefaultDeploymentName": "<!-- Default deployment name -->",
"Connections": {
"<!-- Unique connection name, ideally your Azure AccountName -->": {
"Endpoint": "https://<!-- Your Azure Resource Name -->.openai.azure.com/",
"AuthenticationType": "ApiKey",
"ApiKey": "<!-- API Key for your Azure AI instance -->",
"DefaultDeploymentName": "<!-- Default deployment name -->"
}
}
}
}
}
}
}
Valid values for AuthenticationType are: Default, ManagedIdentity, or ApiKey. If using ApiKey, the ApiKey field is required.
How to Retrieve Azure OpenAI Credentials
Get the API Key and Endpoint
- Open the Azure Portal and navigate to your Azure OpenAI instance.
- Go to Resource Management > Keys and Endpoint.
- Copy the Endpoint.
- Copy one of the two available API keys.
Azure OpenAI Chat Feature
This feature allows the creation of AI profiles using Azure OpenAI chat capabilities.
Recipe Configuration
Define an AI profile with the following step in your recipe:
{
"steps": [
{
"name": "AIProfile",
"profiles": [
{
"Source": "Azure",
"Name": "ExampleProfile",
"DisplayText": "Example Profile",
"WelcomeMessage": "What do you want to know?",
"FunctionNames": [],
"Type": "Chat",
"TitleType": "InitialPrompt",
"PromptTemplate": null,
"ConnectionName": "<!-- Connection name (optional) -->",
"DeploymentId": "<!-- Deployment ID (optional) -->",
"Properties": {
"AIProfileMetadata": {
"SystemMessage": "You are an AI assistant that helps people find information.",
"Temperature": null,
"TopP": null,
"FrequencyPenalty": null,
"PresencePenalty": null,
"MaxTokens": null,
"PastMessagesCount": null
}
}
}
]
}
]
}
Azure OpenAI – Bring Your Own Data
This feature builds on the AI Data Source Management system, enabling Azure OpenAI to interact with your own data repositories. It is automatically activated by dependent features and cannot be manually enabled or disabled.
AI Profile with Data Source Recipe Example
To define a profile that uses a data-source, use this recipe structure:
{
"steps": [
{
"name": "AIProfile",
"profiles": [
{
"Source": "AzureOpenAIOwnData",
"Name": "ExampleProfile",
"DisplayText": "Example Profile",
"WelcomeMessage": "What do you want to know?",
"FunctionNames": [],
"Type": "Chat",
"TitleType": "InitialPrompt",
"ConnectionName": "<!-- Connection name (optional) -->",
"DeploymentId": "<!-- Deployment ID (optional) -->",
"Properties": {
"AIProfileMetadata": {
"SystemMessage": "You are an AI assistant that helps people find information.",
"Temperature": null,
"TopP": null,
"FrequencyPenalty": null,
"PresencePenalty": null,
"MaxTokens": null,
"PastMessagesCount": null
},
"AIProfileDataSourceMetadata": {
"DataSourceId": "<!-- Data source ID -->",
"DataSourceType": "<!-- Data source type, e.g., 'azure_search' -->"
}
}
}
]
}
]
}
Azure AI Search-Powered Data Source
This feature extends the Bring Your Own Data capability by enabling integration with Azure AI Search. It allows your models to use Azure AI Search as a source for the data.
Azure AI Search-Powered Data Source Recipe Example
To define a Azure AI Search-Powered data-source, use this recipe structure:
{
"steps": [
{
"name": "AIDataSource",
"DataSources": [
{
"ProfileSource": "AzureOpenAIOwnData",
"Type": "azure_search",
"DisplayText": "<!-- Display name for the data-source -->",
"Properties": {
"AzureAIProfileAISearchMetadata": {
"IndexName": "<!-- Azure Search AI Index Name -->",
"Strictness": 3,
"TopNDocuments": 5
}
}
}
]
}
]
}
Elasticsearch-Powered Data Source
This feature extends the Bring Your Own Data capability by enabling integration with Elasticsearch, allowing your models to use Elasticsearch as a data source.
Elasticsearch-Powered Data Source Recipe Example
To define an Elasticsearch-Powered data-source, use this recipe structure:
{
"steps": [
{
"name": "AIDataSource",
"DataSources": [
{
"ProfileSource": "AzureOpenAIOwnData",
"Type": "elasticsearch",
"DisplayText": "<!-- Display name for the data-source -->",
"Properties": {
"AzureAIProfileElasticsearchMetadata": {
"IndexName": "<!-- Elasticsearch Index Name -->",
"Strictness": 3,
"TopNDocuments": 5
}
}
}
]
}
]
}
Configuration
This functionality relies on the OrchardCore.Search.Elasticsearch module. Refer to the official Orchard Core documentation for basic Elasticsearch configuration.
If your Elasticsearch cluster has security enabled, you’ll also need to generate an API key via Kibana to allow the chat client to access Elasticsearch indexes.
Generating an API Key in Kibana
1. Log in to Kibana
- Open Kibana in your browser.
- Sign in using an account with permission to manage API keys.
2. Navigate to API Key Management
- Go to Management > Stack Management.
- Under Security, select API Keys.
3. Create a New API Key
-
Click Create API key.
-
Fill in the form:
- Name: e.g.,
search-service-key - Expiration: Optional (e.g.,
1dfor one day) - Privileges: Optional role descriptors for access control
- Name: e.g.,
4. Copy and Format the API Key
- After creation, Kibana will display the key in Base64 format.
You can use this key in one of two ways:
Option 1: Using Base64ApiKey
Use the Base64-encoded key directly by setting AuthenticationType to Base64ApiKey. For example, in your appsettings.json:
{
"OrchardCore": {
"OrchardCore_Elasticsearch": {
"AuthenticationType": "Base64ApiKey",
"Base64ApiKey": "<!-- Base64 encoded key -->"
}
}
}
Option 2: Using KeyIdAndKey
You can also use the KeyIdAndKey authentication type, which requires both the API key ID and the key itself.
To obtain these:
- In Kibana, click the dropdown next to the created API key and switch the view from Base64 to JSON.
- You will see details like:
{
"id": "<!-- Key ID -->",
"name": "<!-- Key Name -->",
"api_key": "<!-- Key -->",
"encoded": "<!-- Base64 encoded ID + Key -->"
}
Then configure appsettings.json like this:
{
"OrchardCore": {
"OrchardCore_Elasticsearch": {
"AuthenticationType": "KeyIdAndKey",
"KeyId": "<!-- Key ID -->",
"Key": "<!-- Key -->"
}
}
}
MongoDB-Powered Data Source
This feature extends the Bring Your Own Data capability by enabling integration with Mongo DB, allowing your models to use Mongo DB as a data source.
Elasticsearch-Powered Data Source Recipe Example
To define an Elasticsearch-Powered data-source, use this recipe structure:
{
"steps": [
{
"name": "AIDataSource",
"DataSources": [
{
"ProfileSource": "AzureOpenAIOwnData",
"Type": "mongo_db",
"DisplayText": "<!-- Display name for the data-source -->",
"Properties": {
"AzureAIProfileMongoDBMetadata": {
"IndexName": "<!-- Mongo DB Index Name -->",
"Strictness": 3,
"TopNDocuments": 5,
"EndpointName": "<!-- Mongo DB endpoint name -->",
"AppName": "<!-- Mongo DB application name -->",
"CollectionName": "<!-- Mongo DB collection name -->",
"Authentication": {
"Type": "username_and_password",
"Username": "<!-- Mongo DB username -->",
"Password": "<!-- Mongo DB password -->"
}
}
}
}
]
}
]
}
Registering a Custom Data Source
Register a new data source using the following code:
services.AddAIDataSource(AzureOpenAIConstants.AISearchImplementationName, "azure_search", o =>
{
o.DisplayName = S["Azure OpenAI with Azure AI Search"];
o.Description = S["Enables AI models to use Azure AI Search as a data source for your data."];
});
Implementing the Data Source Handler
Implement the IAzureOpenAIDataSourceHandler interface to wire your data source into the chat system. You can reference AzureAISearchOpenAIDataSourceHandler in the source code as an example.