Skip to content

feat: rewritten documenation for Mia-Assistant for self-hosted installations #2660

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
albertotessarotto merged 3 commits into from
Aug 20, 2026
Merged

feat: rewritten documenation for Mia-Assistant for self-hosted installations #2660

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fc050be
feat: rewritten documenation for Mia-Assistant for self-hosted instal…
Aug 19, 2026
db06f0c
fix: grammar
Aug 19, 2026
e45af7c
fix: typo
Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 127 additions & 121 deletions ...rements/installation-guidelines/console/self-hosted/helm-values/75_assistant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,84 +4,45 @@ 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 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

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 [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.

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.
:::

### OpenAI Configuration

The Mia-Assistant service can be configured via Helm Chart using the `.assistant` value.
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.

:::info
At the moment, the only supported models are the ones developed by [OpenAI](https://platform.openai.com/docs/models/overview).
Please refer to the official MongoDB documentation to have more information regarding this.
:::

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.
### AI Provider Configuration

The service is already configured to use the following models:
Mia-Assistant allows using Embedding Models and Large Language Models from these providers:

- [`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)
- [**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 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

:::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 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 |
|:----:|:----:|:-----------:|:-------:|:--------:|
| `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 | | ✅ |
| `embeddings` | object | The configuration of the related Embeddings used under the hood | | ✅ |
| `keys` | object | The configuration for the API Keys and Credentials for specified Models | | ✅ |
| `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

Expand All @@ -92,13 +53,26 @@ You can choose one or multiple LLMs providers to be used from the Mia-Assistant.
- `vertex`
- `google_anthropic_vertex`

As Embedding model you can choose one of the following supported types:
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 are defined in the field `keys.vertexAICredentials`.

As an 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 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 service, 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:

Expand All @@ -107,111 +81,143 @@ mia-console:
configurations:
# ...
assistant:
enabled: true,
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 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.

```yaml
mia-console:
configurations:
# ...
assistant:
enabled: true,
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 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.

```yaml
mia-console:
configurations:
# ...
assistant:
enabled: true,
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:
configurations:
# ...
assistant:
enabled: true,
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",
# ...
```