Method: projects.locations.retrieveContexts

Retrieves relevant contexts for a query.

Endpoint

post https://aiplatform.googleapis.com/v1beta1/{parent}:retrieveContexts

Path parameters

parent string

Required. The resource name of the Location from which to retrieve RagContexts. The users must have permission to make a call in the project. Format: projects/{project}/locations/{location}.

Request body

The request body contains data with the following structure:

Fields
query object (RagQuery)

Required. Single RAG retrieve query.

Union field data_source. Data Source to retrieve contexts. data_source can be only one of the following:
vertexRagStore object (VertexRagStore)

The data source for Vertex RagStore.

Response body

Response message for VertexRagService.RetrieveContexts.

If successful, the response body contains data with the following structure:

Fields
contexts object (RagContexts)

The contexts of the query.

JSON representation 
{
  "contexts": {
    object (RagContexts)
  }
}

VertexRagStore

The data source for Vertex RagStore.

Fields
ragCorpora[]
(deprecated) string

Optional. Deprecated. Please use ragResources to specify the data source.

ragResources[] object (RagResource)

Optional. The representation of the rag source. It can be used to specify corpus only or ragfiles. Currently only support one corpus or multiple files from one corpus. In the future we may open up multiple corpora support.

vectorDistanceThreshold number

Optional. Only return contexts with vector distance smaller than the threshold.

JSON representation 
{
  "ragCorpora": [
    string
  ],
  "ragResources": [
    {
      object (RagResource)
    }
  ],
  "vectorDistanceThreshold": number
}

RagResource

The definition of the Rag resource.

Fields
ragCorpus string

Optional. RagCorpora resource name. Format: projects/{project}/locations/{location}/ragCorpora/{ragCorpus}

ragFileIds[] string

Optional. ragFileId. The files should be in the same ragCorpus set in ragCorpus field.

JSON representation 
{
  "ragCorpus": string,
  "ragFileIds": [
    string
  ]
}

RagQuery

A query to retrieve relevant contexts.

Fields
similarityTopK integer

Optional. The number of contexts to retrieve.

ranking object (Ranking)

Optional. Configurations for hybrid search results ranking.

Union field query. The query to retrieve contexts. Currently only text query is supported. query can be only one of the following:
text string

Optional. The query in text format to get relevant contexts.

JSON representation 
{
  "similarityTopK": integer,
  "ranking": {
    object (Ranking)
  },

  // Union field query can be only one of the following:
  "text": string
  // End of list of possible types for union field query.
}

Ranking

Configurations for hybrid search results ranking.

Fields
alpha number

Optional. Alpha value controls the weight between dense and sparse vector search results. The range is [0, 1], while 0 means sparse vector search only and 1 means dense vector search only. The default value is 0.5 which balances sparse and dense vector search equally.

JSON representation 
{
  "alpha": number
}

RagContexts

Relevant contexts for one query.

Fields
contexts[] object (Context)

All its contexts.

JSON representation 
{
  "contexts": [
    {
      object (Context)
    }
  ]
}

Context

A context of the query.

Fields
sourceUri string

If the file is imported from Cloud Storage or Google Drive, sourceUri will be original file URI in Cloud Storage or Google Drive; if file is uploaded, sourceUri will be file display name.

text string

The text chunk.

distance number

The distance between the query dense embedding vector and the context text vector.

sparseDistance number

The distance between the query sparse embedding vector and the context text vector.

JSON representation 
{
  "sourceUri": string,
  "text": string,
  "distance": number,
  "sparseDistance": number
}