CLI

The CLI tool is your way of interacting with the OneContext platform from almost anywhere.

For more info on the CLI tool, you can read the public repo here.

Install the CLI Tool

npm install -g @onecontext/cli

Once you've installed the CLI, it's globally accessible via the onecli command.

If you are having trouble with this / want to play around with the source code, you can clone the repo and access the CLI directly:

git clone https://github.com/onecontext/onecontext-cli
cd onecontext-cli
npm run build

And now you can start the CLI by running (in the root of the repo):

node dist/cli.js

i.e. instead of running onecli and starting the version installed by npm, you can now hit the locally built version in the repo with the above command.

Initial Setup

To start using the OneContext CLI, set your API key and base URL :

onecli config set-api-key
onecli config set-base-url

Then, in a Python file / console:

You can get an API key by signing up here

If you're on the serverless plan, your base URL will simply be https://api.onecontext.ai. If you're on the dedicated plan, this will be the URL of your private instance of OneContext.

Create your first Knowledge Base

A knowledge base is a collection of files. We create our first knowledge base and upload a file:

onecli knowledge-base create --knowledge-base-name=demo_kb

Create a Vector Index

We want to chunk and embed the files in our knowledgebase, but first we need somewhere to store our vectors. We create a vector index and specify the embedding model that the vector index should expect:

onecli vector-index create --vector-index-name=demo_vi --model-name=BAAI/bge-base-en-v1.5

By specifying the model we create a vector index of appropriate dimensions and also ensure that we never write embeddings from a different model to this index.

Create an Ingestion Pipeline

We are ready to deploy our first ingestion pipeline.

onecli pipeline create --pipeline-name=demo_indexing_pipeline --pipeline-yaml=./index.yaml

Where, the file at ./index.yaml is as below:

steps:
  - step: KnowledgeBaseFiles
    name: input
    step_args:
      # specify the source knowledgebases to watch
      knowledgebase_names: ["demo_kb"]
    inputs: []

  - step: Preprocessor
    name: preprocessor
    step_args: {}
    inputs: [input]

  - step: Chunker
    name: simple_chunker
    step_args:
      chunk_size_words: 320
      chunk_overlap: 30
    inputs: [preprocessor]

  - step: SentenceTransformerEmbedder
    name: sentence-transformers
    step_args:
      model_name: BAAI/bge-base-en-v1.5
    inputs: [ simple_chunker ]

  - step: ChunkWriter
    name: save
    step_args:
      vector_index_name: demo_vi
    inputs: [sentence-transformers]

Let's break down the steps.

The KnowledgeBaseFiles step tells the pipeline to watch the "my_kb" knowledge base. When the pipeline is first deployed all files in the knowledge base will be run through the pipeline. Any subsequent files uploaded to this knowledge base will trigger the pipeline to run.

The Chunker defines how the files will be split into chunks.

The SentenceTransformerEmbedder step specifys the embedding model that will be used to embed the chunks.

Finally, the ChunkWriter step writes the chunks to the vector index we created earlier.

Create a query Pipeline

Having indexed (preprocessed, chunked, and embedded) these files, we now create a pipeline to query the vector index.

onecli pipeline create --pipeline-name=demo_query_pipeline --pipeline-yaml=./query.yaml

Where the file at ./query.yaml is defined as:

steps:
  - step: SentenceTransformerEmbedder
    name: query_embedder
    step_args:
      model_name: BAAI/bge-base-en-v1.5
      include_metadata: [ title, file_name ]
      query: "placeholder"
    inputs: [ ]

  - step: Retriever
    name: retriever
    step_args:
      vector_index_name: demo_vi
      top_k: 100
      metadata_filters: { }
    inputs: ["query_embedder"]

  - step: Reranker
    name: reranker
    step_args:
      query: "placeholder"
      model_name: BAAI/bge-reranker-base
      top_k: 5
      metadata_filters: { }
    inputs: [ retriever ]

Here we've created a simple query pipeline with just two steps.

• The Retriever step embeds the query and performs a similarity search against the index we defined earlier. This step has a high recall and is great to retrieve many candidate vectors.
• The Reranker step uses a cross-encoder model to further narrow down the results only to the most relevant chunks.

Run the query Pipeline

We can run the query pipeline and override any of the default step arguments defined in our pipeline at runtime simply by passing a dictionary of the form:

'{"step_name" : {"step_arg": "step_arg_value"}'.

Note, you need to escape the whole override object with single quotes ', and escape each of the keys with double quotes ". The reason for this is because you are passing a dictionary via the command line.

For example:

onecli pipeline run sync --override-args='{
  "query_embedder": {
    "query": "how many roads must a man walk down?"
  }, 
  "retriever": {
    "top_k": 50
  },
  "reranker": {
    "query": "how many roads must a man walk donw?",
    "top_k": 10
  }
}'

override_args = { "query_embedder": {"query": query}, "retriever": { "top_k": retriever_top_k, }, "reranker": {"top_k": top_k, "query": query}, }

For much more information on the steps you can add to your pipeline, and what functionality you can get out of pipelines, see the pipelines page.