chore: docs review (#220)

* fixed links to other docs * fixed links * fix links * fix links * review and fix for links * fix links * add new demo video * fix links
epam · Jan 13, 2025 · 3be30e3 · 3be30e3
1 parent 9af2dfd
commit 3be30e3
Show file tree

Hide file tree

Showing 45 changed files with 151 additions and 192 deletions.
diff --git a/docs/Auth/2. Web/1.overview.md b/docs/Auth/2. Web/1.overview.md
@@ -8,16 +8,16 @@ JSON Web Token (JWT) is used for web authentication to securely transmit informa
 
 1. Configure your identity service provider (IDP)
 2. Configure AI DIAL Core and Chat to work with your IDP
-3. (Optional) Further, you can create roles and permission in AI DIAL for your users. Refer to [Chat Users](/Roles%20and%20Access%20Control/chat-users) to learn how to do this.
+3. (Optional) Further, you can create roles and permission in AI DIAL for your users. Refer to [Chat Users](/docs/Roles%20and%20Access%20Control/2.chat-users.md) to learn how to do this.
 
-> Refer to [Auth0](./IDPs/auth0), [AWS Cognito](./IDPs/cognito), [MS Entra](./IDPs/entraID), [Google Identity](./IDPs/google), [Keycloak](./IDPs/keycloak), [Okta](./IDPs/okta) to view how to enable them as an identity and access management solution for AI DIAL users.
+> Refer to [Auth0](/docs/Auth/2.%20Web/2.IDPs/auth0.md), [AWS Cognito](/docs/Auth/2.%20Web/2.IDPs/cognito.md), [MS Entra](/docs/Auth/2.%20Web/2.IDPs/entraID.md), [Google Identity](/docs/Auth/2.%20Web/2.IDPs/google.md), [Keycloak](/docs/Auth/2.%20Web/2.IDPs/keycloak.md), [Okta](/docs/Auth/2.%20Web/2.IDPs/okta.md) to view how to enable them as an identity and access management solution for AI DIAL users.
 
 ## Example
 
 For example purposes, lets configure Microsoft Entra to work with AI DIAL as an identity service provider: 
 
-1. [Configure Microsoft Entra](/Auth/Web/IDPs/entraID#configure-microsoft-entra-id): create application, client secret, and user group.
-2. [Configure AI DIAL Chat](/Auth/Web/IDPs/entraID#ai-dial-chat-settings) to work with MS Entra.
-3. [Configure AI DIAL Core](/Auth/Web/IDPs/entraID#ai-dial-core-settings) to work with MS Entra.
-4. (Optional) You can now create and assign roles and limits to manage access control of your users to various system resources such as applications, models, assistants and addons. Refer to [Create and assign roles](/Auth/Web/IDPs/entraID#assignment-of-roles) to learn more. Refer to [Roles & Access Control](/Roles%20and%20Access%20Control/overview) to learn more about roles and how to use them. 
+1. [Configure Microsoft Entra](/docs/Auth/2.%20Web/2.IDPs/entraID.md#configure-microsoft-entra-id): create application, client secret, and user group.
+2. [Configure AI DIAL Chat](/docs/Auth/2.%20Web/2.IDPs/entraID.md#ai-dial-chat-settings) to work with MS Entra.
+3. [Configure AI DIAL Core](/docs/Auth/2.%20Web/2.IDPs/entraID.md#ai-dial-core-settings) to work with MS Entra.
+4. (Optional) You can now create and assign roles and limits to manage access control of your users to various system resources such as applications, models, assistants and addons. Refer to [Create and assign roles](/docs/Auth/2.%20Web/2.IDPs/entraID.md#assignment-of-roles) to learn more. Refer to [Roles & Access Control](/docs/Roles%20and%20Access%20Control/1.overview.md) to learn more about roles and how to use them. 
 
diff --git a/docs/Auth/3. programmatic-auth.md b/docs/Auth/3. programmatic-auth.md
@@ -28,13 +28,13 @@ In the following example, `"myApiKey"` API key is created for a project `"MyProj
 
 API keys must be associated with roles. Such roles are used to manage access to system resources and restrict the number of requests that can be sent to them.
 
-> Refer to [Roles](/Roles%20and%20Access%20Control/overview) to learn more how to use roles.
+> Refer to [Roles](/docs/Roles%20and%20Access%20Control/1.overview.md) to learn more how to use roles.
 
 Roles used by API keys must be declared in the `roles` section.
 
 In the previous example, we assigned the `default` role for `myApiKey` API key. On this step, we need to declare the `default` role in the `roles` section to make a valid configuration. 
 
-Optionally, we can configure limits for this role, or leave them empty to apply an unlimited access. In this example, we grant an unlimited access for the `default` role to the `chat-gpt-35-turbo` model. You can refer to [Roles & Access Control](/Roles%20and%20Access%20Control/API%20Keys) to learn how to define access limits for API keys. 
+Optionally, we can configure limits for this role, or leave them empty to apply an unlimited access. In this example, we grant an unlimited access for the `default` role to the `chat-gpt-35-turbo` model. You can refer to [Roles & Access Control](/docs/Roles%20and%20Access%20Control/3.API%20Keys.md) to learn how to define access limits for API keys. 
 
 **Note**, that it is mandatory to define at least one role and assign it for an API key, but you can leave `limits` empty (as shown in the previous example) to apply the default value - `unlimited`.
 

diff --git a/docs/Deployment/Bedrock Model Deployment.md b/docs/Deployment/Bedrock Model Deployment.md
@@ -80,7 +80,7 @@ IAM (Identity and Access Management) users in AWS (Amazon Web Services) are enti
 
 #### Assign to Service Account
 
-In case your cluster is located at AWS, the best practise for using Bedrock is to assign an IAM Policy to your Service Account. You can do this via IAM Roles.
+In case your cluster is located at AWS, the best practice for using Bedrock is to assign an IAM Policy to your Service Account. You can do this via IAM Roles.
 
 > Refer to [AWS Documentation](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to learn how to configure an IAM roles for service accounts.
 
@@ -94,7 +94,7 @@ Add your model with its parameters in the `models` section.
 
 > Refer to [AI DIAL Core Configuration](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json#L30) to view an example.
 
-> Refer to [Configure core config](./configuration.md#core-parameters) to view the configuration of AI DIAL core parameters in the helm-based installation.
+> Refer to [Configure core config](/docs/Deployment/configuration.md#core-parameters) to view the configuration of AI DIAL core parameters in the helm-based installation.
 
 ### Configure AI DIAL Adapter
 

diff --git a/docs/Deployment/OpenAI Model Deployment.md b/docs/Deployment/OpenAI Model Deployment.md
@@ -71,7 +71,7 @@ From this instruction, you will learn how to create an Azure OpenAI model GPT-3.
 
 #### Configure Kubernetes Service Account
 
-In case your cluster is located at Azure, the best practise for using Azure OpenAI is to assign an Azure user-assigned managed identity to Kubernetes Service Account. You can do this using Microsoft Entra Workload ID with Azure Kubernetes Service.
+In case your cluster is located at Azure, the best practice for using Azure OpenAI is to assign an Azure user-assigned managed identity to Kubernetes Service Account. You can do this using Microsoft Entra Workload ID with Azure Kubernetes Service.
 
 > Refer to [Azure Documentation](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview) to learn how to configure Microsoft Entra Workload ID with Azure Kubernetes Service.
 
@@ -87,7 +87,7 @@ Add your model with its parameters in the `models` section.
 
 > Refer to [AI DIAL Core Configuration](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json#L30) to view an example.
 
-> Refer to [Configure core config](./configuration.md#core-parameters) to view the configuration of AI DIAL core parameters in the helm-based installation.
+> Refer to [Configure core config](/docs/Deployment/configuration.md#core-parameters) to view the configuration of AI DIAL core parameters in the helm-based installation.
 
 ### Configure AI DIAL Adapter
 

diff --git a/docs/Deployment/Vertex Model Deployment.md b/docs/Deployment/Vertex Model Deployment.md
@@ -76,7 +76,7 @@ To communicate with VertexAI models, it is necessary to have a service account.
 
 #### Configure Kubernetes Service Account
 
-In case your cluster is located at GCP, the best practise for using VertexAI is to assign a GCP IAM service account to Kubernetes Service Account. You can do this via Workload Identity Federation for GKE.
+In case your cluster is located at GCP, the best practice for using VertexAI is to assign a GCP IAM service account to Kubernetes Service Account. You can do this via Workload Identity Federation for GKE.
 
 > Refer to [GCP Documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) to learn how to configure a Workload Identity Federation for GKE.
 
@@ -90,7 +90,7 @@ Add your model with its parameters in the `models` section.
 
 > Refer to [AI DIAL Core Configuration](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json#L30) to view an example.
 
-> Refer to [Configure core config](./configuration.md#core-parameters) to view the configuration of AI DIAL core parameters in the helm-based installation.
+> Refer to [Configure core config](/docs/Deployment/configuration.md#core-parameters) to view the configuration of AI DIAL core parameters in the helm-based installation.
 
 ### Configure AI DIAL Adapter
 

diff --git a/docs/Deployment/configuration.md b/docs/Deployment/configuration.md
@@ -87,9 +87,9 @@ To work with Azure, AWS or GCP models, AI DIAL uses applications called Adapters
 You can modify adapters settings using environment variables.
 
 > Refer to these repositories to learn how to configure adapters:
-> * [Bedrock Model Deployment](./Bedrock%20Model%20Deployment.md#configure-adapter)
-> * [OpenAI Model Deployment](./OpenAI%20Model%20Deployment.md#configure-adapter)
-> * [Vertex Model Deployment](./Vertex%20Model%20Deployment.md#configure-adapter)
+> * [Bedrock Model Deployment](/docs/Deployment/Bedrock%20Model%20Deployment.md)
+> * [OpenAI Model Deployment](/docs/Deployment/OpenAI%20Model%20Deployment.md)
+> * [Vertex Model Deployment](/docs/Deployment/Vertex%20Model%20Deployment.md)
 
 ## Assistant Parameters
 

diff --git a/docs/Deployment/custom_apps_deployment.md b/docs/Deployment/custom_apps_deployment.md
@@ -4,7 +4,7 @@
 
 Follow steps described in this guide, to deploy your custom application using a Helm chart and integrate it with AI DIAL Core configuration.
 
-> * Refer to [User Guide](../user-guide#applications-1) to learn about DIAL apps.
+> * Refer to [User Guide](/docs/user-guide.md#applications-1) to learn about DIAL apps.
 > * Refer to [DIAL Core dynamic setting](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json) to learn how to add apps to config.
 > * Refer to [DIAL Helm](https://github.com/epam/ai-dial-helm) to view deployment examples.
 

diff --git a/docs/Roles and Access Control/1.overview.md b/docs/Roles and Access Control/1.overview.md
@@ -7,7 +7,7 @@ In AI DIAL, you can use **roles** for various purposes:
 * Implement a custom logic in applications
 * Give access to specific system features
 
-> Watch a [demo video](../video%20demos/demos/dial-roles-and-rate-limits) to learn more.
+> Watch a [demo video](/docs/video%20demos/demos/3.dial-roles-and-rate-limits.md) to learn more.
 
 ## Access to Resources
 
@@ -25,7 +25,7 @@ In the following example, we grant access to `chat-gpt-35-turbo` model for users
 }
 ```
 
-> Refer to [configuration example](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json) to view the full example and to [Chat Users](/Roles%20and%20Access%20Control/chat-users) to learn how to configure access for chat users and to [API Keys](/Roles%20and%20Access%20Control/API%20Keys) to learn how to configure access for applications.
+> Refer to [configuration example](https://github.com/epam/ai-dial-core/blob/development/sample/aidial.config.json) to view the full example and to [Chat Users](/docs/Roles%20and%20Access%20Control/2.chat-users.md) to learn how to configure access for chat users and to [API Keys](/docs/Roles%20and%20Access%20Control/3.API%20Keys.md) to learn how to configure access for applications.
 
 ## Access Restriction
 

diff --git a/docs/Roles and Access Control/2.chat-users.md b/docs/Roles and Access Control/2.chat-users.md
@@ -4,7 +4,7 @@ You can configure AI DIAL to work with various identity service providers, where
 
 In the system configuration, you can then add rules and restrictions to manage access to your users to various system resources.
 
-1. For chat users, you can define user groups/roles/pools (it depends on a specific IDP) in your identity service provider (IDP) which are then passed to AI DIAL in JWT. Refer to [Auth](/Auth/Web/overview) to view supported IDPs and learn how to configure them.
+1. For chat users, you can define user groups/roles/pools (it depends on a specific IDP) in your identity service provider (IDP) which are then passed to AI DIAL in JWT. Refer to [Auth](/docs/Auth/2.%20Web/1.overview.md) to view supported IDPs and learn how to configure them.
 2. You can then utilize user roles from the JWT claims to define roles in the AI DIAL configuration as a `userRoles` parameter value. In the following example, we grant access to `chat-gpt-35-turbo` model for users with the `operator` user role. Using the same pattern, you can define user access to applications, addons, assistants. 
 
     **Important**: you must always use roles from the JWT claims that you receive from your IDP. 

diff --git a/docs/Roles and Access Control/3.API Keys.md b/docs/Roles and Access Control/3.API Keys.md
@@ -2,14 +2,14 @@
 
 ## API Keys
 
-API keys can be used not only for [authentication](/Auth/programmatic-auth), but also to manage access to system resources and apply restrictions on such access.
+API keys can be used not only for [authentication](/docs/Auth/3.%20programmatic-auth.md), but also to manage access to system resources and apply restrictions on such access.
 
 This is done via assigning of **roles** to API keys. Roles must be associated with specific system resources such as models, applications, addons and assistants.
 
 To create and configure access control for API keys:
 
-1. [Create API Key](/Auth/programmatic-auth#step-1-define-api-keys)
-2. [Assign role(s)](/Auth/programmatic-auth#step-2-assign-roles) 
+1. [Create API Key](/docs/Auth/3.%20programmatic-auth.md#step-1-define-api-keys)
+2. [Assign role(s)](/docs/Auth/3.%20programmatic-auth.md#step-2-assign-roles) 
 3. Add restrictions: 
 
     Roles used by API keys must be declared in the `roles` section. In the following example, we assign the `basic` role for `projectKey1` API key. It grants access to the `chat-gpt-35-turbo` model with some restrictions: