1 of 100

Products

Release Notes

May 2025

What's new

2025 Releases

February 2025

What's new

February 28

February 26

A new tutorial on using acme.sh with IONOS Cloud DNS to manage SSL/TLS certificates is now available. This tutorial covers the installation, configuration, and automation of certificate renewal.

February 24

February 13

February 3

AI Model Hub supports the models Llama 3.3 (70B) and Teuken (7B). Document collections can now use all supported embedding models, allow for chunking, and support PostgreSQL as an alternative backend.

Documentation updates

February 28

January 2025

What's new

January 27

API Gateway supports a Caching feature that improves API performance and reduces server load. Caching stores the response to an API request and serves it to the client.

January 7

2024 Releases

October 2024

What's new

October 18

The documentation portal now has information on the security advisory for a critical vulnerability reported in Grafana 11. This vulnerability may allow attackers to execute arbitrary code on affected systems, leading to complete system compromise.

October 15

The documentation portal now has information on the security advisory for vulnerabilities reported in the Kubernetes Image Builder that enables default credentials during the image build process.

October 9

October 8

The documentation portal now has information on the security advisory for vulnerabilities reported in the Linux Common Unix Printing System (CUPS). By chaining these vulnerabilities, an attacker could cause remote code execution.

October 7

Information on the security advisory for three vulnerabilities reported by Redis is now available in the documentation portal. These vulnerabilities, reported by Redis, allow an authenticated remote user to execute arbitrary remote code and perform Denial of Service (DoS) attacks.

October 1

Reverse DNS is now available via the IONOS Data Center Designer (DCD). You can leverage its capabilities to create and efficiently manage Reverse DNS (PTR) records for IPv4 and IPv6 addresses.

October 1

The IONOS AI Model Hub now supports Llama 405B from Meta.

Documentation updates

October 17

October 15

June 2024

What's new

June 28

June 10

May 2024

What's new

May 30

May 24

IONOS announces the release of our Certbot plugin for Cloud DNS. With this plugin, you can automate the process of obtaining and renewing SSL/TLS certificate. This feature enhances security and simplifies certificate management for your domains.

May 23

Information on the security advisory for CVE-2024-4323 reported by Tenable Research is now available in the documentation portal. The memory corruption vulnerability in Fluent Bit can result in a denial of service, information disclosure, or remote code execution.

May 17

May 13

May 7

Logging Service is enhanced to allow you to configure an unlimited retention period for your logs. With this enhancement, you can store your logs for an indefinite period. The enhancement is available since April 29, 2024.

May 6

Information on the security advisory for four vulnerabilities reported by Acronis is now available in the documentation portal. These vulnerabilities reported in the Cyber Protect Agent cause local privilege escalation and information manipulation without authorization.

April 2024

What's new

April 30

April 25

IONOS Object Storage has increased the length of all newly generated Access Keys and Secret Keys to prepare for the upcoming new functionalities on the offering. Access Keys will now be 92 characters long, and Secret Keys will be 64 characters long.

April 22

Managed Kubernetes now supports Regional Control Planes, allowing users to deploy and manage Kubernetes clusters to new geographic regions with ease. You can benefit from optimized performance and reduced latency between the control plane and the nodes of the node pools within the same region.

April 10

April 5

Information on security advisory for CVE-2024-3094 is available on the documentation portal. The vulnerability enables remote system breaches via SSH, and immediate action is required to resolve it.

Documentation updates

April 2

We are thrilled to announce the release of our revamped documentation portal landing page. The enhancement includes significant improvements to the design outlook and website navigation to streamline the user experience and to make accessing information more accessible and more efficient.

Card-based Design: Visually appealing card layouts provide users with concise information and an easier way to engage with the documentation portal.

April 2

To reinforce consistency in the product category and product names across IONOS website and documentation portal, the following changes are made effectively:

— The product categories are renamed, added, and removed.

— Some of the product names in our documentation portal are renamed and reorganized into product categories in a way that it improves easy discoverability of documentation.

Note: The product renaming does not have any impact on its services and functionality. Incorporation of the updated product names across our documentation pages is an ongoing development, and we will be rolling out this update in phases.

March 2024

What's new

March 28

IONOS DBaaS provides support for MariaDB clusters to suit your needs. It offers resources such as CPU cores, RAM size (GB), and storage types to create database clusters. Additionally, the database clusters facilitate point-in-time recovery and backup features, making them highly reliable. It also facilitates cloud-based database patching and scalability. The migration process is straightforward due to its compatibility with MySQL.

March 20

March 13

February 2024

What's new

February 27

February 22

February 5

Information on security advisory for CVE-2024-21626 is available on the documentation portal. The vulnerability enables containerized escape for attackers using a malicious image, a malicious Dockerfile, or an upstream image.

February 1

The following significant changes are being made to IONOS APIs, SDKs authentication methods, and token management to enhance user security.

Effective March 15, 2024, the Basic Authentication across IONOS’ APIs and SDKs is completely deprecated for user accounts with 2-Factor Authentication (2FA) enabled or 2FA forced. Impacted users can only generate tokens from the API/SDK Authentication Token Manager.

January 2024

What's new

January 10

2023 Releases

November 2023

What's new

November 28

November 23

Information on security advisory for CVE-2023-23583, also known as Escalation of privilege for some Intel processors vulnerability, is available on the documentation portal. This vulnerability is based on an unexpected behavior for some Intel(R) processors that may allow an authenticated user to potentially enable escalation of privilege and information disclosure or denial of service via local access.

November 15

Documentation updates

November 13

November 1

Information on security advisory for CVE-2023-20569, also known as Return Form Procedure (RET) Speculation or Inception is available on the documentation portal. This vulnerability is reported by AMD as a sensitive information disclosure due to speculative side-channel attacks.

October 2023

What's new

October 26

The documentation portal now contains information about the new security advisories that Acronis reported. You can find more details about the reported vulnerabilities on the following pages:

October 25

VM Auto Scaling is now available as an Early Access (EA) feature. It is a cloud computing feature that dynamically scales in or scales out the number of virtual machine instances (horizontal scaling) based on customizable monitoring events. The metric-based policy, defined during its configuration, constantly monitors the load and regularly scales the number of VM instances based on the policy threshold. The functionality ensures that the number of replicas in the group remains within the defined constraints.

Documentation updates

October 18

The documentation for Backup Service has been updated to include a new section called Install the Acronis Backup Agent on Linux. This section provides prerequisites, step-by-step instructions, and configuration options to ensure a seamless installation experience.

September 2023

What's new

September 20

IONOS offers the New Object Storage Web Console (Beta), an enhanced version of the existing Object Storage Web Console in the DCD, providing improved user experience and performance, intuitive design, and faster responsiveness while having the same feature set as the existing web console. Currently, the feature is in the Beta phase and is available by default to all new and existing users. You are encouraged to try out the new web console. This new application console does not impact the functionality of the existing web console.

September 4

August 2023

What's new

August 18

August 14

IONOS MongoDB database cluster offers MongoDB Enterprise edition supporting versions 5.0 and 6.0 to suit the requirements of enterprise-level deployments. This edition provides advanced capabilities such as sharding database type, enabling the BI Connector, and more resources - CPU cores, RAM size (GB), and storage types to create database clusters. Additionally, the enterprise database clusters facilitate point-in-time recovery and offsite backup features making these clusters highly reliable.

August 10

A vCPU Server is a new virtual machine provisioned and hosted in one of IONOS's physical data centers. It behaves like a physical server and can be used as a standalone product or combined with other IONOS cloud products. To configure a vCPU Server, choose a preset (S, M, L, XL, and XXL) that suits your needs. Presets are a combination of specific vCPU-to-RAM ratios. The number of vCPUs and RAMs differs based on the selected preset. You can also tailor the vCPU-to-RAM ratios to meet your requirements—the Preset automatically changes to Custom when you edit the predefined ratio.

August 8

The documentation for Kubernetes Versions now contains the following details:

Managed Kubernetes releases Kubernetes version 1.27; hence, the Available column now mentions the release date.
Kubernetes version 1.24 has reached an end-of-life; hence, the Kubernetes end of life column has been updated accordingly.

Documentation updates

Note: The documentation portal URLs are directly affected by the below-mentioned updates. As a result, if you have bookmarked specific pages from the documentation portal, we recommend revisiting the pages and bookmarking the new URLs.

August 10

The following sections have been renamed in the documentation portal:

Compute Engine is now called Compute.
Virtual Machines is now called Compute Engine.

August 10

Cloud Cubes is no longer under Virtual Machines, but an independent section under Compute.

July 2023

What's new

July 17

Managed Stackable version 23.4 is now newly available and the only version currently supported for creating a new Managed Stackable cluster. Older clusters retain their original version.

July 7

The documentation for Managed Kubernetes has been updated to include information about the maintenance window as well as the cluster and node pool maintenance processes.

July 7

The documentation for Managed Kubernetes has been updated to include information about Kubernetes versions and their availability.

July 5

The Vulnerability Register serves as a comprehensive record detailing security vulnerabilities that impact IONOS Cloud products and services. This report has been developed as an integral component of our continuous commitment to assist you in effectively mitigating security risks and safeguarding the integrity of your systems.

July 3

Application Load Balancer is now in the General Availability (GA) phase. With the Application Load Balancer (ALB), incoming application layer traffic can be routed to targets based on user-defined rules.

July 3

Network Load Balancer is now in the General Availability (GA) phase. With the Network Load Balancer (NLB), you can automatically distribute workloads over several servers, which minimizes disruptions during scaling.

July 3

NAT Gateway is now in the General Availability (GA) phase. With the NAT Gateway, you can enable internet access to virtual machines without exposing them to the internet by a public interface. It acts as an intermediary device that translates IP addresses between the private network and the public internet.

June 2023

What's new

June 20

June 1

Updates

June 1

Firewall rules configuration for a Network Interface Card (NIC) is now extended to support IPv6. With this enhancement, Firewall rules support ICMPv6 as a protocol, IPv6 addresses as source or destination IPs, and lets you specify the IP version for which a given rule is applicable.

June 1

With IONOS extending IPv6 support to Compute Engine instances, you can now use the Flow Logs to capture data related to IPv6 network traffic flows in addition to IPv4.

May 2023

What's new

May 30

Cloud DNS is now available as an Early Access (EA) feature. You can publish DNS Zones of your domains and subdomains on public Name Servers using Cloud DNS. You may also programmatically manage your DNS Zones and Records via API.

Set up IONOS Cloud

Create a Data Center

Prerequisites:

— Make sure you have the corresponding permissions to create and manage data centers. By default, contract administrators and owners can create a data center.

To create a data center, use one of the following options:

Option 1: From the left navigation panel

In the DCD, go to Virtual Data Centers > Create new. A drop-down window appears.

Provide the following details:

Name: Enter a name to identify the data center uniquely.
Region: From the drop-down list, choose the physical location of the data center that hosts your infrastructure.

Select Create to confirm.

Alternatively, you can also create a data center using the following options:

Option 2: From the DCD home page

In the DCD, go to the My Virtual Data Centers section and click Create new.
Select Create to confirm.

Result: The data center has been created and can be opened in the workspace. Your DCD dashboard displays the newly created VDC in My Virtual Data Centers.

Info: You can log in to the DCD and scale your infrastructure capacity. Alternatively, you can set defaults and create new resources when needed.

Next steps

Set User Privileges for Data Center

Users need appropriate privileges to create and manage data center. The group privilege called Create Data Center must be enabled for a group so that the members of this group inherit it through group privilege settings and can create and manage Virtual Data Center (VDCs).

To set user privileges to create and manage VDCs, follow these steps:

In the DCD, go to Menu > Management > Users & Groups under Users.
Select the Groups tab in the User Manager window.
Select the appropriate group to assign relevant privileges.
In the Privileges tab, select Create Data Center.

Note: You can remove the privileges from the group by clearing Create Data Center.

Result: The privilege to create and manage VDCs is granted to all the members in the selected group.

Revoke user privileges

You can revoke a user's Create Data Center privilege by removing the user from all the groups with this privilege enabled.

Warning: You can revoke a user from this privilege by disabling Create Data Center for every group the user belongs to. In this case, all the members in the respective groups would also be revoked from this privilege.

To revoke this privilege from a contract administrator, disable the administrator option on the user account. After performing this action, the contract administrator will become a contract user, and the privileges that were set up for the user before becoming an administrator will then be in effect.

My Customer Data

To view or update your data, such as the organization's name and address or contact details, follow these steps:

In the DCD, go to Your Profile > My Customer Data.
A My customer data window will open up. You can view the Email Address, a Contract Number, Company name, First name, and Last name.

Select Edit to update the Street address, ZIP, and City in the Address section. Select Save to make changes.

Select Edit to update the primary Contact email address, Billing email address and Phone number associated with your account in the Contact section. You can also add other billing addresses by selecting Add another billing email address. Select Save to make changes.

Result: Your Customer Data will be saved.

Payment Details

You can view and update your account's billing and payment details.

Note:

Only users with the contract owner role are authorized to modify payment details.
Available payment options vary based on the country associated with your contract; as a result, you may see both options or only Credit card. The availability of SEPA Direct Debit is subject to geographic restrictions.

To edit the payment details, follow these steps:

In the DCD, go to Menu > Your Profile > Payment details.
The Payment Details window will open up. You can set up the payment method by selecting Set up payment method. A Change payment method window will open up.
Select the payment methods in Available payment methods to choose from how you would like to pay. The Credit card option is selected by default.

Select Save to make changes.

Result: Your Payment details will be saved.

DCD Default Settings

To edit the default settings, follow these steps:

In the DCD, go to Menu > My Profile > DCD Default Settings.
A My settings window will open up. Set the default values for Session settings, Data Center settings, Server settings, Storage settings, and IP settings from the respective drop-down lists.

Result: Your new settings will be updated immediately. You can undo your changes either by selecting Reset or Reset All.

Management

Manage user access and security policies with features in Identity and Access Management.

Usage provides insights into resource usage, cost incurred, and cost alerts for your account.

Features

Identity and Access Management (IAM)

Users & Groups: Facilitates adding new users, assigning roles, and managing access permissions.
Password Policy: Enforces rules for password strength, expiration, and complexity to ensure secure authentication.
Token Manager: Manages authentication tokens, ensuring secure access control across systems.

Usage

Cost & Usage: Monitors and reports on resource consumption.
Cost Alert: Sends notifications when usage exceeds predefined cost thresholds.
Resource Overview: Provides a comprehensive view of all resources and their limits.

Quick Links

Identity & Access Management

Identity and Access Management (IAM) is a framework of policies and technologies used to ensure that the right users (or entities) have the appropriate access to IONOS Cloud resources. It helps you to control your resources securely and authenticate and authorize access users to use resources and your IONOS Cloud account.

Identity management

When you create an account with IONOS Cloud, you become the contract owner and can access your account using your username and password. To begin with, you login with a sign-in identity and will have access to all the services and resources associated with the account. Ensure that your contract owner credentials are safe.

Next, from your contract owner account, you can set up other users and assign them roles and resources they need. For example, an administrators can have additional permissions whereas or sub-users can have limited permissions.

Access management

Once you create sub-users, they can log in to the IONOS Cloud account using their credentials. The credentials are validated before authorizing access to the resources and privileges associated with the respective user account.

By managing identities and their access privileges, IAM helps protect sensitive data and systems, reducing the risk of unauthorized access. You can control who can access specific resources and ensure compliance with security standards and regulations for your organization.

Access Permissions

To access Identity & Access Management features, select Menu > Management on the top navigation menu of the DCD. You will see the following features in the drop-down menu:

Note: The features are subject to access levels based on the user's role.

Quick Links

Usage

With Usage, you can track your resource usage, cost incurred, and cost alerts for your account.

Access Permissions

To access Usage features, select Menu > Management on the top navigation menu of the DCD. You will see the following features in the drop-down menu:

Note: The features are subject to access levels based on the user's role.

Quick Links

Resource Overview

You can track the global usage of resources available in your account along with the overview of usage limits per instance.

To view the resource overview, follow these steps:

In the DCD, go to Menu > Management > Resource Overview.
A Resource Overview window will open up with a summary of all resources.

AI

Data Handling

As artificial intelligence continues to evolve, it is paramount to ensure that user data is handled responsibly and transparently. This commitment protects user privacy and builds trust in the technology we provide. At IONOS, we strive to uphold the highest standards in data handling while delivering innovative AI solutions through our AI Model Hub.

Data Collection, Usage, and Storage

Stateless Service: AI Model Hub operates as a stateless service, meaning it does not retain user prompts or outputs. Each session is independent, ensuring that your interactions are not logged or recorded for future reference or used to train or improve models.
Data Collections: Customers can upload their documents to a Vector database. Each collection is dedicated to a customer by design and is securely stored in a database in our Berlin data center, ensuring that user data is subject to strict geographic regulations and protections.
Service Logs: We collect standard service logs like any other application. These logs are essential for operational integrity and performance tracking. They are used to:
- Monitor the overall performance and health of the AI Model Hub service.
- Identify and troubleshoot any potential issues that may arise.
- Provide support services effectively when users encounter difficulties.

Data Security

Our infrastructure is hosted in our Berlin data center, designed to meet stringent security standards.

We employ multiple security measures, including:

Encryption protocols to protect data both at rest and in transit.
The use of API key tokens protects API endpoints.
Regular security audits and compliance checks to identify and mitigate potential vulnerabilities.

Privacy Guidelines

Advanced Concepts

We introduce several advanced concepts to help you better understand and apply AI technologies.

Concept 1: Embeddings

Embeddings are layers in deep learning models representing data in a lower-dimensional space. Although they do not make the final prediction themselves, embeddings can help identify semantically similar objects — crucial for tasks such as recommendation, clustering, and search.

Key learnings

Understand the basic idea behind embeddings.
Learn how to use embeddings to measure semantic similarity.

Concept 2: Tool Calling

Tool calling allows a model to access external tools—such as APIs, databases, or custom functions—at runtime. Developers define the available tools in the model's prompt, and the model learns to decide when to use a tool versus when to answer based on its internal knowledge. This enables language models to work with up-to-date, private, or computational information they couldn't otherwise access.

Key learnings

Understand how tool calling extends a model’s functionality beyond its training data.
Learn what tool calling enables and where its limitations lie.

Embeddings

One seemingly simple task for humans is identifying semantically similar concepts. Take the following three texts, for example:

"AI Model Hub"
"Michael Jackson"
"best-selling music artists"

For a human, it is easy to tell that "Michael Jackson" and "best-selling music artists" are related, while "AI Model Hub" is not.

Embeddings, a core concept in modern foundation models, provide an effective way for machines to perform this kind of semantic comparison. An embedding is a numerical vector representation of a text, where the key property is this: semantically similar texts have similar vectors.

Semantic similarity

To illustrate this, imagine we convert the three example texts into embeddings:

"AI Model Hub": (0.10; 0.10)
"Michael Jackson": (0.95; 0.90)
"best-selling music artists": (0.96; 0.87)

In practice, embedding vectors have dozens or even thousands of dimensions. Here, we simplify them to 2D for clarity. These embeddings can be visualized like this:

As shown, the embeddings for "Michael Jackson" and "best-selling music artists" are close to each other, while "AI Model Hub" is farther away, mirroring our intuitive understanding.

Embedding models are models that convert data—like text, into these embeddings. They exist for different types of content, including text (in one or multiple languages), images, audio, and more. The IONOS AI Model Hub supports embedding models for English text and multilingual models.

To measure how similar two embeddings are, we use a similarity score. One commonly used metric is cosine similarity, which calculates the cosine of the angle between two vectors. The score ranges from -1 to 1:

1: very similar
0: unrelated
-1: opposite meanings (in rare cases)

Explore further

Use Cases

Below, we present two use cases that showcase practical applications of AI, complete with source code you can use immediately.

Use Case 1: Enrich Text with AI-Generated Images

Key Learnings

Understand the benefits of enriching text with AI-generated images.
Generate photorealistic or stylized images tailored to your needs.

Use Case 2: Intelligent Document Search with AI

Key Learnings

Understand how document collections are used to store documents based on semantic similarity.
Upload documents to a searchable collection for easy retrieval.
Improve search accuracy and relevance for user queries.

FAQs

The AI Model Hub is focused on offering an API. While this is great in terms of integrating the solution into your existing code , it has a downside: Errors and problems that arise are often not obvious enough to fix. This FAQ gathers the most important issues:

How do I fix an unauthorized, incorrect, or no API key error?

IONOS_API_TOKEN is not set: Check whether your system's environment variable is set. The simplest way to do this is by adding the line
to your code. If nothing is shown, the environment variable is not set. Please set it.

How do I fix a `404 Not Found` error?

Communication with the AI Model Hub is by API endpoints. These endpoints often contain IDs, like the Collection ID, a Model ID or some similar ID. One typical example of such an API endpoint is the endpoint to see all uploaded documents in a specific document collection:

Notice that the variable COLLECTION_ID is part of the API endpoint URL. If you, for example, have previously deleted this endpoint, a request to it will return a '404 Not Found' error.

To ensure the ID exists, invoke the higher-level endpoint with a get request. This will return a list of all entries, and you can choose one of the existing IDs. In the above example, the Python command could be:

An entry item exists in the resulting JSON document, which gathers all available document collections.

How do I fix a `500 Internal Server` error?

Compute Services

Compute Engine

Product Overview

How-Tos

Developer Tools

Frequently Asked Questions (FAQs)

DCD How-Tos

Connect via Remote Console

Prerequisites: Make sure you have the appropriate permissions. Only contract administrators, owners, or users with access rights to the data center can connect to a server. Other user types have read-only access and cannot provision changes.

Start the Remote Console from the server.
Log in to the DCD with your credentials.
In the Workspace, select the server.
In the Inspector pane, choose Console or select Console from the context menu of the server.
Start the Remote Console from the Start Center (contract owners and administrators only).

Open the Start Center by clicking on the Menu Bar > Data Center Designer > Open Start Center.

Open the Details of the required data center. A list of servers in this data center is displayed.
Select the server and click Open Remote Console.

Result: Remote Console version matching your browser opens; you can now log in to the server with the root or administrator password.

Connect to Virtual Machines via SSH

Note: Connecting via SSH is only possible with the Linux operating system, not Windows, because IONOS Windows images do not support SSH key injection.

Establish connection using SSH Keys

With SSH key-based authentication, you can establish secure connections to your Linux VMs. An SSH key is composed of a public-private key pair:

A private key: It stays on your local system. Ensure that you do not share your private key.
A public key: It is saved on your VM and enables you to access your provisioned VMs.

When you connect to your VM (which has the public key) using an SSH client, the remote VM validates the private key of the client. The client can access the VM only if the client has the correct private key.

Supported SSH Key types

SSH keys are necessary to connect via SSH. The following are the types of SSH keys that can be used for an SSH connection:

Keys from the SSH Keys view

Ad-hoc SSH Keys

SSH keys that you intend to use often, either as default or non-default.

SSH keys that you only use once and do not intend to save in the SSH Keys view for reuse.

Select the Default checkbox in the SSH Keys to set them as default SSH keys.

An Ad-hoc SSH Key cannot be set as default.

Default SSH keys are preselected when you configure storage devices.

An Ad-hoc SSH Key must be specified manually.

Clear the Default checkbox if you do not want to set them as default. However, you can still associate a non-default SSH key while adding storage to a VM element.

You can specify only one Ad-hoc SSH Key when you associate a storage with the VM element.

Workflow

You can connect to the VM via SSH in the following ways:

Generate SSH keys

To generate SSH keys, ensure that you have ssh-keygen command-line tool installed. ssh-keygen is a utility for generating SSH key pairs and storing them in a secure location. With these keys, you can connect to your instances without encountering the login prompt. You can use the SSH keys on a macOS or a Linux using an SSH client.

You can manually generate SSH keys when working with a SSH client using the following:

Enter the following command into the terminal window on your computer and press ENTER.

Result: The key generation process is initiated by the command above. When you run this command, the ssh-keygen utility prompts you for a location to save the key.

Accept the default location by pressing the ENTER key, or enter the path to the file where you want to save the key /home/username/.ssh/id_rsa.

If you have previously generated a key pair, you may see the following prompt. If you choose to overwrite the key, you will no longer authenticate with the previous key.

Enter the passphrase that will be used to encrypt the private key file on the disk. You can also press ENTER to accept the default (no passphrase) SSH key. However, we recommend that you use a passphrase.
Enter your passphrase once more.

You can copy the public key to your clipboard by running the following command:

Manage SSH keys

The DCD's SSH Keys view allows you to save and manage up to 100 public SSH keys for SSH access setup. This saves you from having to copy and paste the public part of an SSH key from an external source multiple times.

Store SSH Keys in the DCD

To save your SSH key in the DCD, follow these steps:

Log in to the DCD with your credentials.
Go to Menu > Management > SSH Keys.

Select + Add Key in the top left corner.

Enter a Name and click Add.
Paste the SSH key from the clipboard into the SSH key field. If you have saved your SSH key in a file, you can upload it by selecting the Choose file button in the Select Key file field.

Note: Make sure the SSH keys you enter are valid. The DCD does not validate the syntax or format of the keys.

(Optional:) Select the Default checkbox to have the SSH key pre-selected when configuring SSH access. Clear the checkbox if you do not want the key to be set as default.
Click Save to save the key.

Result: The SSH key is visible and saved in the SSH Keys view. It can be used for the configuration of SSH accesses.

Delete an SSH key

To delete an existing SSH key, follow these steps:

Log in to the DCD with your credentials.
Go to Menu > Management > SSH Keys.
Select the respective SSH key from the list.
Click Delete Key.
Click OK in the Delete SSH key confirmation dialog box.

Result: The selected SSH key is deleted.

Associate an SSH key with a VM

To associate an SSH key with a Linux storage image of a VM, follow these steps:

Log in to the DCD with your credentials.
If a VM does not exist, drag a VM element (a Dedicated Core server, a vCPU Server, or a Cube) from the palette onto the workspace based on your needs. Else, you can choose to add storage to an existing VM.
Click + on the VM to attach storage.

Based on the need, either associate an HDD or an SSD storage by choosing one of these options: Create and attach HDD Storage or Create and attach SSD Storage.

Click Create HDD Storage or Create SSD Storage. The option differs based on the storage type you have chosen.

Result: The selected SSH key is associated with your VM.

Connect to your VM (Linux) instance via an SSH client

You can connect to your VM instance using an SSH client. However, it varies depending on your operating system.

Linux: Search Terminal or press CTRL+ALT+T.
macOS: Search Terminal.
Windows: Search Bash. If you do not have it installed, use PuTTY instead.

Follow these steps to connect to your VM:

For a private key, ensure that you have the location of the private key (.pem file), the username, and the public DNS name. Enter the following command:

Note: — When you log in for the first time, your local machine does not recognize the server, so you will be prompted to continue the connection. You can type yes and then press ENTER.

Authentication is the next step in the connection process. You will be able to connect to the VM immediately if you have added the SSH keys or after entering your key pair's passphrase.

If you have not already added SSH keys, you will be prompted for your password:

The terminal remains empty for you to paste the initial password into. Pasting into text-based terminals is different from desktop applications. It is also different from one window manager to another:

For Linux Gnome Terminal, use CTRL+SHIFT+V.
For macOS, use the SHIFT-CMD-V or a middle mouse button.
For Bash on Windows, right-click on the window bar, choose Edit, then Paste. You can also right-click to paste if you enable the QuickEdit mode.

Press ENTER after you enter the password.

Result: You can log in to your VM instance if the SSH key is configured correctly.

Product Renaming FAQs

The following are a few FAQs to provide an insight about renaming the product from Virtual Server(s) to Dedicated Core Server(s).

What is the reason for renaming "Virtual Servers" to "Dedicated Core Servers"?

The name change is part of our ongoing efforts to better reflect the performance and benefits of our Virtual Machines. "Dedicated Core Servers" emphasizes the dedicated nature of the compute resources assigned to each instance, ensuring consistent performance and increased reliability.

Will there be any changes in the features or specifications of the product with this name update?

No, there won't be any changes in the features or specifications of the product. The only update is the product name from "Virtual Servers" to "Dedicated Core Servers".

What is the difference between "Virtual Servers" and "Dedicated Core Servers"?

The underlying technology and capabilities of the Virtual Machines remain the same. The primary difference lies in the name. With "Dedicated Core Servers," you can still expect virtualized environments but with the added emphasis on dedicated resources per instance.

Will the pricing change with this new name?

There will be no changes to the pricing structure due to the name update. The costs and billing for our Virtual Machines, now known as "Dedicated Core Servers," will remain the same as they were for "Virtual Servers."

Are "Dedicated Core Server" instances isolated from each other?

Yes, "Dedicated Core Server" instances are isolated from one another. Each instance operates independently, with dedicated CPU cores, memory, and storage, ensuring a high level of performance and security.

How will this name change affect existing users of "Virtual Servers"?

Existing users of "Virtual Servers" will experience no functional changes or disruptions due to the name update. Your current virtual server instances will be referred to as "Dedicated Core Server" instances from now on.

Can I still use the same APIs and tools to manage Dedicated Core Servers?

Yes, you can continue to use the same APIs and tools that were used to manage regular virtual servers for the newly renamed Dedicated Core Servers.

Are there any actions I need to take as a user after this renaming?

