Vantage ConsoleCommunityCustomer Support

Management API

Account, collection, API keys and data upload functionalities of the Vantage API

Suggest Edits

The Management API is a collection of functionalities related to working with accounts, collections, Vantage and Model API keys, and data upload. Below, you can find different options and approaches for using these functionalities.

📘

Vantage Client

In the following code blocks, we're initializing the Vantage client using Vantage API key. For more information on client configuration, check out the API Usage page.

Management API

Account

Here you can find Account management functionalities provided by the Vantage API.

If you prefer a visual guide, check out the Console UI walkthrough example: See And Manage Account Details

Get Account

The following example returns details about the account ACCOUNT_ID.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

account = vantage_instance_stage.get_account()
print(account)

./cli.py get-account

Update Account

The following example updates the account ACCOUNT_ID.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

account = vantage_instance_stage.update_account(
	account_name="New Account Name",
)
print(account)

./cli.py update-account "New Account Name"

Collections

Here you can find Collection management functionalities provided by the Vantage API.

If you prefer a visual guide, check out the Console UI walkthrough examples: Create Collections, Upload Data To Collection

List Collections

The following example returns all collections created by account ACCOUNT_ID.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

collections = vantage_instance_stage.list_collections()
print(collections)

./cli.py list-collections

Get Collection

The following example returns details about the collection example-collection.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

collection = vantage_instance.get_collection(
  collection_id="example-collection"
)

print(collection)

./cli.py get-collection example-collection

Create Collection

The following examples will demonstrate how you can create collection objects.

There are different types of collections, depending on whether you want Vantage to manage and create embeddings from your data, or if you prefer to provide them manually. The Python SDK provides two types of classes based on this distinction:

  • UserProvidedEmbeddingCollection and
  • VantageManagedEmbeddingCollection.

Further, depending on the LLM provider, which is either OpenAI or HuggingFace, Vantage-managed embedding collections are divided into OpenAICollection and HuggingFaceCollection classes. You should instantiate the appropriate one.

In the following examples, you can see how this is done. For more details and parameter descriptions, please check the Embeddings page of our documentation.

📘

Vantage-managed or User-provided Embeddings?

For more information on different collection types refer to our Collections or Embeddings documentation pages.

Vantage-managed embeddings

Below, you can see the code block representing the creation of two types of Vantage-managed embeddings collections.

The parameter that represents the actual embedding model (LLM) differs:

  • OpenAI collections require the llm parameter, where you can provide the OpenAI model name.
  • HuggingFace collections use the external_url parameter, which represents the endpoint URL of the deployed HF model.
from vantage_sdk import VantageClient
from vantage_sdk.model.collection import OpenAICollection

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

openai_collection_id = "vantage-managed-openai"

openai_collection = OpenAICollection(
    collection_id=openai_collection_id,
    embeddings_dimension=1536,
    llm="text-embedding-ada-002",
    external_account_id="YOUR_MODEL_API_KEY_ID",
)

created_collection = vantage_instance.create_collection(
    collection= openai_collection
)

print(created_collection)

from vantage_sdk import VantageClient
from vantage_sdk.model.collection import HuggingFaceCollection

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

openai_collection_id = "vantage-managed-huggingface"

hf_collection = HuggingFaceCollection(
    collection_id=hf_collection,
    embeddings_dimension=1536,
    external_url="HF_ENDPOINT_URL",
    external_account_id="YOUR_MODEL_API_KEY_ID",
)

created_collection = vantage_instance.create_collection(
    collection= hf_collection
)

print(created_collection)

./cli.py create-collection-openai \
    --collection-id 'my-openai-collection' \
    --embeddings-dimension 1536 \
    --llm-model-name 'text-embeddings-ada-002' \
    --llm-secret 'YOUR_OPENAI_SECRET_KEY'

./cli.py create-collection-hf \
    --collection-id 'my-hf-collection' \
    --embeddings-dimension 123 \
    --external-url 'YOUR_HF_ENDPOINT_URL' \
    --llm-secret 'YOUR_OPENAI_SECRET_KEY'

