---
name: inference-taxonomy-prep
title: Preparing taxonomies for Red Hat AI Inference
description: Follow these steps to create your own taxonomy. For more information on taxonomies and the data they include, see How taxonomies are structured.
last-updated: 2026-07-09
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/inference?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Preparing taxonomies for Red Hat AI Inference
{: #taxonomy-prep}

Follow these steps to create your own taxonomy. For more information on taxonomies and the data they include, see [How taxonomies are structured](https://cloud.ibm.com/docs/inference?topic=inference-taxonomy-overview&format=markdown).
{: shortdesc}

Red Hat AI Inference model alignment, synthetic data generation, and taxonomy management features are deprecated and will be removed on 25 September 2026. To continue model customization and alignment workflows, migrate to Red Hat® OpenShift® AI On OpenShift. [Learn more about Red Hat® OpenShift® AI](https://cloud.ibm.com/docs/openshift?topic=openshift-ai-addon-about&format=markdown){: external}.
{: deprecated}

## Create or clone your taxonomy
{: #taxonomy-create}
{: step}

You can [fork and clone the Red Hat AI Inference taxonomy](https://github.com/IBM-Cloud/redhat-ai-instructlab-taxonomy){: external}, or you can create a new taxonomy from scratch in your own GitHub repo. For examples and diagrams showing how you can structure your own taxonomy, see [Upstream taxonomy tree layout](https://docs.instructlab.ai/taxonomy/#upstream-taxonomy-tree-layout){: external} in the Red Hat AI Inference docs.

## Gather your knowledge documents
{: #taxonomy-gather}
{: step}

Format your knowledge documents as a Markdown `.md` file and store them in a directory that is separate from the taxonomy. For an example of a knowledge document, see the [documentation](https://docs.instructlab.ai/taxonomy/knowledge/file_structure/#example-of-a-knowledge-document-file){: external}.

Knowledge documents are only required when adding knowledge to your taxonomy, not skills. For more information on the difference between knowledge and skills see [Taxonomy data](https://cloud.ibm.com/docs/inference?topic=inference-taxonomy-overview&format=markdown#taxonomy-data).

The total size of your knowledge documents should not exceed 10MB cumulative.
{: note}

## Create `qna.yaml` files for knowledge and skills
{: #taxonomy-qna}

1. Create a `qna.yaml` file that includes questions and answers related to the knowledge or skill you want to add. The file must follow standard YAML formatting. The file must also have at least 5 `seed_examples` sections and, within each of those, exactly 3 question and answer pairs. For a complete list of fields required for the `qna.yaml` file, see the docs for adding [knowledge](https://docs.instructlab.ai/taxonomy/knowledge/file_structure/#the-knowledge-files){: external} or [skills](https://docs.instructlab.ai/taxonomy/skills/file_structure/#the-structure-of-the-qnayaml-file){: external}.

2. If you are creating a `qna.yaml` file for a knowledge addition, you must reference the relevant knowledge document, the commit hash for the document, and the directory where it is stored in the `document` section of the file.

    Example knowledge document and directory reference.

    ```yaml
    document:
        repo: https://github.com/user/my_knowledge
        commit: 0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9u
        patterns:
          - knowledge_document.md
    ```
    {: screen}

3. Add the file to the correct node in your taxonomy.

In addition to creating a new `qna.yaml` file, you can also add question and answer pairs to existing files.
{: tip}

## Upload your taxonomy to your Object Storage bucket
{: #taxonomy-upload}
{: step}

Use the [UI](https://cloud.ibm.com/docs/inference?topic=inference-getting-started&interface=ui&format=markdown#taxonomy-add-ui) or the [CLI](https://cloud.ibm.com/docs/inference?topic=inference-getting-started&interface=cli&format=markdown#taxonomy-add-ui) to upload and store your taxonomy to your Object Storage bucket.

## What's next?
{: #taxonomy-next}

Learn how to [generate data from your taxonomy](https://cloud.ibm.com/docs/inference?topic=inference-data-generate&interface=ui&format=markdown).