No, as a user, you do not need to take any action. The name change is purely cosmetic, and your existing configurations and access to your instances will remain unchanged.

Will there be any updates to the user interface or API documentation as a result of this name change?

Yes, we will update the user interface and API documentation to reflect the new name "Dedicated Core Servers". Rest assured, the changes will be cosmetic, and the functionality will remain consistent.

Can I still create and manage multiple "Dedicated Core Servers" instances under my account?

Absolutely! You can continue to create and manage multiple "Dedicated Core Server" instances as per your requirements, just as you did with "Virtual Servers."

Where can I find more information or support regarding "Dedicated Core Server" instances?

For more information or support, you can refer to our documentation on the "Dedicated Core Server" product page on our documentation portal. Additionally, our customer support team is available to assist you with any questions or concerns you may have.

Changes to AMD Opteron Virtual Machines

Note: Starting July 29th, creating new VMs with AMD Opteron CPUs will no longer be possible. Existing VMs can continue to run and will be unaffected by this change. They can also undergo normal power cycles without impacting functionality.

Best practices for provisioning new Opteron VMs

For Terraform Users

Configuration check:

Ensure that the cpu_family parameter in your Terraform configuration file (*.tf) is not set to AMD_OPTERON.

Provisioning:

Before provisioning new VMs, verify that the Terraform configuration file (*.tf) is updated appropriately.
Run terraform plan to confirm the configuration is correct.
Provision the VM using terraform apply.

For Crossplane Users

Configuration check:

If the specification file has the cpuFamily set to AMD_OPTERON, it should be updated to avoid errors.
Failure to update the cpuFamily parameter will result in an error when managing VMs.

Verification:

Check your specification files for the cpuFamily parameter.
Update the parameter from AMD_OPTERON to the appropriate value according to your needs.

Limitations while creating new VMs with AMD Opteron

These limitations apply when you try to create new VMs:

You cannot select AMD Opteron as the CPU architecture for New VMs.
You cannot switch a running or deallocated VM's CPU family to AMD Opteron.

Migrate from AMD Opteron Servers in Frankfurt (de/fra)

As we prepare to phase out the AMD Opteron servers in Frankfurt (de/fra), this article serves as a detailed guide to help you transition your AMD Opteron-based Compute Engine workloads to other server options within the Frankfurt location.

Important: You should perform the necessary changes from April 1, 2025, until May 13, 2025. After that period, we will change the CPU architecture of the remaining servers to AMD Epyc, ensuring continued operation, as we will be decommissioning the AMD Opteron physical hardware from this location.

Migration options and instructions

Important notice regarding software licensing

As you plan to migrate your Virtual Machines (VMs) from Opteron-based processors to newer options like Dedicated Core - AMD Epyc or vCPU Servers, please be aware of potential licensing implications for software running on your VMs.

Key points

Licensing on logical processors

Specific software licenses are explicitly tied to the number of logical processors recognized by the operating system. Opteron processors utilize a one-core, one-thread configuration. In contrast, newer processors like EPYC or those used in vCPU Servers use hyper-threading, where each core has two threads and is recognized as two separate logical processors.

Impact of migration

When migrating to hyper-threaded CPUs, a VM configured for a single logical processor on Opteron will appear to have precisely two logical processors on newer CPUs. It could impact your software licenses, as they may not authorize the additional logical processor, potentially leading to compliance issues and operational disruptions.

Recommendation

Review your software licensing agreements before migration and ensure compliance with the license terms when configuring VMs on hyper-threaded CPUs.

Cubes

Cubes are virtual private service instances with shared resources. Refer to our user guides, reference documentation, and FAQs to support your hosting needs.

Product Overview

How-Tos

Developer Tools

Frequently Asked Questions (FAQs)

DCD How-Tos

Enable IPv6

You can enable IPv6 on Cubes when you create them or after you create them.

Set up IPv6

You can set up IPv6 to improve the network connectivity for your virtualized environment. By setting up IPv6 for your Cubes, you can ensure that they are accessible to IPv6-enabled networks and clients.

Prerequisites:

Prior to enabling IPv6, make sure you have the appropriate privileges. New VDC can be created by the contract administrators, owners, or users with the Create VDC privilege.

Note:

The number of bits in the fixed address is the prefix length. For Data Center IPv6 CIDR, the prefix length is /56.
IPv6 CIDR assigned to LANs(/64) and NICs(/80 and /128) must be unique.
You can create a maximum of 256 IPv6-enabled LANs per VDC.

Log in to DCD with your username and password.
Select the Network option on the right pane for the specific Cube and enter the following:

Name: It is recommended to enter a unique name for this Network Interface Controller (NIC).
MAC: This field is automatically populated.
LAN: Select an IPv6 enabled Local Area Network (LAN).
Firewall: Specify whether you want to enable or disable the firewall. For enabling the firewall, choose Ingress to create flow logs for incoming traffic, Egress for outgoing traffic, or Bidirectional to create flow logs for all traffic.
Flow Log: Select + to add a new flow log. Enter name, direction, action, target S3 bucket, and select + Flow Log to complete the configuration of the flow log. It becomes applied once you provision your changes.
IPv4 Configuration: This field is automatically populated. If Dynamic Host Configuration Protocol (DHCP) is enabled, the Internet Protocol version 4 (IPv4) address is dynamic, meaning it can change while the Dedicated Core Server is operational or in the case of a restart. Add additional public IP addresses in Add IP. It is an optional field.
IPv6 Configuration: You can populate a NIC IPv6 CIDR block with prefix length /80 or allow it to be automatically assigned from the VDCs allocated range, as seen in the screenshot below. In order to use "floating" or virtual IPs, you can assign additional IPs to a NIC by selecting them from the drop-down list in Add IP.

Click PROVISION CHANGES.

Generate SSH keys

You can manually generate SSH keys when working with a SSH client using the following:

Enter the following command into the terminal window on your computer and press ENTER.

Result: The key generation process is initiated by the command above. When you run this command, the ssh-keygen utility prompts you for a location to save the key.

Accept the default location by pressing the ENTER key, or enter the path to the file where you want to save the key /home/username/.ssh/id_rsa.

If you have previously generated a key pair, you may see the following prompt. If you choose to overwrite the key, you will no longer authenticate with the previous key.

Enter the passphrase that will be used to encrypt the private key file on the disk. You can also press ENTER to accept the default (no passphrase) SSH key. However, we recommend that you use a passphrase.
Enter your passphrase once more.

You can copy the public key to your clipboard by running the following command:

 pbcopy < ~/.ssh/id_rsa.pub

Manage SSH keys

Store SSH Keys in the DCD

To save your SSH key in the DCD, follow these steps:

Log in to the DCD with your credentials.
Go to Menu > Management > SSH Keys.

Select + Add Key in the top left corner.

Enter a Name and click Add.
Paste the SSH key from the clipboard into the SSH key field. If you have saved your SSH key in a file, you can upload it by selecting the Choose file button in the Select Key file field.

Note: Make sure the SSH keys you enter are valid. The DCD does not validate the syntax or format of the keys.

(Optional:) Select the Default checkbox to have the SSH key pre-selected when configuring SSH access. Clear the checkbox if you do not want the key to be set as default.
Click Save to save the key.

Result: The SSH key is visible and saved in the SSH Keys view. It can be used for the configuration of SSH accesses.

Delete an SSH key

To delete an existing SSH key, follow these steps:

Log in to the DCD with your credentials.
Go to Menu > Management > SSH Keys.
Select the respective SSH key from the list.
Click Delete Key.
Click OK in the Delete SSH key confirmation dialog box.

Result: The selected SSH key is deleted.

Associate an SSH key with a VM

To associate an SSH key with a Linux storage image of a VM, follow these steps:

Log in to the DCD with your credentials.
If a VM does not exist, drag a VM element (a Dedicated Core server, a vCPU Server, or a Cube) from the palette onto the workspace based on your needs. Else, you can choose to add storage to an existing VM.
Click + on the VM to attach storage.

Based on the need, either associate an HDD or an SSD storage by choosing one of these options: Create and attach HDD Storage or Create and attach SSD Storage.

Click Create HDD Storage or Create SSD Storage. The option differs based on the storage type you have chosen.

Result: The selected SSH key is associated with your VM.

Compute Engine FAQs

Dedicated Core Servers

What are the maximum resources available for a Server?

Cores

Dedicated Core Server configurations are subject to the following limits, according to the CPU type:

AMD CPU: Up to 62 cores and 230 GB RAM
Intel® CPU: Up to 51 Intel® cores and 230 GB RAM

Info: — A single physical core with Hyper-Threading Technology is exposed to the operating system of your Dedicated Core Server as two distinct “logical cores”, which process separate threads. — Each individual CPU of a Windows machine is considered a socket by the system.

Warning: Because the size of the working memory (RAM) cannot be processed during the initial configuration, newly provisioned servers with more than 8 GB of RAM may not start successfully when created from IONOS Windows images.

We recommend initially setting the RAM size to 8 GB; RAM size can then be scaled as needed after the initial provisioning and configuration.

HDD storage

Minimum per volume: 1 GB
Maximum per volume: 4 TB

SSD storage

Minimum per volume: 1 GB
Maximum per volume: 4 TB

Note: You can scale up the HDD and SSD storage volumes as needed.

What are the Availability Zones?

IONOS data centers are divided into separate areas called Availability Zones.

You can enhance reliability and set up high-availability scenarios by deploying redundant Dedicated Core Servers and storage devices across multiple Availability Zones.

How do I change the Availability Zone?

Select the server in the DCD Workspace
Use Inspector > Properties > Availability Zone menu to change the Availability Zone

What is Live Vertical Scaling?

Live Vertical Scaling (LVS) technology permits you to scale the number of CPU cores and amount of RAM while the server is running, without having to restart it. Please note that Windows only allows scaling the number of CPU cores, but not the amount of RAM. For scaling to more than eight CPU cores, Windows requires a reboot.

