Ask Catalog | Documentation

This document explains how to use the AskCatalog API to conduct a retrieval test for a Catalog. Unlike similar chunk searches that only identify related chunks, this API assesses whether a language model (LLM) can understand the context of these chunks and provide accurate answers. It is a single-turn question-answering API designed primarily for testing Catalogs, ensuring that the LLM can comprehend the context and use retrieved chunks to respond correctly. This can also serve as a demonstration purpose.

It uses a preset pipeline to answer questions based on the chunks retrieved from the Catalog. For more details, please refer to the Q&A VDP Pipeline.

#Ask Catalog via API

The AskCatalog API allows you to pose a question related to a Catalog and receive an answer based on the contents of the Catalog. This is useful for validating whether the LLM can correctly interpret and respond to queries using the available data.

cURL

Python

export INSTILL_API_TOKEN=********
curl -X POST 'https://api.instill.tech/v1alpha/namespaces/NAMESPACE_ID/catalogs/CATALOG_ID/ask' \
--header "Authorization: Bearer $INSTILL_API_TOKEN" \
--header "Content-Type: application/json" \
--header "Instill-Requester-Uid: REQUESTER_UID" \
--data-raw '{
  "question": "What is Instill Core?",
  "topK": 5
}'

Note that the NAMESPACE_ID and CATALOG_ID path parameters must be replaced by the Catalog owner's ID (namespace) and the identifier of the Catalog you are querying. The REQUESTER_UID in the Instill-Requester-Uid header is optional and should be replaced with the UID of the entity on whose behalf the request is being made, typically an organization you belong to. If you are not making the request on behalf of another entity, you can omit this header.

#Body Parameters

question (string, required): The question you want the LLM to answer.
topK (integer, optional): The number of similar chunks to retrieve for context. Default is 5.

#Example Response

A successful response will return the answer to the question, along with a list of similar chunks from the Catalog that the LLM used to generate the answer.

{
  "answer": "Instill Core is a full-stack AI solution designed to accelerate AI development...",
  "similarChunks": [
    {
      "chunkUid": "ba30f524-889c-4dc7-82a2-33a8f7be2d47",
      "similarityScore": 0.95,
      "textContent": "Instill Core is a full-stack AI solution to accelerate AI development...",
      "sourceFile": "core-intro.txt"
    },
    {
      "chunkUid": "757ab6d9-e5b4-482e-8017-5582b578e57a",
      "similarityScore": 0.89,
      "textContent": "Transform unstructured data into a knowledge base with unified format...",
      "sourceFile": "catalog-intro.pdf"
    }
  ]
}

#Output Description

answer (string): The text response generated by the LLM based on the question and the context provided by the retrieved chunks.
similarChunks (array of objects): An array of similar chunks that contributed to the answer.
- chunkUid (string): The unique identifier of the chunk.
- similarityScore (number): The similarity score between the question and the chunk content. Scores range from 0 to 1, with higher scores indicating greater relevance.
- textContent (string): The content of the similar chunk.
- sourceFile (string): The file from which the chunk was extracted.

Notes:

This API is crucial for testing and demonstrating the Catalog's ability to understand and accurately respond to questions, showcasing the practical application of AI in managing and retrieving unstructured data.
Ensure that the Authorization header contains a valid API token with the Bearer prefix.
The Instill-Requester-Uid header is optional and should be included if the authenticated user is making the request on behalf of another entity, such as an organization they belong to.
Adjust the topK parameter based on how many context chunks you want to retrieve for answering the question. If omitted, it defaults to 5.