From fc050be2c9a2e2006945fa9e864b09b22bab10c0 Mon Sep 17 00:00:00 2001 From: "demetrio.marino" Date: Wed, 19 Aug 2026 10:38:26 +0200 Subject: [PATCH 1/3] feat: rewritten documenation for Mia-Assistant for self-hosted installations --- .../self-hosted/helm-values/75_assistant.md | 230 +++++++++--------- 1 file changed, 118 insertions(+), 112 deletions(-) diff --git a/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md b/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md index 931c9380b8..9133ab260b 100644 --- a/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md +++ b/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md @@ -4,72 +4,33 @@ title: Mia-Assistant sidebar_label: Assistant --- +Mia-Platform Console includes *Mia Assistant*, an AI-based application that can be interrogated on anything included in the official [Mia-Platform Documentation](/) and to use the [Mia-Platform Console MCP Server](https://github.com/mia-platform/console-mcp-server) to receive help on the Mia-Platform Console company and projects, allowing to gather information about configurations, deployments, kubernetes status. +## MongoDB requirements -Mia-Platform Console includes *Mia Assistant*, an AI-based application that can be interrogated on anything included in the official [Mia-Platform Documentation](/). +To fetch information of the official documentation of the Mia-Platform Suite, Mia-Assistant relies on the [RAG technique](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) on a set of embeddings that contains the Mia-Platform documentation. -## MongoDB configuration +These embeddings are included in a specific Docker Image named _mia-assistant-embeddings_, available on the official Mia-Platform Container registry. This image contains a script that extracts the embeddings of the documentation related to the installed Mia-Platform version, and stores them in a MongoDB collection named `assistant-documents`. -Mia-Assistant relies on a MongoDB vector store collection, that is automatically populated during deployment. - -However, the Helm Chart is not yet capable of creating the vector store collection and the necessary indexes for it to work; so you have to manually create a collection named `assistant-documents` and configure an [Atlas Vector Search index](https://www.mongodb.com/docs/atlas/atlas-vector-search/tutorials/vector-search-quick-start/) on it. +The Mia-Assistant service, at startup, will create (or update) an an [Atlas Vector Search index](https://www.mongodb.com/docs/atlas/atlas-vector-search/tutorials/vector-search-quick-start/) on it, partially based on the configuration included at the Assistant startup. :::info Please mind that Atlas Vector Search indexes are available only on MongoDB Atlas instance with version 6.0.11, 7.0.2 or higher. -Unfortunately, MongoDB's Vector Search indexes are not available on previous versions or on MongoDB Entreprise Server edition. If you don't meet these requirements, unfortunately the service will not work. +MongoDB's Vector Search indexes are not available on previous versions or on MongoDB Entreprise Server edition. If you don't meet these requirements, unfortunately the service will not work. Please refer to the official MongoDB official documentation to have more information regarding this. ::: -You can create the index in two ways: - -- with a script with the official MongoDB drivers that connects to MongoDB and prepare the embeddings for you, [as explained in the MongoDB official documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-type/#procedure) -- manually, connecting to your MongoDB Atlas cluster and creating the index from the Atlas web application, [as explained in this guide](https://mongodb-developer.github.io/search-lab/docs/vector-search/create-index) - -It is important that the index have this structure: - -```json -{ - "fields": [ - { - "numDimensions": 1536, - "path": "embedding", - "similarity": "euclidean", - "type": "vector" - }, - { - "path": "__STATE__", - "type": "filter" - } - ] -} -``` - -:::caution -The structure of the index is mandatory, otherwise the documents cannot be extracted from the collection. -::: +### AI Provider Configuration -### OpenAI Configuration +Mia-Assistant allow using Embedding Models and Large Language Models from these providers: -The Mia-Assistant service can be configured via Helm Chart using the `.assistant` value. - -:::info -At the moment, the only supported models are the ones developed by [OpenAI](https://platform.openai.com/docs/models/overview). -::: +- [**OpenAI**](https://openai.com/api/), which includes models of the GPT family and embedding models `text-embedding-3-small` and `text-embedding-3-large` +- [**Azure**](https://ai.azure.com/), which allow deployment of several models from several companies +- [**Vertex AI**](https://cloud.google.com/products/gemini-enterprise-agent-platform?hl=en) (rebranded in _Gemini Enterprise Agent Platform_), which allow hosting of several models from several companies -The Helm Chart will require including the API key for both the embedding model and the large language model used. For OpenAI models, these two API keys are the same and can be created from the [OpenAI API keys page](https://platform.openai.com/api-keys). After logging in with the credentials of your company, you can create the API Key that must be included in the `assistant` object inside the Helm chart and that will be used by the Mia-Assistant service. - -The service is already configured to use the following models: - -- [`text-embedding-3-small`](https://platform.openai.com/docs/guides/embeddings) as Embedding model -- [`gpt-3.5-turbo`](https://platform.openai.com/docs/models/gpt-3-5-turbo) as Large Language Model (LLM) - -:::info -Please note that using these models has a cost, which is detailed on the [Pricing](https://openai.com/api/pricing/) page of the OpenAI documentation. - -When registering with OpenAI, you also have to set up a billing plan in order to use OpenAI services with the Mia-Assistant. -::: +While LLMs are required to the Assistant to function (producing text, meaning reading questions and producing answers), the Embedding Models are required to have access to the Mia-Platform Documentation ## Mia-Assistant Configuration @@ -79,9 +40,9 @@ In order for the service to correctly start up, please ensure the following prop | Name | Type | Description | Default | Required | |:----:|:----:|:-----------:|:-------:|:--------:| | `enabled` | boolean | If set to `true`, the Mia-Assistant will be enabled | `false` | ❌ | -| `keys` | object | The configuration for the API Keys and Credentials for specified Models | | ✅ | +| `keys` | object | The configuration for the API Keys and Credentials for specified Models | | ✅ | | `llm` | object | The configuration of the related LLM used under the hood | | ✅ | -| `embeddings` | object | The configuration of the related Embeddings used under the hood | | ✅ | +| `embeddings` | object | The configuration of the related Embeddings used under the hood | | ❌ | ### LLM and Embeddings Model Configuration @@ -92,13 +53,26 @@ You can choose one or multiple LLMs providers to be used from the Mia-Assistant. - `vertex` - `google_anthropic_vertex` +The Assistant can be configured to have multiple LLM available, allowing the user using the Mia-Assistant to choose which LLM use based on their need. It is also possible to include different LLM coming from different AI Providers: the `llms` key expect an array of objects where +the different LLM configurations can included, as shown in the example above. + +Note that both `vertex` and `google_anthropic_vertex` cannot be configured to use different credentials for LLM and Embeddings models. Credentials for these models is defined in the field `keys.vertexAICredentials`. + As Embedding model you can choose one of the following supported types: - `azure` - `openai` -- `vertex` -Note that both `vertex` and `google_anthropic_vertex` cannot be configured to use different credentials for LLM and Embeddings models. Credentials for these models is defined in the field `keys.vertexAICredentials`. +The `embeddings` key is an object, since you can have configure one embedding model in use. + +:::info +The embeddings are available only with the `text-embedding-3-large` embedding model provided by OpenAI, and available via OpenAI API or Azure AI Foundry. If you don't have access to either services, the RAG technique could not work, and the Mia-Assistant cannot rely on the Documentation for helping carrying tasks on projects. +::: + +:::info +You can omit the `embeddings` key if you don't want the support of the Mia-Platform Documentation +in the Mia-Assistant and use it only as a general purpose knowledge with the capabilities of the MCP Server. +::: Here an example to configure Mia-Assistant with different LLM providers: @@ -109,50 +83,57 @@ mia-console: assistant: enabled: true, keys: - azureLlmApiKey: "azure-apiKey" - vertexAICredentials: "vertex-credentials" + azureLlmApiKey: azure-apiKey + vertexAICredentials: vertex-credentials llms: - - type: "azure", # this model uses keys.azureLlmApiKey - displayName: "GPT-4o Mini" - apiVersion": "2025-01-01-preview", - deploymentName": "gpt-4o-mini", - name": "gpt-4o-mini", - url": "https://test.openai.azure.com/" - - type: "google_anthropic_vertex", # this model uses keys.vertexAICredentials - name": "claude-sonnet-4@20250514", + # OpenAI LLM configuration example + - type: openai + name: gpt-5.4 + displayName: GPT-5.4 + # Azure LLM configuration example + - type: azure + name: gpt-5.4 + displayName: GPT-5.4 + deploymentName: gpt-5.4 + apiVersion: 2024-12-01-preview + url: https://test.openai.azure.com/ + # Gemini models hosted on Vertex AI LLM configuration example + - type: vertex + name: gemini-3.1-pro-preview + displayName: Gemini 3.1 Pro (Preview) + project: my-gcp-project + location: global + # Non-Gemini model hosted on Vertex AI LLM configuration example + - type: google_anthropic_vertex + name: claude-sonnet-4-6 + displayName: Claude Sonnet 4.6 + project: my-gcp-project + location: global # ... embeddings: - type: "azure", - apiKey: "embeddings-apiKey" - apiVersion": "2025-01-01-preview", - deploymentName": "text-embedding-3-large", - name": "text-embedding-3-large", - url": "https://test.openai.azure.com/" + # Azure embedding model configuration example + type: azure, + apiKey: embeddings-apiKey + apiVersion: 2025-01-01-preview + deploymentName: text-embedding-3-large + name: text-embedding-3-large + url: https://test.openai.azure.com ``` -Azure: +Different AI providers require different authentication secrets (such as API keys or private keys). These must be included inside the `keys` key. It is in form of an object where different +values must be included to support authentication with different providers. More details +on how to do this is shown in the following sub-paragraphs. -```yaml -mia-console: - configurations: - # ... - assistant: - enabled: true, - # ... - keys: - azureLlmApiKey: "your-apiKey" - llms: - - type": "azure", - name": "gpt-4o-mini", - # ... - embeddings: - type": "azure", - apiKey: "azure-embeddings-apiKey" - name": "text-embedding-3-large", - # ... -``` +#### Using OpenAI -OpenAI: +:::info +OpenAI is the default AI Provider for both LLMs and embedding models. If `type` key is omitted, it automatically defaults to `openai`. +::: + +Azure models requires to be deployed via Azure AI Foundry. You have to set the name of the model in the `name` key, and you can add `displayName` for a more readable name of the model to be shown in Mia-Assistant (defaults to the `name` value). + +The API Key used to authenticate must be included inside `keys.openaiLlmApiKey`. This value will +be encoded in base64 and included in a kubernetes service. ```yaml mia-console: @@ -162,19 +143,24 @@ mia-console: enabled: true, # ... keys: - openaiLlmApiKey: "your-apiKey" + openaiLlmApiKey: your-apiKey llms: - - type": "openai", - name": "gpt-4o-mini", + - type: openai + name: gpt-5.4 + displayName: GPT-5.4 # ... embeddings: - type": "openai", - apiKey: "openai-embeddings-apiKey" - name": "text-embedding-3-large", + type: openai, + name: text-embedding-3-large, # ... ``` -Vertex: +#### Using Azure + +Azure models requires to be deployed via Azure AI Foundry. The configuration requires then the `deploymentName`, the `apiVersion` and the `url` of said deployment. This goes for each LLM configured and for the embedding model. + +The API Key used to authenticate must be included inside `keys.azureLlmApiKey`. This value will +be encoded in base64 and included in a kubernetes service. ```yaml mia-console: @@ -184,18 +170,32 @@ mia-console: enabled: true, # ... keys: - vertexAICredentials: "vertex-ai-credentials" + azureLlmApiKey: your-apiKey llms: - - type": "vertex", - name": "gpt-4o-mini", - # ... - embeddings: - type": "vertex", - name": "text-embedding-004", + - type: azure + name: gpt-5.4 + displayName: GPT-5.4 + deploymentName: gpt-5.4 + apiVersion: 2024-12-01-preview + url: https://test.openai.azure.com/ # ... + embeddings: + type: azure, + apiKey: embeddings-apiKey + apiVersion: 2025-01-01-preview + deploymentName: text-embedding-3-large + name: text-embedding-3-large + url: https://test.openai.azure.com ``` -Anthropic models on Vertex: +#### Using Gemini Enterprise Agent Platform (Vertex AI) + +Gemini models require the type `vertex`. Other models available via Google Model Garden (such as Claude services) require the type `google_anthropic_vertex`. + +You have to set the name of the model in the `name` key, and you can add `displayName` for a more readable name of the model to be shown in Mia-Assistant (defaults to the `name` value). +Moreover, the `project` (which is the GCP project of the service account used to authenticate) and the `location` of the model to use must be included for each LLM model. + +The API Key used to authenticate must be included inside `keys.vertexAICredentials`, and should include the JSON with the required information of the service account to authenticate to the Google Cloud Provider instance. This value will be encoded in base64 and included in a kubernetes service. ```yaml mia-console: @@ -205,13 +205,19 @@ mia-console: enabled: true, # ... keys: - vertexAICredentials: "vertex-ai-credentials" + vertexAICredentials: my-vertex-ai-credentials llms: - - type": "google_anthropic_vertex", - name": "claude-sonnet-4@20250514", + - type: vertex, # Gemini models + name: gemini-3.1-pro-preview + displayName: Gemini 3.1 Pro (Preview) + project: my-gcp-project + location: global + - type: google_anthropic_vertex, # Vertex deployed models + name: claude-haiku-4-5 + displayName: Claude Haiku 4.5 + project: my-gcp-project + location: global # ... embeddings: - type": "vertex", - name": "text-embedding-004", # ... ``` From db06f0c22fb9c51a95f798f6406f0b45ddb876eb Mon Sep 17 00:00:00 2001 From: "demetrio.marino" Date: Wed, 19 Aug 2026 10:46:57 +0200 Subject: [PATCH 2/3] fix: grammar --- .../self-hosted/helm-values/75_assistant.md | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md b/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md index 9133ab260b..91c9ad13cf 100644 --- a/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md +++ b/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md @@ -4,7 +4,7 @@ title: Mia-Assistant sidebar_label: Assistant --- -Mia-Platform Console includes *Mia Assistant*, an AI-based application that can be interrogated on anything included in the official [Mia-Platform Documentation](/) and to use the [Mia-Platform Console MCP Server](https://github.com/mia-platform/console-mcp-server) to receive help on the Mia-Platform Console company and projects, allowing to gather information about configurations, deployments, kubernetes status. +Mia-Platform Console includes *Mia Assistant*, an AI-based application that can be interrogated on anything included in the official [Mia-Platform Documentation](/) and can use the [Mia-Platform Console MCP Server](https://github.com/mia-platform/console-mcp-server) to receive help on the Mia-Platform Console company and projects, allowing it to gather information about configurations, deployments, and Kubernetes status. ## MongoDB requirements @@ -12,30 +12,30 @@ To fetch information of the official documentation of the Mia-Platform Suite, Mi These embeddings are included in a specific Docker Image named _mia-assistant-embeddings_, available on the official Mia-Platform Container registry. This image contains a script that extracts the embeddings of the documentation related to the installed Mia-Platform version, and stores them in a MongoDB collection named `assistant-documents`. -The Mia-Assistant service, at startup, will create (or update) an an [Atlas Vector Search index](https://www.mongodb.com/docs/atlas/atlas-vector-search/tutorials/vector-search-quick-start/) on it, partially based on the configuration included at the Assistant startup. +The Mia-Assistant service, at startup, will create (or update) an [Atlas Vector Search index](https://www.mongodb.com/docs/atlas/atlas-vector-search/tutorials/vector-search-quick-start/) on it, partially based on the configuration included at the Assistant startup. :::info Please mind that Atlas Vector Search indexes are available only on MongoDB Atlas instance with version 6.0.11, 7.0.2 or higher. -MongoDB's Vector Search indexes are not available on previous versions or on MongoDB Entreprise Server edition. If you don't meet these requirements, unfortunately the service will not work. +MongoDB's Vector Search indexes are not available on previous versions or on MongoDB Enterprise Server edition. If you don't meet these requirements, unfortunately the service will not work. -Please refer to the official MongoDB official documentation to have more information regarding this. +Please refer to the official MongoDB documentation to have more information regarding this. ::: ### AI Provider Configuration -Mia-Assistant allow using Embedding Models and Large Language Models from these providers: +Mia-Assistant allows using Embedding Models and Large Language Models from these providers: - [**OpenAI**](https://openai.com/api/), which includes models of the GPT family and embedding models `text-embedding-3-small` and `text-embedding-3-large` -- [**Azure**](https://ai.azure.com/), which allow deployment of several models from several companies -- [**Vertex AI**](https://cloud.google.com/products/gemini-enterprise-agent-platform?hl=en) (rebranded in _Gemini Enterprise Agent Platform_), which allow hosting of several models from several companies +- [**Azure**](https://ai.azure.com/), which allows deployment of several models from several companies +- [**Vertex AI**](https://cloud.google.com/products/gemini-enterprise-agent-platform?hl=en) (re-branded as _Gemini Enterprise Agent Platform_), which allows hosting of several models from several companies -While LLMs are required to the Assistant to function (producing text, meaning reading questions and producing answers), the Embedding Models are required to have access to the Mia-Platform Documentation +While LLMs are required for the Assistant to function (producing text, meaning reading questions and producing answers), the Embedding Models are required to have access to the Mia-Platform Documentation. ## Mia-Assistant Configuration -The configuration regarding the Assistant is included inside the `assistant` object, which is composed by: -In order for the service to correctly start up, please ensure the following properties configured: +The configuration regarding the Assistant is included inside the `assistant` object, which is composed of: +In order for the service to correctly start up, please ensure the following properties are configured: | Name | Type | Description | Default | Required | |:----:|:----:|:-----------:|:-------:|:--------:| @@ -53,20 +53,20 @@ You can choose one or multiple LLMs providers to be used from the Mia-Assistant. - `vertex` - `google_anthropic_vertex` -The Assistant can be configured to have multiple LLM available, allowing the user using the Mia-Assistant to choose which LLM use based on their need. It is also possible to include different LLM coming from different AI Providers: the `llms` key expect an array of objects where -the different LLM configurations can included, as shown in the example above. +The Assistant can be configured to have multiple LLMs available, allowing the user using the Mia-Assistant to choose which LLM to use based on their need. It is also possible to include different LLMs coming from different AI Providers: the `llms` key expects an array of objects where +the different LLM configurations can be included, as shown in the example above. -Note that both `vertex` and `google_anthropic_vertex` cannot be configured to use different credentials for LLM and Embeddings models. Credentials for these models is defined in the field `keys.vertexAICredentials`. +Note that both `vertex` and `google_anthropic_vertex` cannot be configured to use different credentials for LLM and Embeddings models. Credentials for these models are defined in the field `keys.vertexAICredentials`. -As Embedding model you can choose one of the following supported types: +As an Embedding model, you can choose one of the following supported types: - `azure` - `openai` -The `embeddings` key is an object, since you can have configure one embedding model in use. +The `embeddings` key is an object, since you can configure only one embedding model in use. :::info -The embeddings are available only with the `text-embedding-3-large` embedding model provided by OpenAI, and available via OpenAI API or Azure AI Foundry. If you don't have access to either services, the RAG technique could not work, and the Mia-Assistant cannot rely on the Documentation for helping carrying tasks on projects. +The embeddings are available only with the `text-embedding-3-large` embedding model provided by OpenAI, and available via OpenAI API or Azure AI Foundry. If you don't have access to either service, the RAG technique could not work, and the Mia-Assistant cannot rely on the Documentation for helping carrying tasks on projects. ::: :::info @@ -81,7 +81,7 @@ mia-console: configurations: # ... assistant: - enabled: true, + enabled: true keys: azureLlmApiKey: azure-apiKey vertexAICredentials: vertex-credentials @@ -112,7 +112,7 @@ mia-console: # ... embeddings: # Azure embedding model configuration example - type: azure, + type: azure apiKey: embeddings-apiKey apiVersion: 2025-01-01-preview deploymentName: text-embedding-3-large @@ -130,7 +130,7 @@ on how to do this is shown in the following sub-paragraphs. OpenAI is the default AI Provider for both LLMs and embedding models. If `type` key is omitted, it automatically defaults to `openai`. ::: -Azure models requires to be deployed via Azure AI Foundry. You have to set the name of the model in the `name` key, and you can add `displayName` for a more readable name of the model to be shown in Mia-Assistant (defaults to the `name` value). +Azure models require to be deployed via Azure AI Foundry. You have to set the name of the model in the `name` key, and you can add `displayName` for a more readable name of the model to be shown in Mia-Assistant (defaults to the `name` value). The API Key used to authenticate must be included inside `keys.openaiLlmApiKey`. This value will be encoded in base64 and included in a kubernetes service. @@ -140,7 +140,7 @@ mia-console: configurations: # ... assistant: - enabled: true, + enabled: true # ... keys: openaiLlmApiKey: your-apiKey @@ -150,14 +150,14 @@ mia-console: displayName: GPT-5.4 # ... embeddings: - type: openai, - name: text-embedding-3-large, + type: openai + name: text-embedding-3-large # ... ``` #### Using Azure -Azure models requires to be deployed via Azure AI Foundry. The configuration requires then the `deploymentName`, the `apiVersion` and the `url` of said deployment. This goes for each LLM configured and for the embedding model. +Azure models require to be deployed via Azure AI Foundry. The configuration requires then the `deploymentName`, the `apiVersion` and the `url` of said deployment. This goes for each LLM configured and for the embedding model. The API Key used to authenticate must be included inside `keys.azureLlmApiKey`. This value will be encoded in base64 and included in a kubernetes service. @@ -167,7 +167,7 @@ mia-console: configurations: # ... assistant: - enabled: true, + enabled: true # ... keys: azureLlmApiKey: your-apiKey @@ -180,7 +180,7 @@ mia-console: url: https://test.openai.azure.com/ # ... embeddings: - type: azure, + type: azure apiKey: embeddings-apiKey apiVersion: 2025-01-01-preview deploymentName: text-embedding-3-large @@ -202,17 +202,17 @@ mia-console: configurations: # ... assistant: - enabled: true, + enabled: true # ... keys: vertexAICredentials: my-vertex-ai-credentials llms: - - type: vertex, # Gemini models + - type: vertex # Gemini models name: gemini-3.1-pro-preview displayName: Gemini 3.1 Pro (Preview) project: my-gcp-project location: global - - type: google_anthropic_vertex, # Vertex deployed models + - type: google_anthropic_vertex # Vertex deployed models name: claude-haiku-4-5 displayName: Claude Haiku 4.5 project: my-gcp-project From e45af7c5f7839d283645bb49d3bb50e00b951c83 Mon Sep 17 00:00:00 2001 From: "demetrio.marino" Date: Wed, 19 Aug 2026 13:06:11 +0200 Subject: [PATCH 3/3] fix: typo --- .../console/self-hosted/helm-values/75_assistant.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md b/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md index 91c9ad13cf..c32b5b52e9 100644 --- a/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md +++ b/docs/requirements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md @@ -41,7 +41,7 @@ In order for the service to correctly start up, please ensure the following prop |:----:|:----:|:-----------:|:-------:|:--------:| | `enabled` | boolean | If set to `true`, the Mia-Assistant will be enabled | `false` | ❌ | | `keys` | object | The configuration for the API Keys and Credentials for specified Models | | ✅ | -| `llm` | object | The configuration of the related LLM used under the hood | | ✅ | +| `llms` | object | The configuration of the related LLM used under the hood | | ✅ | | `embeddings` | object | The configuration of the related Embeddings used under the hood | | ❌ | ### LLM and Embeddings Model Configuration