Warning: RAM hotplugging for a VM is automatically disabled when the RAM size exceeds 240 GB. This leads to the VM restarting every time the RAM is increased beyond this limit, disabling live vertical scaling.

Why do I sometimes see steal time in my Dedicated Core servers?

How do I reboot a Dedicated Core server?

Dedicated Core servers can be restarted at the operating system level (using the reboot command, for instance). You can also use the DCD reset function, which functions similarly to a physical server's reset button.

How do I shut down a Dedicated Core server?

You should use the DCD to shut down your server completely. Your VM will then be marked as "shut down" in the DCD. Shutting down a VM at the operating system level alone does not deallocate its resources or suspend the billing.

How do I delete a Dedicated Core server?

You can delete a Dedicated Core server from the DCD Workspace by right-clicking on it and selecting Delete Server from the list, or by selecting the server and pressing the Del key on your keyboard.

What do I do when my VM isn't accessible?

Try to connect to your VM using the Remote Console to see if it is up and running. If you have trouble logging on to your VM, please provide our support team with screenshots of error messages and prompts from the Remote Console.

Windows users: Please send us a screenshot of the Task Manager.
Linux users: Please send us the output of uptime and top.

How do I get the root/admin passwords with IONOS images?

For IONOS-provided images, you can set the passwords before provisioning.

Why does my newly provisioned server not start?

Newly provisioned servers with more than 8 GB of RAM may not start successfully when created from IONOS Windows images, because the RAM size cannot be processed during the initial configuration.

An error is displayed according to the server version; for example, Windows Server 2012 R2 displays the following message:

"Windows could not finish configuring the system. To attempt to resume configuration, restart the computer."

We recommend initially setting the RAM size to 8 GB, and rescaling it as needed after the initial provisioning and configuration is complete.

Which CPU architecture should I choose?

The choice of CPU architecture primarily depends on your workload and performance requirements. Intel® processors are oftentimes more powerful than AMD processors. Intel® processors are designed for compute-intensive applications and workloads where the benefits of hyperthreading and multitasking can be fully exploited. Intel® cores cost twice as much as AMD cores. Therefore, it is recommended that you measure and compare the actual performance of both CPU architectures against your workload. You can change the CPU type in the DCD or use the API, and see for yourself whether Intel® processors deliver significant performance gains or more economical AMD cores still meet your requirements.

IONOS is the only cloud computing provider with the unique "Core Technology Choice" feature that can flexibly change the processor architecture per virtual instance.

What do I do if the cursor in the Remote Console disappears?

When the cursor disappears after logging on to the Remote Console, you can reconnect to the server using the appropriate menu entry.

vCPU Servers

What are the maximum resources available for a vCPU Server?

vCPUs

vCPU Server configurations are subject to the following limits:

Up to 60 vCPUs and 230 GB RAM

A CPU Family of a vCPU server cannot be chosen at the time of creation and cannot be changed later.

Note: — A single vCPU with Hyper-Threading Technology is exposed to the operating system of your vCPU Server as two distinct “logical cores”, which process separate threads. — Each individual CPU of a Windows machine is considered a socket by the system.

We recommend initially setting the RAM size to 8 GB; RAM size can then be scaled as needed after the initial provisioning and configuration.

HDD storage

Minimum per volume: 1 GB
Maximum per volume: 4 TB

SSD storage

Minimum per volume: 1 GB
Maximum per volume: 4 TB

Note: You can scale up the HDD and SSD storage volumes as needed.

What are the Availability Zones?

IONOS data centers are divided into separate areas called Availability Zones.

You can enhance reliability and set up high-availability scenarios by deploying redundant vCPU Servers and storage devices across multiple Availability Zones.

How do I change the Availability Zone?

Select the vCPU Server in the DCD Workspace.
Navigate to the Inspector pane > Properties > Availability Zone menu to change the Availability Zone.

What is Live Vertical Scaling?

How do I reboot a server?

Servers can be restarted at the operating system level (using the reboot command, for instance). You can also use the DCD reset function, which functions similarly to a physical server's reset button.

How do I shut down a server?

How do I delete a server?

You can delete a server from the DCD Workspace by right-clicking on it and selecting Delete Server from the list, or by selecting the server and pressing the Del key on your keyboard.

What do I do when my VM isn't accessible?

Windows users: Please send us a screenshot of the Task Manager.
Linux users: Please send us the output of uptime and top.

How do I get the root/admin passwords with IONOS images?

For IONOS-provided images, you can set the passwords before provisioning.

Why does my newly provisioned server not start?

Newly provisioned servers with more than 8 GB of RAM may not start successfully when created from IONOS Windows images, because the RAM size cannot be processed during the initial configuration.

An error is displayed according to the server version; for example, Windows Server 2012 R2 displays the following message:

"Windows could not finish configuring the system. To attempt to resume configuration, restart the computer."

We recommend initially setting the RAM size to 8 GB, and rescaling it as needed after the initial provisioning and configuration is complete.

Which CPU architecture should I choose?

A CPU Family of a vCPU server cannot be chosen at the time of creation and cannot be changed later.

What do I do if the cursor in the Remote Console disappears?

When the cursor disappears after logging on to the Remote Console, you can reconnect to the server using the appropriate menu entry.

PVPanic Device

What is the PVPanic device for?

The device monitors VM/OS crashes. PVPanic is a simulated device, through which a guest panic event is sent to the hypervisor, and a QMP event is generated.

Do I need to restart the VM to get PVPanic?

No, the PVPanic device is plug-and-play. However, installing drivers may require a restart.

What happens if Windows VMs complain about an unknown device?

This is no cause for concern. First of all, you do not need to reboot the VM. However, you will need to reinstall the appropriate drivers (which are provided by IONOS Cloud).

Are there any risks when enabling the use of PVPanic?

There are no issues found when enabling pvpanic. However, users cannot choose whether or not to enable the device; it is always available for use.

Something else to consider - PVPanic does not offer bidirectional communication between the VM and the hypervisor. Instead, the communication only goes from the VM towards the hypervisor.

Are there any compatibility issues with AMD or Intel processors?

There are no special requirements or limitations to any components of a virtualized server. Therefore, PVPanic is completely compatible with AMD and Intel processors.

Do we support hardware solutions?

The PVPanic device is implemented as an ISA device (using IOPORT).

Does my Linux image support the Pvpanic device?

Check the kernel config CONFIG_PVPANIC parameter.

For example:

root@debian:~# grep --color CONFIG_PVPANIC /boot/config-$(uname -r) 
CONFIG_PVPANIC=m

m = PVPanic device is available as module y = PVPanic device is native available in the kernel n = PVPanic device is not available

When the device is not available (CONFIG_PVPANIC=n), use another kernel or image.

How do I install the device driver for the pvpanic device on Windows?

For your virtual machines running Microsoft Windows, we provide an ISO image that includes all the relevant drivers for your instance. Just log into DCD, open your chosen virtual data center, add a CD-ROM drive and insert the driver ISO as shown below (this can also be done via CloudAPI).

Note: A reboot is mandatory to add the CD drive.

Once provisioning is complete, you can log into your OS by adding drivers for the unknown device through the Device Manager. Just enter devmgmt.msc in the Windows search bar, console, or PowerShell to open it.

Since this is a Plug & Play driver, there is no need to reboot the machine.

Retrieval Augmented Generation

The IONOS AI Model Hub allows you to combine Large Language Models and a vector database to implement Retrieval Augmented Generation use cases.

Retrieval Augmented Generation is an approach that allows you to teach an existing Large Language Model, such as LLama or Mistral, to answer not only based on the knowledge the model learned during training, but also based on the knowledge you specified yourself.

Retrieval Augmented Generation uses two components:

If one of your users queries your Retrieval Augmented Generation system, you first get the most similar documents from the corresponding document collection. Second, you ask the Large Language Model to answer the query by using both the knowledge it was trained on and the most similar documents from your document collection.

Overview

This tutorial is intended for developers. It assumes you have basic knowledge of:

REST APIs and how to call them
A programming language to handle REST API endpoints (for illustration purposes, the tutorials use Python and Bash scripting)

You are familiar with:

By the end of this tutorial, you'll be able to: Answer customer queries using a Large Language Model which adds data from your document collections to the answers.

Background

The IONOS AI Model Hub API offers both document collections and Large Language Models that you can use to implement retrieval augmented generation without having to manage corresponding hardware yourself.
Our AI Model Hub API provides all required functionality without your data being transferred out of Germany.

Before You Begin

You will need this identifier in the subsequent steps.

To get started, open your IDE to enter Python code.

Next generate a header document to authenticate yourself against the endpoints of our REST API:

# Python example to specify header

IONOS_API_TOKEN = [YOUR API TOKEN HERE]
header = {
    "Authorization": f"Bearer {API_TOKEN}", 
    "Content-Type": "application/json"
}

After this step, you have one variable header you can use to access our vector database.

To get started, open a terminal and ensure that curl and jq are installed. While curl is essential for communicating with our API service, we use jq throughout our examples the improve the readability of the results of our API.

Download the respective code files to easily access retrieval augmented generation-specific scripts and examples and generate the intended output:

Download this Python Notebook file to easily access retrieval augmented generation-specific scripts and examples and generate the intended output.

Download this Python code file to easily access retrieval augmented generation-specific scripts and examples and generate the intended output.

Download this Bash code file to easily access retrieval augmented generation-specific scripts and examples and generate the intended output.

Access List of Available Large Language Models

To retrieve a list of Large Language Models supported by the IONOS AI Model Hub API enter:

# Python example to get all available models
import requests

IONOS_API_TOKEN = [ YOUR API TOKEN HERE ]
header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}
requests.get("https://inference.de-txl.ionos.com/models", headers=header).json()

#!/bin/bash

