Method: locations.retrieveContexts

Full name: projects.locations.retrieveContexts

Retrieves relevant contexts for a query.

Endpoint

post

https:  
/  
/{service-endpoint}  
/v1  
/{parent}:retrieveContexts

Where {service-endpoint} is one of the supported service endpoints .

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.

data_source Union type

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

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
 (deprecated)

number

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

JSON representation
{ "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

ragRetrievalConfig

object (  RagRetrievalConfig 
 
)

Optional. The retrieval config for the query.

query Union type

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
{ "ragRetrievalConfig" : { object ( `RagRetrievalConfig` ) } , // query "text" : string // Union type }

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.

sourceDisplayName string

The file display name.

text string

The text chunk.

chunk

object (  RagChunk 
 
)

Context of the retrieved chunk.

score number

According to the underlying Vector DB and the selected metric type, the score can be either the distance or the similarity between the query and the context and its range depends on the metric type.

For example, if the metric type is COSINE_DISTANCE, it represents the distance between the query and the context. The larger the distance, the less relevant the context is to the query. The range is [0, 2], while 0 means the most relevant and 2 means the least relevant.

JSON representation
{ "sourceUri" : string , "sourceDisplayName" : string , "text" : string , "chunk" : { object ( `RagChunk` ) } , "score" : number }