| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| minLevel | 1 | |||||||||||
| maxLevel | 6 | outline | ||||||||||
| Table of Contents | ||||||||||||
|
...
Ayfie Personal Assistant is an advanced AI-powered web application that enables users to upload, analyze, and interact with data of almost any file format, including Office documents and PDFs, facilitating queries and discussions related to the uploaded content.
Here are a few important concepts to be aware of when managing the standalone Personal Assistant application.
Two Components
Ayfie Personal Assistant consists of two components, of which one, the part that includes the UI, is referred to as the Ayfie Personal Assistant Application. Since Azure Marketplace refers to both components as applicationsA, this can lead to some confusion. It is thus important to understand that Ayfie Personal Assistant: is made up of these two components:
...
There are two ways of purchasing Ayfie Personal Assistant, : via a private plan or via a public offering. As the installation and configuration is slightly different for the two cases, one will need to know how the product was purchased.
...
A resource groups is what is used to group and administrate customer resources in Azure. The two Ayfie components Ayfie Personal Assistant Storage and Ayfie Personal Assistant Application could be placed in one resource group together with other non-Ayfie resources, or in a resource group just by themselves, or split across two different resource groups. Further, these resource groups could be given any name one see fit. However, it is recommended that each of them are given a dedicated resource group and that they are not mixed with other resources. It is also our recommendation these recommended naming the resource groups are named rg-ayfie-pa-storage and rg-ayfie-pa-application as the use of standardized names will make any later support request much easier to follow up on.
Prerequisites
The prerequisites come in two groups:
System prerequisites - Obtain the required subscription rights to do the installation
Admin user prerequisites - Obtain the required user permissions to run the install process
System Prerequisites
These are the system prerequisites:
Obtain an Azure Subscription
An active Azure subscription is required. To register a new subscription, go to the Azure website.
At times, Microsoft may impose subscription type specific limitations on their OpenAI services, particularly concerning the amount of data (referred to as the token quota) that can be exchanged during chat interactions. Please see this Microsoft documentation on token quotas for details on which subscription types that may have such restrictions.
If one has a contract directly with Ayfie (a.k.a. private plan) please send the Subscription ID to your Ayfie contact.
Get Azure OpenAI Approval
The Azure subscription needs to be approved for Azure Open AI. How to do that is described in Ayfie Personal Assistant - How to Request Access to the Azure OpenAI Service.
Enable two Providers
In the Azure subscription settings, ensure that the two providers below are enabled. How to do that is described in Ayfie Personal Assistant - How to Add Providers to an Azure Subscription.
Microsoft.App: Required for deploying applications within Azure.
Microsoft.ContainerService: Required for managing container-based services within Azure.
Admin User Prerequisites
The user that is to carries out the Ayfie . Using these exact named resource groups will simplify later upgrades to newer versions of Ayfie Personal Assistant as well as any future interactions with Ayfie support.
Version Upgrades
Version upgrades are not done as “upgrades” but rather as an uninstall operation (of the old version) followed by an install operation (of the new version). As of version 2.9, Personal Assistant consists of two components (see above) and only the application component is “upgraded” (uninstalled and installed), the storage component is left as-is.
Custom Domain vs. Random URL
The URL to access Personal Assistant can be either a custom domain of your choosing (for instance pa.mycompany.com) or whatever random URL provided by Azure AI services. The former approach is what is most common. In either case this has to be followed up whenever one upgrade to a new version of Personal Assistant, either by making sure to reuse the same Service Principle (the Entra ID application) or by updating the callback_url if one uses the default URL provided by Azure AI services.
Prerequisites
The prerequisites come in two groups:
System prerequisites - Obtain the required subscription rights to do the installation
Admin user prerequisites - Obtain the required user permissions to run the install process
System Prerequisites
These are the system prerequisites:
Obtain an Azure Subscription
An active Azure subscription is required. To register a new subscription, go to the Azure website.
At times, Microsoft may impose subscription type specific limitations on their OpenAI services, particularly concerning the amount of data (referred to as the token quota) that can be exchanged during chat interactions. Please see this Microsoft documentation on token quotas for details on which subscription types that may have such restrictions.
If one has a contract directly with Ayfie (a.k.a. private plan) please send the Subscription ID to your Ayfie contact.
Get Azure OpenAI Approval
The Azure subscription needs to be approved for Azure Open AI. How to do that is described in Ayfie Personal Assistant - How to Request Access to the Azure OpenAI Service.
Enable two Providers
In the Azure subscription settings, ensure that the two providers below are enabled. How to do that is described in Ayfie Personal Assistant - How to Add Providers to an Azure Subscription.
Microsoft.App: Required for deploying applications within Azure.
Microsoft.ContainerService: Required for managing container-based services within Azure.
Admin User Prerequisites
The user that is to carries out the Ayfie Personal Assistant install process must have these roles and permissions:
...
Obtain and configure the storage component of Ayfie Personal Assistant
Obtain and configure the application component of Ayfie Personal Assistant
Post-Deployment configuration
Obtain and Configure the Storage Component
Obtain the Storage Component
...
| Note |
|---|
Ayfie Personal Assistant Storage must be created (or already exist) before setting up the Ayfie Personal Assistant Application. |
...
If in doubt, one should consult Private Plan or Public Offering? on how to find out what one has. Most of the steps are the same for the two alternatives. The difference is in step 2 and 5 below (indicated with bold font) and with green markings in the screenshot below where one follow the red arrows all the way for the public offering and swap to green for the private plan.
...
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Marketplace and select it from the search resultsthe search results
If you have a private plan select Private plans in in the left side menu (circled in green), otherwise use the search box to look up the “Ayfie Personal Assistant” applications
Select the Ayfie Personal Assistant Application box
If you have a private plan select Private plans in in the left side menu (circled in green, select the plan from the dropdown (see green arrow below), otherwise use the search box to look up the “Ayfie Personal Assistant” applications
Select the Ayfie Personal Assistant Application box
If you have a private plan, select the plan from the dropdown (see green arrow below), otherwise select the number of users you want to license (red arrow). Then click the Create button.
...
From this point of in the procedure, there is no difference between having a private plan or a public offering.
Configure the Application Component
To complete the creation of the Ayfie Personal Assistant Application component, one will visit these 4 page tabs one by one in the given order:
Basic
User Authentication
Application Settings
Review + create
The Basic Tab
The page title in the graphics below ends with Private Plan. if one is using a public offering, then the title will instead be Create N users, where N is the number of users one selected from the dropdown on the previous page. The graphics in this section will show both title types.
...
Select the subscription from the dropdown (Ayfie Development in the example above).
Create a new resource group (recommended) or select an existing one. The recommended name for the group is rg-ayfie-pa-application.
Select the region. Normally one would select the same region as earlier selected for the storage component, but if this is done as part of an upgrade one may have to select another region if one as part of the upgrade is changing to a new language model that is not available in the same region.
Select the storage resource group from earlier (that is rg-ayfie-pa-storage if one created it using the recommend name)
Give the managed application a name, for instance the recommended name AyfiePersonalAssistant as in the example above.
Click Next to get to the next page tab
The User Authentication Tab
...
User access to Ayfie Personal Assistance is managed by Entra ID via a Service Principal.
One can use a Service Principal that already exists or create a new one.
Note:If an upgrade make sure to use the exact same Enterprise Application in previous version, else it may cause issues with files and chat history
Depending on which of the two options one chose, clicking the Make selection link will either bring up a search pane with existing Service Principals to choose from, or a form to register a new Service Principal. The screenshot above shows the case of creating a new one.
Give the Service Principal (the Entra ID application) a name, for instance AyfiePersonalAssistantApp as in the graphics above.
Select the single tenant option (this would cover the case of all users being employees of the customer)
Click the Register button. This will take one away from the page. After having completed the registration, just redo the first few steps to get back to this place.
Verify that one has created or selected a Service Principal by checking of the check box
Click Next (circled in red) to get to the Authentication page
The Application Settings Tab
The “Application Settings” tab has the following optional settings which allows you to:
Enable and set Custom Domain (instead of a generated URL)
Enable and set Data Retention Policy (if not enabled we will keep all documents for as long the application is installed)
These settings are not possible to change post deployment. That would require one to uninstall and install as explained in chapter “Upgrading to a Newer Version of Ayfie Personal Assistant”
...
Custom Domain (red box)
When deploying Ayfie Personal Assistant one is always given an URL which users can use to access the frontend. This URL will adhere to the format: https://chat-ui.random-part.region-name.azurecontainerapps.io.
If one instead would like users to access the application with a specific custom URL, then do as described below, otherwise skip this page by clicking the Next button directly:
Check the “Configure custom domain”
Check the “Verify if you have access to DNS record for you domain”
Add the custom domain, e.g. “pa.my-domain.com” to the input field
Click the white Next or the blue Review + create button. This will take one to the Review + create page.
Data Retention Policy (green box)
If one want to reduce the storage cost, be compliant with internal policies for data storage or if one want to avoid a potential long list of files in the user interface of Personal Assistant, one can enable Data Retention Policy. This can be set to an integer between 7 and 100. This feature will then remove all files permanently from Personal Assistant if the file is older and haven’t been used in any chat for the past number of days specified.
...
Check the “Enable data retention policy”
...
select the number of users you want to license (red arrow). Then click the Create button.
...
From this point of in the procedure, there is no difference between having a private plan or a public offering.
Configure the Application Component
To complete the creation of the Ayfie Personal Assistant Application component, one will visit these 4 page tabs one by one in the given order:
Basic
User Authentication
Application Settings
Review + create
The Basic Tab
The page title in the graphics below ends with Private Plan. if one is using a public offering, then the title will instead be Create N users, where N is the number of users one selected from the dropdown on the previous page. The graphics in this section will show both title types.
...
Select the subscription from the dropdown (Ayfie Development in the example above).
Create a new resource group (recommended) or select an existing one. The recommended name for the group is rg-ayfie-pa-application.
Select the region. Normally one would select the same region as earlier selected for the storage component, but if this is done as part of an upgrade one may have to select another region if one as part of the upgrade is changing to a new language model that is not available in the same region.
Select the storage resource group from earlier (that is rg-ayfie-pa-storage if one created it using the recommended name)
Give the managed application a name, for instance the recommended name AyfiePersonalAssistant as in the example above.
Click Next to get to the next page tab
The User Authentication Tab
...
User access to Ayfie Personal Assistance is managed by Entra ID via a Service Principal.
One can use a Service Principal that already exists or create a new one.
Note: If upgrading, make sure to use the exact same Enterprise Application as in for previous version, otherwise it may cause issues with stored documents and chat history
Depending on which of the two options one chose, clicking the Make selection link will either bring up a search pane with existing Service Principals to choose from, or a form to register a new Service Principal. The screenshot above shows the case of creating a new one.
Give the Service Principal (the Entra ID application) a name, for instance AyfiePersonalAssistantApp as in the graphics above.
Select the single tenant option (this would cover the case of all users being employees of the customer)
Click the Register button. This will take one away from the page. After having completed the registration, just redo the first few steps to get back to this place.
Verify that one has created or selected a Service Principal by checking of the check box
Click Next (circled in red) to get to the Authentication page
The Application Settings Tab
The “Application Settings” tab has the following optional settings which allows you to:
Custom Domain - Enable and set Custom Domain (instead of a generated URL)
Data Retention Policy- Enable and set Data Retention Policy (if not enabled we will keep all documents for as long the application is installed)
Model Configuration - Change the default AI-model for new Chat-sessions
These settings are not possible to change post deployment. That would require one to uninstall and install as explained in chapter “Upgrading to a Newer Version of Ayfie Personal Assistant”
...
Custom Domain (red box)
When deploying Ayfie Personal Assistant one is always given an URL which users can use to access the frontend. This URL will adhere to the format: https://chat-ui.random-part.region-name.azurecontainerapps.io.
If one instead would like users to access the application with a specific custom URL, then do as described below, otherwise skip this page by clicking the Next button directly:
Check the “Configure custom domain”
Check the “Verify if you have access to DNS record for you domain”
Add the custom domain, e.g. “pa.my-domain.com” to the input field
Click the white Next or the blue Review + create button. This will take one to the Review + create page.
Data Retention Policy (green box)
If one want to reduce the storage cost, be compliant with internal policies for data storage or if one want to avoid a potential long list of files in the user interface of Personal Assistant, one can enable Data Retention Policy. This can be set to an integer between 7 and 100. This feature will then remove all files permanently from Personal Assistant if the file is older and haven’t been used in any chat for the past number of days specified.
Check the “Enable data retention policy”
Enter the number of days before files are deleted due to inactivity
Model Configuration (blue box)
By default, the best supported models for your selected region will be enabled and visible for all users. However, one can chose to change the default model that will be used when users initiate a new chat. By default it’s the “Economy”-model that is set as default, which may be changed to either “Standard” or “Premium”.
The Review + Create Tab
Review the summary of one’s choices from the previous two tabs and go back and correct anything found to be wrong.
Click the Create button at the bottom of the page when ready to deploy Ayfie Personal Assistant
...
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Resource Groups and select it from the search results
Search for and select resource group rg-ayfie-pa-application (or whatever other name that it was given)
Click the managed application AyfiePersonalAssistant (or whatever other name that it was given)
Click the managed resource group link mrg-ayfie_personal_assistan-<timestamp> (or whatever other name that it was given) up to the right
Within this group, find and click on the 'chat-ui' resource to access its settings.
In the 'chat-ui' resource, look for the 'Custom Domain' section in the navigation pane on the left side of the screen.
Click on the 'Add custom domain' button to start the domain setup process.
When prompted, choose 'Managed certificate' as your first option (circled in purple) to ensure your domain is secured with an SSL certificate managed by Azure.
In the 'Domain' field (circled in green), type in the exact domain name you specified during the deployment of the Ayfie Personal Assistant Application.
For the record type, leave it set to “CNAME”
Add the two records provided in the 'Domain validation' section (circled in orange) to your domain's DNS settings. These records are crucial for proving ownership of the domain and for the SSL certificate to be issued.
Once you've updated your domain's DNS settings, click the 'Validate' button in Azure to check if the records are correctly configured.
If the validation is successful, the domain status should eventually update from “No binding” to 'Secured', indicating that your custom domain is now properly set up and protected with an SSL certificate.
...
One wants to uninstall Personal Assistant completely for not using it any longer
Uninstall both components
One wants to uninstall Personal Assistant as part of an upgrade to a newer version of Personal Assistant
Only uninstall the application component, leave the storage component with all the chat history and uploaded documents in place
...
Retrieve the Client ID of the application:
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Managed Applications and select it from the search results
At the Managed Applications page, click AyfiePersonalAssistant (or whatever other name one chose to give the application in a previous section above)
Under Settings, Click Parameters and Outputs in the left vertical menu
Navigate to Settings and select Parameters and outputs
Copy the Client ID, it will be needed in step 4 below
Uninstall the current version as described in chapter Uninstalling the Ayfie Personal Assistant
Force an immediate deletion of any resources that are marked for deletion but that have still not been deleted as shown in the screenshot below.
...
Install Do the installation from scratch as described in chapter Installing Ayfie Personal Assistant. (but skip installing the storage component that was not uninstalled):
If opting to re-use the existing "Service Principal" and you don’t (Entra ID application) and one does not use a custom domain name, ensure to update the 'callback_url' within as described in earlier section Set the Entra ID application up with the Callback URL
(Note: If you are upgrading for a version prior 2.14 of Personal Assistant you would also need to follow the instruction in linked). The same applies if one is upgrading from a Personal Assistant version prior to version 2.14.If Custom Domain is configured with the same value as in past versions, one is required to follow the steps within earlier section Custom Domain Configuration.
Troubleshooting
Deploying Ayfie Personal Assistant may encounter issues, and this section provides guidance on identifying and resolving common errors.
...