IONOS_API_TOKEN=[ YOUR API TOKEN HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     --get https://inference.de-txl.ionos.com/models

This query returns a JSON document consisting of all foundation models and corresponding meta information.

The JSON document consists an entry items*. This is a list of all available foundation models. Of the 7 attributes per foundation model 3 are relevant for you:

id: The identifier of the foundation model
properties.description: The textual description of the model
properties.name: The name of the model

Note:

The identifiers for the foundation models differ between our API for Retrival Augmented Generation and for the image generation and text generation endpoints compatible with OpenAI.

From the list you generated in the previous step, choose the model you want to use and the id. You will use this id in the next step to use the foundation model.

Manual Retrieval Augmented Generation

This section shows how to use the document collection and the contained documents to answer a user query.

Step 1: Retrieve Relevant Documents

To retrieve the documents relevant to answering the user query, invoke the query endpoint as follows:

# Python example to retrieve relevant documents
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
USER_QUERY = [ USER QUERY HERE ]
NUM_OF_DOCUMENTS = [ NUMBER OF DOCUMENTS TO CONSIDER HERE ]

endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}/query"
body = {"query": USER_QUERY, "limit": NUM_OF_DOCUMENTS }
relevant_documents = requests.post(endpoint, json=body, headers=header)

relevant_documents_decoded = [
    base64.b64decode(entry['document']['properties']['content']).decode()
    for entry in relevant_documents.json()['properties']['matches']
]

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
USER_QUERY=[ USER QUERY HERE ]
NUM_OF_DOCUMENTS=[ NUMBER OF DOCUMENTS TO CONSIDER HERE ]

BODY='{"query": "'$USER_QUERY'", "limit": '$NUM_OF_DOCUMENTS' }'
RESULT=$(\
    curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
         -H "Content-Type: application/json" \
         -d "$BODY" \
         https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/query \
)
RELEVANT_DOCUMENTS_DECODED=$( \
    echo "$RESULT" | \
    jq -r '.["properties"]["matches"][].["document"]["properties"]["content"]' | \
    base64 --decode \
)

This will return a list of the NUM_OF_DOCUMENTS most relevant documents in your document collection for answering the user query.

Step 2: Generate Final Answer

Now, combine the user query and the result from the document collection in one prompt:

# Python example to retrieve relevant documents
import requests

MODEL_ID = [ YOUR MODEL ID HERE]
endpoint = f"https://inference.de-txl.ionos.com/models/{MODEL_ID}/predictions"
prompt = f"""
    <|begin_of_text|><|start_header_id|>system<|end_header_id|>
    Please use the information specified as context to answer the question.
    Formulate you answer in one sentence and be an honest AI.<|eot_id|>
    <|begin_of_text|><|start_header_id|>context<|end_header_id|>
    {"; ".join(relevant_documents_decoded)}<|eot_id|>
    <|start_header_id|>user<|end_header_id|>
    {USER_QUERY}<|eot_id|>
    <|start_header_id|>assistant<|end_header_id|>
"""
body = { "properties": {"input": prompt} }
requests.post(endpoint, json=body, headers=header).json()

#!/bin/bash

MODEL_ID=[ YOUR MODEL ID HERE]
QUERY="<|begin_of_text|><|start_header_id|>system<|end_header_id|> \
    Please use the information specified as context to answer the question. \
    Formulate you answer in one sentence and be an honest AI.<|eot_id|> \
    <|begin_of_text|><|start_header_id|>context<|end_header_id|> \
    ${RELEVANT_DOCUMENTS_DECODED}<|eot_id|> \
    <|start_header_id|>user<|end_header_id|> \
    ${USER_QUERY}<|eot_id|> \
    <|start_header_id|>assistant<|end_header_id|>"
BODY='{ "properties": {"input": "'${QUERY}'"} }'
RESULT=$( \
    curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
            -H "Content-Type: application/json" \
            -d "$BODY" \
            https://inference.de-txl.ionos.com/models/${MODEL_ID}/predictions \
)

The result will be a JSON-Document consisting of the answer to the customer and some meta information. You can access it in the field at properties.output

Note:

The best prompt strongly depends on the Large Language Model used. Adapt your prompt to improve results for the specific Large Language Model.

Automated Retrieval Augmented Generation

The IONOS AI Model Hub allows for automating the process described above. Namely, by specifying the collection ID and the collection query directly to our foundation model endpoint, it first queries the document collection and returns it in a variable which you can then directly use in your prompt. This section describes how to do this.

Apply Combined Retrieval Augmented Generation Prompt to Foundation Model

To implement a Retrieval Augmented Generation use case with only one prompt, you must invoke the /predictions endpoint of the Large Language Model you want to use and send the prompt as part of the body of this query:

# Python example to retrieve relevant documents
import requests

MODEL_ID = [ YOUR MODEL ID HERE]
COLLECTION_ID = [ YOUR COLLECTION ID HERE]
USER_QUERY = [ USER QUERY HERE ]

endpoint = f"https://inference.de-txl.ionos.com/models/{MODEL_ID}/predictions"
body = { "properties": {
    "input": f"""
    <|begin_of_text|><|start_header_id|>system<|end_header_id|>
    Please use the information specified as context to answer the question.
    Formulate you answer in one sentence and be a honest AI.<|eot_id|>
    <|begin_of_text|><|start_header_id|>context<|end_header_id|>
    {{{{.context}}}}<|eot_id|>
    <|start_header_id|>user<|end_header_id|>
    {{{{.collection_query}}}} <|eot_id|>
    <|start_header_id|>assistant<|end_header_id|>
    """,
    "collectionId": COLLECTION_ID,
    "collectionQuery": USER_QUERY,
    "options": {  
        "max_length": "500",  
        "temperature": "0.01"
    }  
}}
requests.post(endpoint, json=body, headers=header).json()

#!/bin/bash

MODEL_ID=[ YOUR MODEL ID HERE]
COLLECTION_ID=[ YOUR COLLECTION ID HERE]
USER_QUERY=[ USER QUERY HERE ]

QUERY="<|begin_of_text|><|start_header_id|>system<|end_header_id|> \
    Please use the information specified as context to answer the question. \
    Formulate your answer in one sentence and be an honest AI.<|eot_id|> \
    <|begin_of_text|><|start_header_id|>context<|end_header_id|> \
    {{.context}}<|eot_id|> \
    <|start_header_id|>user<|end_header_id|> \
    {{.collection_query}} <|eot_id|> \
    <|start_header_id|>assistant<|end_header_id|>"
BODY='{ "properties": { 
    "input": "'${QUERY}'", 
    "collectionId": "'${COLLECTION_ID}'",
    "collectionQuery": "'${USER_QUERY}'",
    "options": { 
        "max_length": "500", 
        "temperature": "0.01"
    } 
}}'

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     https://inference.de-txl.ionos.com/models/${MODEL_ID}/predictions

This query conducts all steps necessary to answer a user query using Retrieval Augmented Generation:

The user query (saved at collectionQuery) is sent to the collection (specified at collectionId).
The results of this query are saved in a variable .context, while the user query is saved in a variable .collection_query. You can use both variables in your prompt.
The example prompt uses the variables .context and .collection_query to answer the customer query.

Note:

The best prompt strongly depends on the Large Language Model used. Adapt your prompt to improve results.

Summary

In this tutorial, you learned how to use the IONOS AI Model Hub API to implement Retrieval Augmented Generation use cases.

Namely, you learned how to: Derive answers to user queries using the content of your document collection and one of the IONOS foundation models.

Tool Calling

The IONOS AI Model Hub supports tool calling, a feature of our OpenAI-compatible text generation API. Tool calling allows Large Language Models (LLMs) to trigger external functions and APIs during conversation, making the models interactive and dynamic. It significantly extends the LLM’s capabilities beyond pre-trained data or vector database retrieval, enabling real-time actions such as retrieving live weather data or interacting with your business systems.

Note: In modern AI APIs, the term "tool calling" has replaced "function calling." This tutorial uses the updated terminology in accordance with current standards.

Text generation models supporting tool calling

Only the following LLMs offer tool calling:

Model Provider

Model Name

Purpose

Llama 3.3 Instruct (70B)

Best for conversational tasks and natural language processing. Outperforms Llama 3.1 405B at similar quality levels.

Llama 3.1 Instruct (8B and 405B)

Ideal for chatbots, assistants, and dialogue-driven applications.

Mistral Instruct v0.3 (7B)

Strong in European languages; supports longer contexts; great for assistant-style use cases.

Unsupported Models: Teuken and Mixtral 8x7B do not support tool calling.

Overview

In this tutorial, you will learn how to integrate tool calling with a LLM through the OpenAI-compatible API to generate a mock weather forecast.

This tutorial is intended for developers with basic knowledge of:

REST APIs
A programming language capable of making HTTP requests (Python and Bash examples included)

By the end, you will be able to:

Define tool definitions that describe available external tools
Trigger tool calls based on user queries
Parse tool call responses to deliver final answers

Get started with tool calling

First, set up your environment and authenticate using the IONOS OpenAI-compatible API endpoint.

Download the respective code files to easily access tool calling-specific scripts and examples and generate the intended output:

Download the Python Notebook to explore tool calling with ready-to-use examples.

Download the standalone Python script for a quick implementation.

Download the Bash script for a command-line implementation.

Step 1: Retrieve available models

To begin, retrieve a list of available models that support tool calling. This helps you confirm which models we offer for your use case.

import requests

IONOS_API_TOKEN = "[YOUR API TOKEN HERE]"

endpoint = "https://openai.inference.de-txl.ionos.com/v1/models"

header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}
requests.get(endpoint, headers=header).json()
print(response.json())

#!/bin/bash

IONOS_API_TOKEN=[YOUR API TOKEN HERE]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     --get https://openai.inference.de-txl.ionos.com/v1/models

The output will be a JSON document listing each model by name. You will reference one of these model names in later steps to perform text generation and tool calling operations.

Step 2: Define your functions

Tool calling requires you to define external functions that the model can invoke. These functions might fetch external data, trigger workflows, or perform custom computations.

In this example, we define a mock get_weather function that simulates retrieving current weather data.