User-provided embeddings

The code block below describes how you can create a user-provided embeddings collection. It simply requires only the collection_id parameter and the embedding_dimensions.

from vantage_sdk import VantageClient
from vantage_sdk.model.collection import UserProvidedEmbeddingsCollection

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

upe_collection_id = "vantage-managed-upe"

upe_collection = UserProvidedEmbeddingsCollection(
    collection_id=upe_collection_id,
    embeddings_dimension=123,
)

created_collection = vantage_instance.create_collection(
    collection= upe_collection
)

print(created_collection)

./cli.py create-collection-upe  \
    --collection-id 'my-upe-collection' \
    --embeddings-dimension 123

Update Collection

The following example updates the collection example-collection.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

collection = vantage_instance.update_collection(
  collection_id="example-collection",
  collection_name="New Collection Name"
)

print(collection)

./cli.py update-collection --collection-id example-collection --collection-name "New Name"

Delete Collection

The following example deletes the collection example-collection.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

vantage_instance.delete_collection(
  collection_id="example-collection",
)

./cli.py delete-collection example-collection

Model API Keys

Here you can find Model API Key management functionalities provided by the Vantage API. Note Model API Keys are the same as External Keys.

If you prefer a visual guide, check out the Console UI walkthrough example: Manage Your Model API Keys

List Model API Keys

The following example returns all Model API Keys created by account ACCOUNT_ID.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

model_keys = vantage_instance.get_external_api_keys()
print(model_keys)

./cli.py get-external-api-keys

Get Model API Key

The following example returns details about the Model API Key with id model-key-id.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

model_key = vantage_instance.get_external_api_key(
    external_key_id = "MODEL_KEY_ID"
)

print(model_key)

./cli.py get-external-api-key model-key-id

Create Model API Key

The following example creates new Model API Key.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

model_key = vantage_instance.create_external_api_key(
    llm_provider = "OpenAI",
    llm_secret = "LLM_SECRET",
)

print(model_key)

./cli.py create-external-api-key \
  --llm-provider "Value" \
  --llm-secret "secret" \
  model-key-id

Update Model API Key

The following example updates the Model API Key with id model-key-id.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

updated_model_key = vantage_instance.update_external_api_key(
    external_key_id = "MODEL_KEY_ID",
    llm_provider = "OpenAI",
    llm_secret = "NEW_LLM_SECRET",
)

print(updated_model_key)
     

./cli.py update-external-api-key \
  --llm-provider "New Value" \
  --llm-secret "new-secret" \
  model-key-id

Delete Model API Key

The following example deletes the Model API Key with id model-key-id.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

vantage_instance.delete_external_api_key(
    external_key_id = "MODEL_KEY_ID"
)

./cli.py delete-external-api-key model-key-id

Vantage API Keys

Here you can find Vantage API key management functionalities provided by the Vantage API.

If you prefer a visual guide, check out the Console UI walkthrough example: Get Your Vantage API Key

List Vantage API Keys

The following example returns all Vantage API keys linked to account ACCOUNT_ID.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

vantage_keys = vantage_instance.get_vantage_api_keys()
print(vantage_keys)

./cli.py get-vantage-api-keys

Get Vantage API Key

The following example returns details about the Vantage API key with id vantage-api-key-id.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

vantage_key = vantage_instance.get_vantage_api_key(
    vantage_api_key_id = "VANTAGE_API_KEY_ID"
)

print(vantage_key)

./cli.py get-vantage-api-key vantage-api-key-id

Data Upload

Vantage offers the possibility to upload documents to collections using multiple methods and data formats:

  • Vantage Documents
    • upsert_documents
  • JSONL Format
    • upsert_documents_from_jsonl_string
    • upsert_documents_from_jsonl_file
  • Parquet Format
    • upsert_documents_from_parquet_file

Below are examples on how to use each of these methods.

Upsert Documents using Vantage Document objects - upsert_documents

