About This Task

A component is a Python code snippet that follows our template and performs a specific task on your data. When you create and upload a custom component to deepset Cloud, it becomes accessible to your entire organization. Any member can then use the component in their pipelines.

📘

Custom components are currently available only in the YAML editor. Support for Studio is coming soon.

Custom components are based on Haystack components. Haystack is deepset's open source AI framework, which also powers deepset Cloud. To learn more, visit the Haystack website.

We provide a template for creating your custom components, available as a GitHub repository. This template serves as a custom components library for your organization. Components created in the ./dc-custom-component-template/src/dc_custom_component/example_components/ folder and imported into deepset Cloud are the components you can use in your pipelines.

For example, if someone in your organization creates a component called WelcomeTextGenerator and uploads it to deepset Cloud, everyone in the organization can use it. However, if later someone adds two new components, GoodbyeTextGenerator and CharacterSplitter, and deletes WelcomeTextGenerator, only the new components will be available to use in your pipelines. WelcomeTextGenerator will no longer be accessible.

Only the components present in the most recently uploaded template are available for use.

Currently, you can't delete custom components.

Prerequisites

• Read the following resources before completing this task:
  • Haystack Components
  • Custom Components
  • Pipelines
• You should have a basic understanding of working with GitHub repositories.
• Generate a deepset Cloud API key to upload the created component to your workspace. For instructions, see Generate an API Key.

Create a Component

Prepare the Template

1. Fork the dc-custom-component-template GitHub repository. This will let you version control your changes.
2. Navigate to the directory where you cloned the repository and open the ./dc-custom-component-template/src/dc_custom_component/example_components/ directory. The preprocessors and rankers folders are examples you can modify or remove as needed.
3. Create a new folder or rename one of the example folders to match your custom component's name and open it. There's a .py file inside. This is where you'll write your component code. You can rename this file as well.
   Example:
   To create a custom component called WelcomeTextGenerator:
   1. Rename ./dc-custom-component-template/src/dc_custom_component/example_components/preprocessors to ./dc-custom-component-template/src/dc_custom_component/components/generators.
   2. Open the generators folder and rename the example file character_splitter.py to welcome_text_generator.py.
   3. Delete the rankers folder if it's not needed. If you're creating multiple components, use the folder structure to keep them organized.
      Note: You can create all your components in one .py file or you can have a separate folder with a .py file in it for each custom component. That's up to you.

Set Up a Virtual Environment

Creating a virtual environment isolates your project's dependencies from other Python projects and your system Python installation.

The template uses Hatch, a Python project manager, to set up virtual environments. For details, see the Hatch website.

1. Install Hatch by running: pip install hatch. This installs all the necessary packages, including pytest.
2. Create a virtual environment by running: hatch shell.

Implement the Component

1. Write the component code in the .py file. Use the recipe below as a starting point:

2. If your component has dependencies, add them in the ./dc-custom-component-template/pyproject.toml file in the dependencies section:

dependencies = [
  "haystack-ai>=2.0.0"
]

Note: Do not modify versions of dependencies already listed in this file.

3. From the project root directory, run thehatch run code-quality:all command to format your code.
4. Update the component version in the ./dc-custom-component-template/src/dc_custom_component/__about__.py file. You can specify version numbers in any way you like, but we suggest that you adopt the major.minor.micro format, for example, 1.1.0. Have a look at Hatch versioning for guidelines.
   The version number applies to all components. Even if you have multiple components, you only need to specify one version number.

Components Connecting to Third-Party Providers

If your component connects to a third-party provider that requires authentication, we recommend adding the API key as a secret to keep it hidden from the code. You can do this using deepset Cloud's Secrets feature.

First, add the secret on the Secrets page:

1. In deepset Cloud, click your initials in the top right corner and choose Secrets>Add New Secret.

   

2. Give your secret the same name as the environment variable where you want to store it.

3. Paste the API key into the Secret field and save it.

Then, add the secret to your componentinit() method:

Add the secret to the component's code by specifying the environment variable name, which must match the secret's name:

@component
class MyComponent
    def __init__(self, api_key: Secret = Secret.from_env_var("<ENV_VAR_NAME")):
    # the name of the environment variable must be the same as the name of the secret
        ...

If you have multiple secrets for one provider, you can easily switch between them in your pipeline YAML by updating the secret's name:

llm:
  type: dc_custom_component.components.my_components.component1.MyComponent # the path to your component
  init_parameters:
     api_key: {"type": "env_var", "env_vars": ["ENV_VAR_NAME"], "strict": False} # uses the `ENV_VAR_NAME` secret
     # to use another secret, update its name here
    

Test Your Component

When you upload your component to deepset Cloud, we verify the structure and version of the uploaded .zip file. We recommend that you test your component before uploading.

1. Add unit and integration tests in the ./dc-custom-component-template/tests folder to ensure everything works fine.
2. Run your tests using: hatch run tests. If the tests pass, your component is ready.

Import the Component to deepset Cloud

There are two ways to import your component:

• Through REST API (supported for all systems)
• Using commands (currently supported for Linux and macOS, support for Windows is coming soon)

Import with REST API:

1. Zip the repository from the template folder. The zipped repository should contain the same files in the same hierarchy as the dc-custom-component-template repository.