# Function to get current weather (mock implementation)
def get_weather(city: str, unit: str="celsius"):
    """Get the current weather in a given location"""
    # In a real implementation, this would call a weather API
    # This is a mock implementation
    if city.lower() == "berlin":
        temperature = 22 if unit == "celsius" else 72
        weather_data = {
            "city": city,
            "temperature": temperature,
            "unit": unit,
            "forecast": ["sunny", "windy"],
            "humidity": 70
        }
        return weather_data
    return {"error": "Location not supported"}

# Function to get current weather (mock implementation)
get_weather() {
    local city=$1
    local unit=$2
    
    # Convert location to lowercase for case-insensitive matching
    city_lower=$(echo "$city" | tr '[:upper:]' '[:lower:]')
    
    # Mock data for a few cities
    if [ "$city_lower" = "berlin" ]; then
        if [ "$unit" = "celsius" ]; then
            temperature=22
        else
            temperature=72
        fi
        echo '{"city": $city, "temperature": $temperature, "unit": $unit, "forecast": ["sunny", "windy"], "humidity": 70}'
    else
        echo {"error": "Location not supported"}
    fi
}

These functions form the core logic your AI model will invoke when processing relevant queries.

Step 3: Derive tool definition

Once you've created your function, define a tool definition that describes it in a format the model can understand. This includes the tool name, description, expected parameters, and parameter types.

# Define the tool schema
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather in a given city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The city for which the weather should be returned"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature to use. Is inferred from the city if possible."
                    }
                },
                "required": ["city", "unit"]
            }
        }
    }
]

# Define the tool schema as a JSON string
TOOLS='[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather in a given city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city for which the weather should be returned"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "The unit of temperature to use. Is inferred from the city if possible."
          }
        },
        "required": ["city", "unit"]
      }
    }
  }
]'

Each tool definition must use clear, human-readable names and descriptions. It helps the model determine the most appropriate tool to call and which parameters to request or infer.

In the above example, the model may infer that a query about "Berlin" defaults to Celsius and "New York" to Fahrenheit. If it cannot infer the unit, it may ask the user for clarification.

To use multiple tools, simply add more definitions to the tools list.

Step 4: Enrich user query with available tool definitions

Now, send a user query with your defined tools using the OpenAI-compatible API.

# Python example for tool calling
import requests
import json
from openai import OpenAI

IONOS_API_TOKEN = "[YOUR API TOKEN HERE]"
MODEL_NAME = "[MODEL NAME HERE]"
IONOS_API_URL = 'https://openai.inference.de-txl.ionos.com/v1'

# Initialize the OpenAI client with IONOS API URL
client = OpenAI(base_url=IONOS_API_URL, api_key=IONOS_API_TOKEN)

user_query = "What's the weather like in Berlin?"

body = {
    "model": MODEL_NAME,
    "messages": [
        {"role": "user", "content": user_query}
    ],
    "tools": tools,
    "tool_choice": "auto"  # Let the model decide when to call tools
}

response = client.chat.completions.create(**body)
print(json.dumps(response, default=lambda o: o.__dict__, indent=2))

#!/bin/bash
# Configuration
IONOS_API_TOKEN="[YOUR API TOKEN HERE]"
MODEL_NAME="[MODEL NAME HERE]"
IONOS_API_URL="https://openai.inference.de-txl.ionos.com/v1"

USER_QUERY="What's the weather like in Berlin?"

# Create messages array for the API call
MESSAGES='[
    {"role": "user", "content": "'"$USER_QUERY"'"}
]'

# Create the full request body
REQUEST_BODY="{
    \"model\": \"$MODEL_NAME\",
    \"messages\": $MESSAGES,
    \"tools\": $TOOLS,
    \"tool_choice\": \"auto\"
}"

# Make the API call to IONOS API
RESPONSE=$(curl -s -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$REQUEST_BODY" \
     $IONOS_API_URL/chat/completions)

echo -e "$RESPONSE"

The model will decide whether to call the tool based on the user query. For example, if the user asks about Berlin’s weather, the model might infer the unit as Celsius without prompting it explicitly.

Step 5: Process tool call response and execute tool

Once the LLM responds with a tool call, your application must handle the tool call by executing the corresponding function and returning the result to the user.

# Parse tool call and arguments
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    function_name = tool_call.function.name
    function_args = json.loads(tool_call.function.arguments)
    
    # Call the function
    if function_name == "get_weather":
        tool_response = get_weather(
            city=function_args.get("city"),
            unit=function_args.get("unit")
        )
    print(tool_response)
else:
    print("The model provided a direct response (no tool call):")
    print(response.choices[0].message.content)

if echo "$RESPONSE" | jq -e '.choices[0].message.tool_calls' &> /dev/null; then
    TOOL_CALL_ID=$(echo "$RESPONSE" | jq -r '.choices[0].message.tool_calls[0].id')
    FUNCTION_NAME=$(echo "$RESPONSE" | jq -r '.choices[0].message.tool_calls[0].function.name')
    FUNCTION_ARGS=$(echo "$RESPONSE" | jq -r '.choices[0].message.tool_calls[0].function.arguments')
    
    # Extract location and unit from arguments
    LOCATION=$(echo "$FUNCTION_ARGS" | jq -r '.location')
    UNIT=$(echo "$FUNCTION_ARGS" | jq -r '.unit // "celsius"')
    
    # Get weather data
    WEATHER_DATA=$(get_weather "$LOCATION" "$UNIT")
    
    echo -e "Relevant answer: $WEATHER_DATA"
else
    # The model didn't call a tool, just return its response
    DIRECT_RESPONSE=$(echo "$RESPONSE" | jq -r '.choices[0].message.content')
    echo -e "The model provided a direct response (no tool call):"
    echo -e "Relevant answer: $DIRECT_RESPONSE"
fi

Tool call responses follow a predictable structure, making it easy to extract arguments and determine the function to execute. However, response behavior can vary based on the model, prompt structure, and tool definition quality.

You can also guide model behavior more precisely by:

Using detailed system prompts
Providing complete and clear tool descriptions
Adjusting the temperature or other generation parameters

In real-world use cases, always validate parameters and add safety checks before executing external actions based on user prompts.

Summary

In this tutorial, you learned how to:

Create a mock weather function simulating a real API call
Define a tool definition based on the function
Prompt the LLM with a user query and tool definition
Parse the model’s response to extract tool call details
Execute the tool and return structured output

Tool calling enables your application to integrate LLMs with external data sources, APIs, or internal logic. This makes the LLM more powerful, responsive, and capable of handling real-time, or dynamic user scenarios.

Document Collections

The IONOS AI Model Hub API allows you to access vector databases to persist your document collections and find semantically similar documents.

The vector database is used to persist documents in document collections. Each document is any form of pure text. In the document collection not only the input text is persisted, but also a transformation of the input text into an embedding. Each embedding is a vector of numbers. Input texts which are semantically similar have similar embeddings. A similarity search on a document collection finds the most similar embeddings for a given input text. These embeddings and the corresponding input text are returned to the user.

Overview

This tutorial is intended for developers. It assumes you have basic knowledge of:

REST APIs and how to call them
A programming language to handle REST API endpoints (for illustration purposes, the tutorials uses Python and Bash scripting)

By the end of this tutorial, you'll be able to:

Create, delete and query a document collection in the IONOS vector database
Save, delete and modify documents in the document collection and
Answer customer queries using the document collection.

Background

The IONOS AI Model Hub API offers a vector database that you can use to persist text in document collections without having to manage corresponding hardware yourself.
Our AI Model Hub API provides all required functionality without your data being transfered out of Germany.

Before you begin

To get started, open your IDE to enter Python code.

Next generate a header document to authenticate yourself against the endpoints of our REST API:

# Python example to specify header

IONOS_API_TOKEN = [YOUR API TOKEN HERE]
header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}

After this step, you have one variable header you can use to access our vector database.

To get started, open a terminal and ensure that curl and jq is installed. While curl is essential for communicating with our API service, we use jq throughout our examples the improve the readability of our API results.

Download the respective code files to easily access document collection-specific scripts and examples and generate the intended output:

Download this Python Notebook file to easily access document collection-specific scripts and examples and generate the intended output.

Download this Python code file to easily access document collection-specific scripts and examples and generate the intended output.

Download this Bash code file to easily access document collection-specific scripts and examples and generate the intended output.

Manage document collections

In this section you learn how to create a document collection. We will use this document collection to fill it with the data from your knowledge base in the next step.

To track, if something is incorrect this section also shows how to:

List existing document collections
Remove document collections
Get meta data of a document collection

Create document collections

To create a document collection, you must specify the collection name and a description and invoke the endpoint to generate document collections:

# Python example to specify header
import requests

COLLECTION_NAME = [ YOUR COLLECTION NAME HERE ]
COLLECTION_DESCRIPTION = [ YOUR COLLECTION DESCRIPTION HERE ]
CHUNK_OVERLAP = [ NUMBER OF OVERLAPPING TOKENS ]
CHUNK_SIZE = [ MAXIMUM NUMBER OF TOKENS PER DOCUMENT ]
EMBEDDING_MODEL = [ YOUR EMBEDDING MODEL HERE ]
DATA_BACKEND = [ THE BACKEND TO USE ]
endpoint = "https://inference.de-txl.ionos.com/collections"
body = {
    "properties": {
        "name": COLLECTION_NAME,
        "description": COLLECTION_DESCRIPTION,
        "chunking": {
            "enabled": True,
            "strategy": {
                "config": {
                    "chunk_overlap": CHUNK_OVERLAP, 
                    "chunk_size": CHUNK_SIZE
                }
            }
        },
        "embedding": {
            "model": EMBEDDING_MODEL
        },
        "engine": {
            "db_type": DATA_BACKEND
        }
    }
}
requests.post(endpoint, json=body, headers=header)

#!/bin/bash