Vantage offers multiple document upload options. Depending on the collection type, you can create either a UserProvidedEmbeddingsDocument or a VantageManagedEmbeddingsDocument object.

They differ in that the former requires an embeddings field, matching the embeddings_dimension set for the collection to which you are uploading data, while the latter does not. When uploading documents to a collection, you must upload a list consisting solely of one of these document types.

Below, you can see a code block with examples of both of these cases.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

ids = [
    "1",
    "2",
    "3",
    "4",
]

texts = [
    "First text",
    "Second text",
    "Third text",
    "Fourth text",
]

# Suppose that the collection "example-upe-collection" has 
# the `embedding_dimension` parameter set to 3.
embeddings = [
    [0.123, 0.234, 0.345],
    [0.456, 0.567, 0.678],
    [0.789, 0.891, 0.912],
    [0.257, 0.389, 0.468],
]

documents = [
    UserProvidedEmbeddingsDocument(text=text, id=id, embeddings=emb)
    for id, text, emb in zip(ids, texts, embeddings)
]

vantage_instance.upsert_documents(
    collection_id="example-upe-collection",
    documents=documents
)

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

ids = [
    "1",
    "2",
    "3",
    "4",
]

texts = [
    "First text",
    "Second text",
    "Third text",
    "Fourth text",
]

documents = [
    VantageManagedEmbeddingsDocument(text=text, id=id)
    for id, text in zip(ids, texts)
]

vantage_instance.upsert_documents(
    collection_id="example-vme-collection",
    documents=documents
)

Not supported

Upsert Documents from JSONL string - upsert_documents_from_jsonl_string

There is a possibility to provide your document objects by manually creating your JSONL string. In that case, it's important to follow the Vantage JSONL data ingestion format. We highly recommend you take a look at our documentation page describing it.

Below is one example of how you can upload documents using this approach.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

documents_jsonl = '{
  "id": "1", 
  "text": "Example text", 
  "meta_color": "green", 
  "embeddings": [1,2,3, ...]
}\\n{
  "id": "2", 
  "text": "Sample text", 
  "meta_color": "blue",
  "embeddings": [4,5,6, ...]
}'

vantage_instance.upsert_documents_from_jsonl_string(
    collection_id="example-collection",
    documents_jsonl=documents_jsonl
)

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

documents_jsonl = '{
  "id": "1", 
  "text": "Example text", 
  "meta_color": "green",
}\\n{
  "id": "2", 
  "text": "Sample text", 
  "meta_color": "blue",
}'

vantage_instance.upsert_documents_from_jsonl_string(
    collection_id="example-collection",
    documents_jsonl=documents_jsonl
)

Not supported

Upsert Documents from JSONL file - upsert_documents_from_jsonl_file

The following example uploads data from path_to_data.jsonl file to collection example-collection.

It's important to follow the Vantage JSONL data ingestion format. We highly recommend you take a look at our documentation page describing it.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

vantage_instance.upsert_documents_from_jsonl_file(
    collection_id="example-collection",
    jsonl_file_path="path_to_data.jsonl"
)

./cli.py upsert-documents-from-jsonl --collection-id example-collection "path_to_data.jsonl"

Upsert Documents from Parquet file - upsert_documents_from_parquet_file

The following example uploads data from path_to_data.parquet file to collection example-collection.

It's important to follow the Vantage Parquet data ingestion format. We highly recommend you take a look at our documentation page describing it.

📘

User-provided embeddings Collections only

This method of data upload is available for user-provided embeddings collections only.

from vantage_sdk import VantageClient

vantage_instance = VantageClient.using_vantage_api_key(
    vantage_api_key=VANTAGE_API_KEY,
    account_id=ACCOUNT_ID,
)

vantage_instance.upsert_documents_from_parquet_file(
    collection_id="example-collection",
    parquet_file_path="path_to_data.parquet"
)

./cli.py upsert-documents-from-parquet --collection-id example-collection "path_to_data.jsonl"

Updated about 2 months ago