zip -r ../custom_component.zip ./*

Compress-Archive -Path .\* -DestinationPath ..\custom_component.zip -Force

This command creates a zip file called custom_component.zip in the parent directory.

2. Upload the .zip file to deepset Cloud using the Import Custom Components [private] endpoint. Here's a sample code you can use as a starting point for your request:

curl 
--request POST \
--url https://api.cloud.deepset.ai/api/v2/custom_components \
--header 'accept: application/json' \
--header 'Authorization: Bearer api_XXX' \
--form 'file=@"/path/to/custom/component/custom_component.zip";type=application/zip'

Import with Commands

This method works only on Linux and macOS systems.

1. Set your deepset Cloud API key:
   Shell

   export API_KEY=<YOUR_API_KEY>
   

2. From within this project, run the following command to upload your custom component:
   Shell

   hatch run dc:build-and-push
   

This command creates a .zip file called custom_component.zip in the dist directory and uploads it to deepset Cloud.

Verify the Import

Check the component status using the Get Custom Components endpoint. If the status is finished, you can use the component in your pipelines. Here is a sample code you can use:

curl --request GET \
     --url 'https://api.cloud.deepset.ai/api/v2/custom_components?limit=10&page_number=1&field=created_at&order=DESC' \
     --header 'accept: application/json'
     --header 'Authorization: Bearer api_XXX'

Add the Component to Your Pipeline

1. Open the pipeline where you want to add the component in Code editor:
   • If you're in Studio, switch to the code view.
   • If you're on the Pipelines page, click More actions next to the pipeline and choose Edit.
2. In the components section of the YAML, add your custom component name and type like this:

components:
  custom_component: # this is a custom name for your component, it's up to you
    init_parameters: #here you can set init parameters for your component, if you added any. Otherwise delete init_parameters.
      param: value
    type: dc_custom_component.components.your_component_folder.your_component_file.YourComponentName # this is the path to your custom component; it reflects the template structure starting from the "src" directory and separated with periods. If you changed the path, the type must reflect this.
    
connections:
- receiver: custom_component.output # Define how to connect to your component to other components, make sure the input and output types match.
  sender: another_component.input
    
inputs:  # Define the inputs for your pipeline
  query:  # These components will receive the query as input
  - "custom_component.input"
    
outputs:
  answers: "custom_component.output"
    
max_loops_allowed: 100
metadata: {}

# This is an example with two custom components, WelcomeTextGenerator that generates a welcome message to a user
# and Splitter that splits text by whitespace:

components:
  splitter:
    init_parameters: {}
    type: dc_custom_component.components.splitters.whitespace_splitter.Splitter
    # This component's path is "./dc-custom-component-template/src/dc_custom_component/components/splitters/whitespace_splitter.py"
  welcome_text_generator:
    init_parameters: {}
    type: dc_custom_component.components.generators.welcome_text_generator.WelcomeTextGenerator
    # This component's path is: "./dc-custom-component-template/src/dc_custom_component/components/generators/welcome_text_generator.py"
connections:
- receiver: splitter.text
  sender: welcome_text_generator.welcome_text
    
inputs:  # Define the inputs for your pipeline
  query:  # These components will receive the query as input
  - "welcome_text_generator.name"
    
outputs:
  answers: "splitter.answers"
    
max_loops_allowed: 100
metadata: {}

Update a Component

You update custom components by uploading their new version to deepset Cloud:

1. Pull the latest version of the dc-custom-component-template repository.
2. Update the component code in the ./dc-custom-component-template/src/dc_custom_component/components/<your_components_folder>/<custom_component>.py file.
3. Update the component version in the ./dc-custom-component-template/src/dc_custom_component/__about__.py file.

📘

How do I check the current version?

If you don't know what version is currently uploaded to deepset Cloud, use the Get Custom Components endpoint. Version is listed in the version parameter of a successful response.

4. If the component has any dependencies, add them in the dependencies section of the ./dc-custom-component-template/pyproject.toml file. Do not modify versions of dependencies already listed in this file.
5. Upload the updated component with one of these methods:
   1. With REST API: Zip the repository and upload it using the Import Custom Components endpoint.
   2. With a command (currently only supported for Linux and macOS):
      1. Set your deepset Cloud API key: export API_KEY=<YOUR_API_KEY>
      2. hatch run dc:build-and-push. This creates a custom_component.zip file and uploads it to deepset Cloud.
6. Check the upload status using the Get Custom Components endpoint.

All new pipelines automatically use the latest version of your custom components. However, running pipelines continue to use the version that was current when they were deployed. To update the component version in running pipelines, undeploy and redeploy them.

Compare Different Versions

To evaluate which version of your component performs better in a pipeline, you can upload two versions of the component simultaneously, each with a unique name.

1. Pull the latest version of the dc-custom-component-template repository.
2. Add two versions of the component to the ./dc-custom-component-template/src/dc_custom_component/components/<your_component_folder>/<your_component_name>.py file, treating them as separate components and giving each version a distinct name.
3. Update the component version in the ./dc-custom-component-template/src/dc_custom_component/__about__.py file.
4. Zip the repository and upload it with one of these methods:
   1. With REST API: Zip the repository and upload it using the Import Custom Components endpoint.
   2. With a command (currently only supported for Linux and macOS):
      1. Set your deepset Cloud API key: export API_KEY=<YOUR_API_KEY>
      2. hatch run dc:build-and-push. This creates a custom_component.zip file and uploads it to deepset Cloud.
5. Check the upload status using the Get Custom Component endpoint.

Now, you can create two pipelines—one using the first version and another using the second—to compare their performance.

Troubleshooting Custom Components

If you're having issues with your component, check the pipeline logs for details. To access pipeline logs:

1. Go to Pipelines and click the pipeline you want to troubleshoot.

2. Click Logs on the Pipeline Details page to view all information messages, warnings, and errors your pipeline produced.