COLLECTION_NAME=[ YOUR COLLECTION NAME HERE ]
COLLECTION_DESCRIPTION=[ YOUR COLLECTION DESCRIPTION HERE ]
CHUNK_OVERLAP=[ NUMBER OF OVERLAPPING TOKENS ]
CHUNK_SIZE=[ MAXIMUM NUMBER OF TOKENS PER DOCUMENT ]
EMBEDDING_MODEL=[ YOUR EMBEDDING MODEL HERE ]
DATA_BACKEND=[ THE BACKEND TO USE ]
BODY='{ 
    "properties": { 
        "name": "'${COLLECTION_NAME}'", 
        "description": "'${COLLECTION_DESCRIPTION}'",
        "chunking": {
            "enabled": True,
            "strategy": {
                "config": {
                    "chunk_overlap": "'${CHUNK_OVERLAP}'", 
                    "chunk_size": "'${CHUNK_SIZE}'"
                }
            }
        },
        "embedding": {
            "model": "'${EMBEDDING_MODEL}'"
        },
        "engine": {
            "db_type": "'${DATA_BACKEND}'"
        }
    } 
}'

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
        -H "Content-Type: application/json" \
        -d "$BODY" \
        https://inference.de-txl.ionos.com/collections

You can specify the following parameters when you create your document collection:

Chunking

The AI Model Hub supports fixed-length chunking. If you apply chunking, long documents are split before being uploaded into the document collection. Is is beneficial in the following cases:

If your document exceeds the length of the text, your embedding model can cope with.
If your document spans over different semantic topics.

You can control chunking using:

CHUNK_OVERLAP: The number of overlaping tokens in two subsequent chunks.
CHUNK_SIZE: The maximum number of tokens per chunk.

Embedding Model

Database Engine

The AI Model Hub supports different databases in the backend to persist your data. Upon creation of your collection, you can choose which of them to use by setting DATA_BACKEND to:

pgvector: PGVector uses a PostgreSQL database as the backend to persist the document collection. We offer the corresponding PostgreSQL as a Database as a Service (DBaaS) offering. This allows you to scale as your demands grow by switching from the managed PostgreSQL to your own DBaaS instance.
chromadb: ChromaDB is a state-of-the-art database optimized for persisting document collections. It is strongly optimized but does not support relational database features like PostgreSQL.

If you remove the chunking, embedding, and engine sections from the body of your request, we will create a document collection with default parameters. Our approach does not apply chunking; sentence transformers will be used as the embedding models, and the data will be stored in our managed ChromaDB.

If the creation of the document collection was successful, the status code of the request is 201 and it returns a JSON document with all relevant information about the document collection.

To modify the document collection you need its identifier. You can extract it from the returned JSON document in the variable id.

List Existing Document Collections

To ensure that the previous step went as expected, you can list the existing document collections.

To retrieve a list of all document collections saved by you:

# Python example to list existing document collections
import requests

endpoint = "https://inference.de-txl.ionos.com/collections"
requests.get(endpoint, headers=header).json()

#!/bin/bash

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
        -H "Content-Type: application/json" \
        https://inference.de-txl.ionos.com/collections

This query returns a JSON document consisting of your document collections and corresponding meta information

The result consists of 8 attributes per collection of which 3 are relevant for you:

id: The identifier of the document collection
properties.description: The textual description of the document collection
properties.documentsCount: The number of documents persisted in the document collection

If you have not created a collection yet, the field items is an empty list.

Remove a Document Collection

If the list of document collections consists of document collections you do not need anymore, you can remove a document collection by invoking:

# Python example to delete collections
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
requests.delete(endpoint, headers=header)

#!/bin/bash
COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -X DELETE \
     -i https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}

This query returns a status code which indicates whether the deletion was successful:

204: Status code for successfull deletion
404: Status code given the collection did not exist

Get Meta Data for a Document Collection

If you are interested in the meta data of a collection, you can extract it by invoking:

# Python example to extract meta information
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
result = requests.get(endpoint, headers=header)
result.status_code

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}

This query returns a status code which indicates whether the collection exists:

200: Status code if the collection exists
404: Status code given the collection does not exist

The body of the request consists of all meta data of the document collection.

Manage Documents in Document Collection

In this section, you learn how to add documents to the newly created document collection. To validate your insertion, this section also shows how to

List the documents in the document collection,
Get meta data for a document,
Update an existing document and
Prune a document collection.

Add Documents to Document Collection

To add an entry to the document collection, you must at least specify the content, the name of the content, and the contentType:

# Python example to add documents to a collection
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
CONTENT = [ YOUR CONTENT HERE ]
NAME = [ YOUR NAME HERE]
content_base64 = base64.b64encode(CONTENT.encode('utf-8')).decode("utf-8")
body = { 
    "items": [{ 
        "properties": { 
            "name": NAME, 
            "contentType": "text/plain", 
            "content": content_base64
        }
    }]
}
endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}/documents"
requests.put(endpoint, json=body, headers=header)

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
CONTENT=[ YOUR CONTENT HERE ]
NAME=[ YOUR NAME HERE]

CONTENT_BASE64=$(echo -n ${CONTENT} | base64)
BODY='{
    "items": [{
        "properties": {
            "name": "'${NAME}'", 
            "contentType": "text/plain", 
            "content": "'${CONTENT_BASE64}'"
        }
    }]
}'

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     -X PUT \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents

Note:

You must encode your content using base64 before adding it to the document collection. This is done here in line 7 of the source code. We imply a document limit of 65535 characters for each document you upload. Ensure that your documents do not exceed this limit.

This request returns a status code 200 if adding the document to the document collection was successful.

List Existing Documents in Document Collection

To ensure that the previous step went as expected, you can list the existing documents of your document collection.

To retrieve a list of all documents in the document collection saved by you:

# Python example to list all existing documents in a document collections
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]

endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents"

requests.get(endpoint, headers=header).json()

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents

This query returns a JSON document consisting of your documents in the document collection and corresponding meta information

The result has a field items with all documents in the collection. This field consists of 10 attributes per entry of which 5 are relevant for you:

id: The identifier of the document
properties.content: The base64 encoded content of the document
properties.name: The name of the document
properties.description: The description of the document
properties.labels.number_of_tokens: The number of tokens in the document

If you have not created the collection yet, the request will return a status code 404. It will return a JSON document with the field items set to an empty list if no documents were added yet.

Get Meta Data for a Document

If you are interested in the metadata of a document, you can extract it by invoking:

# Python example to access meta data from a document
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
DOCUMENT_ID = [ YOUR DOCUMENT ID HERE ]

endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents/{DOCUMENT_ID}"

requests.get(endpoint, headers=header).json()

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
DOCUMENT_ID=[ YOUR DOCUMENT ID HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents/${DOCUMENT_ID}

This query returns a status code which indicates whether the document exists:

200: Status code if the document exists
404: Status code given the document does not exist

The body of the request consists of all meta data of the document.

Update a Document

If you want to update a document, invoke:

# Python example to update a document
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
DOCUMENT_ID = [ YOUR DOCUMENT ID HERE ]
CONTENT = [ YOUR CONTENT HERE ]
NAME = [ YOUR NAME HERE ]

endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents/{DOCUMENT_ID}"
content_base64 = base64.b64encode(CONTENT.encode('utf-8')).decode("utf-8")
body = { 
    "properties": { 
        "id": DOCUMENT_ID, 
        "name": NAME, 
        "contentType": 
        "text/plain", 
        "content": content_base64
    }
}

requests.put(endpoint, json=body, headers=header)

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
DOCUMENT_ID=[ YOUR DOCUMENT ID HERE ]
CONTENT=[ YOUR CONTENT HERE ]
NAME=[ YOUR NAME HERE ]
CONTENT_BASE64=$(echo -n ${CONTENT} | base64)
BODY='{
    "properties": {
        "name": "'${NAME}'", 
        "id": "'${DOCUMENT_ID}'", 
        "contentType": "text/plain", 
        "content": "'${CONTENT_BASE64}'"
    }
}'
curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     -X PUT \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents/${DOCUMENT_ID}

This will replace the existing entry in the document collection with the given id by the payload of this request.

Prune a Document Collection

If you want to remove all documents from a document collection invoke:

# Python example to prune a document collection
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents"
requests.delete(endpoint, headers=header)

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -X DELETE \
     -i https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents

This query returns the status code 204 if pruning the document collection was successful.

Query Documents in the Document Collection

Finally, this section shows how to use the document collection and the contained documents to answer a user query.

To retrieve the documents relevant for answering the user query, invoke the query endpoint as follows:

# Python example to retrieve documents for answering a user query
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
USER_QUERY = [ USER QUERY HERE ]
NUM_OF_DOCUMENTS = [ NUMBER OF DOCUMENTS TO CONSIDER HERE ]

endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}/query"
body = {"query": USER_QUERY, "limit": NUM_OF_DOCUMENTS }

relevant_documents = requests.post(endpoint, json=body, headers=header)

[
    base64.b64decode(entry['document']['properties']['content']).decode()
    for entry in relevant_documents.json()['properties']['matches']
]

#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
USER_QUERY=[ USER QUERY HERE ]
NUM_OF_DOCUMENTS=[ NUMBER OF DOCUMENTS TO CONSIDER HERE ]
BODY='{"query": "'${USER_QUERY}'", "limit": "'${NUM_OF_DOCUMENTS}'" }'

RESULT=$(curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     -X POST \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/query)

echo "$RESULT" | \
jq -r '.["properties"]["matches"][].["document"]["properties"]["content"]' | \
base64 --decode

This will return a list of the NUM_OF_DOCUMENTS most relevant documents in your document collection for answering the user query.

Summary

In this tutorial you learned how to use the IONOS AI Model Hub API to conduct semantic similarity searches using our vector database.

Namely, you learned how to:

Create a necessary document collection in the vector database and modify it
Insert your documents into the document collection and modify the documents
Conduct semantic similarity searches using your document collection.