Repository navigation
Legacy Semantic Retrieval (AQA)
Warning
Legacy API. Google no longer documents Semantic Retrieval (corpora, documents, chunks, permissions) or the
AQA (Attributed Question Answering) model, and Google may remove them at any time. The endpoints and models/aqa
still respond today, and the SDK still supports them, but GoogleAIModels.Aqa is marked [Obsolete].
For new work, use File Search (Gemini API) or the Vertex RAG Engine.
This page combines the former Semantic Search Retrieval with Google AQA, Corpora Client, Document Client, Chunk Client and Corpus Permission Client pages.
- Concepts
- Setup and authentication
- End-to-end example: question answering with AQA
- CorporaManager (high-level API)
- CorporaClient
- DocumentsClient
- ChunkClient
- CorpusPermissionClient
- Notes
- Retrieval-Augmented Generation (RAG) first finds relevant passages in your own knowledge base, then gives them to the model, so answers are grounded in your documents.
- Semantic search matches by meaning, using embeddings, rather than by exact keywords.
-
Corpus → Document → Chunk: a corpus is a collection of documents, and each document is split into chunks.
Chunks are the units that get indexed and returned by queries. Corpora, documents and chunks can carry
CustomMetadata, which you can filter on in queries. -
AQA (Attributed Question Answering) is a model that answers questions from the chunks in a corpus. It returns
an
AnswerableProbability, which is its confidence that the corpus contains the answer.
All types are in GenerativeAI.Types. The clients are in GenerativeAI.Clients.
dotnet add package Google_GenerativeAI
dotnet add package Google_GenerativeAI.Auth # GoogleServiceAccountAuthenticator / GoogleOAuthAuthenticator
dotnet add package DocumentChunker # optional, used in the example below to split textThe corpora endpoints need OAuth credentials; an API key alone isn't enough. CorporaManager and
GoogleAi.CreateCorpusManager() / CreatSemanticRetrieverModel() throw GenerativeAIException if the platform has
no IGoogleAuthenticator.
One-time Google Cloud setup for a service account:
- In the Google Cloud Console, open IAM & Admin → Service accounts.
- Create a service account, or pick an existing one, then create and download a JSON key.
- Set an environment variable, for example
Google_Service_Account_Json, to the full path of the key file.
using GenerativeAI;
using GenerativeAI.Authenticators;
var keyPath = Environment.GetEnvironmentVariable("Google_Service_Account_Json")
?? throw new InvalidOperationException("Google_Service_Account_Json is not set.");
var authenticator = new GoogleServiceAccountAuthenticator(keyPath);
// Option A: model + manager in one go
#pragma warning disable CS0618 // GoogleAIModels.Aqa is obsolete (legacy model)
var retrieverModel = new SemanticRetrieverModel(GoogleAIModels.Aqa, EnvironmentVariables.GOOGLE_API_KEY!, authenticator);
#pragma warning restore CS0618
var corporaManager = retrieverModel.CorporaManager;
// Option B: from GoogleAi
var googleAi = new GoogleAi(EnvironmentVariables.GOOGLE_API_KEY);
var manager = googleAi.CreateCorpusManager(authenticator);
var aqa = googleAi.CreatSemanticRetrieverModel("models/aqa", authenticator: authenticator); // method name is spelled "Creat" in the SDK
// Option C: low-level clients share one platform adapter
var platform = new GoogleAIPlatformAdapter(EnvironmentVariables.GOOGLE_API_KEY, authenticator: authenticator);
var corporaClient = new CorporaClient(platform); // (platform, HttpClient? httpClient = null, ILogger? logger = null)
var documentsClient = new DocumentsClient(platform);
var chunkClient = new ChunkClient(platform);
var permissionClient = new CorpusPermissionClient(platform);This example creates (or reuses) a corpus, adds a book split into chunks, and asks AQA a question about it.
using GenerativeAI;
using GenerativeAI.Authenticators;
using GenerativeAI.Clients;
using GenerativeAI.Types;
using DocumentChunker.Chunkers;
using DocumentChunker.Core;
using DocumentChunker.Enum;
public class Program
{
public static async Task Main()
{
// 1. Authentication and model
var keyPath = Environment.GetEnvironmentVariable("Google_Service_Account_Json")
?? throw new InvalidOperationException("Google_Service_Account_Json is not set.");
var authenticator = new GoogleServiceAccountAuthenticator(keyPath);
#pragma warning disable CS0618
var retrieverModel = new SemanticRetrieverModel(GoogleAIModels.Aqa, EnvironmentVariables.GOOGLE_API_KEY!, authenticator);
#pragma warning restore CS0618
// 2. Corpus
var corporaManager = retrieverModel.CorporaManager;
var corpus = await GetOrCreateCorpusAsync(corporaManager, "My Search Corpus");
// 3. Document and chunks
await AddDocumentAndChunksAsync(corporaManager, corpus.Name!,
"https://www.gutenberg.org/cache/epub/1184/pg1184.txt", "The Count of Monte Cristo", "Alexandre Dumas");
// 4. Question answering
var chatSession = retrieverModel.CreateChatSession(corpus.Name!, AnswerStyle.VERBOSE);
var question = "What is Edmond Dantes imprisoned for?";
var answer = await chatSession.GenerateAnswerAsync(question);
Console.WriteLine($"Question: {question}");
Console.WriteLine($"Answer: {answer.GetAnswer()}");
Console.WriteLine($"Answerable Probability: {answer.AnswerableProbability}");
}
private static async Task<Corpus> GetOrCreateCorpusAsync(CorporaManager corporaManager, string displayName)
{
var corpora = await corporaManager.ListCorporaAsync();
var existing = corpora?.FirstOrDefault(c => c.DisplayName == displayName);
return existing ?? (await corporaManager.CreateCorpusAsync(displayName))!;
}
private static async Task AddDocumentAndChunksAsync(CorporaManager corporaManager, string corpusName,
string contentUrl, string documentName, string author)
{
var chunker = new PlainTextDocumentChunker(new ChunkerConfig(500, ChunkType.Paragraph));
var document = await corporaManager.AddDocumentAsync(corpusName, documentName,
new List<CustomMetadata> { new CustomMetadata { Key = "Author", StringValue = author } });
await foreach (var textParts in chunker.ExtractChunksInPartsFromUrlAsync(contentUrl, 100))
{
var chunks = textParts.Select(text => new Chunk { Data = new ChunkData { StringValue = text } }).ToList();
await corporaManager.AddChunksAsync(document!.Name!, chunks);
}
}
}AnswerStyle values: ABSTRACTIVE (short and abstractive), EXTRACTIVE (very short and extractive), VERBOSE
(longer, with extra detail). SemanticRetrieverChatSession keeps the conversation history between calls.
You can also call SemanticRetrieverModel.GenerateAnswerAsync(GenerateAnswerRequest) directly.
CorporaManager wraps the four clients below. Its methods return simple results, such as List<T> instead of paged
responses. Every method also takes an optional CancellationToken.
| Area | Methods |
|---|---|
| Corpora |
CreateCorpusAsync(displayName), GetCorpusAsync(corpusName), ListCorporaAsync(), DeleteCorpusAsync(corpusName, force = false)
|
| Documents |
AddDocumentAsync(corpusName, displayName, metadata = null), GetDocumentAsync(documentName), ListDocumentsAsync(corpusName), DeleteDocumentAsync(documentName, force = false)
|
| Chunks |
AddChunkAsync(documentName, chunk), AddChunksAsync(documentName, chunks) (batch create), GetChunkAsync(chunkName), ListChunksAsync(documentName), DeleteChunkAsync(chunkName)
|
| Permissions |
CreateCorpusPermissionAsync(corpusName, permission), GetPermissionAsync(permissionName), ListCorpusPermissionsAsync(corpusName), DeletePermissionAsync(permissionName)
|
| Queries |
QueryCorpusAsync(corpusName, query), QueryDocumentAsync(documentName, query)
|
var results = await corporaManager.QueryCorpusAsync(corpus.Name!, "Who is Mercedes?");
foreach (var relevant in results?.RelevantChunks ?? new())
Console.WriteLine($"{relevant.ChunkRelevanceScore:F2}: {relevant.Chunk?.Data?.StringValue}");Low-level client for the corpora endpoint.
| Method | Description |
|---|---|
CreateCorpusAsync(Corpus corpus) |
Creates a corpus |
QueryCorpusAsync(string name, QueryCorpusRequest request) |
Semantic search over a corpus |
ListCorporaAsync(int? pageSize = null, string? pageToken = null) |
Lists corpora (ListCorporaResponse.Corpora, NextPageToken) |
GetCorpusAsync(string name) |
Gets a corpus |
UpdateCorpusAsync(string corpusName, Corpus corpus, string updateMask) |
Updates the fields listed in updateMask
|
DeleteCorpusAsync(string name, bool? force = null) |
Deletes a corpus. Pass force: true to also delete its documents and chunks |
var created = await corporaClient.CreateCorpusAsync(new Corpus { DisplayName = "My Sample Corpus" });
Console.WriteLine($"Corpus created: {created?.Name}");
var query = new QueryCorpusRequest
{
Query = "What are the key concepts in this document?",
ResultsCount = 5,
MetadataFilters = new List<MetadataFilter>
{
new MetadataFilter
{
Key = "chunk.custom_metadata.Author",
Conditions = new List<Condition> { new Condition { Operation = Operator.EQUAL, StringValue = "Alexandre Dumas" } }
}
}
};
var response = await corporaClient.QueryCorpusAsync("corpora/my-corpus-id", query);
foreach (var relevant in response?.RelevantChunks ?? new())
Console.WriteLine($"Relevant chunk: {relevant.Chunk?.Data?.StringValue}");
var list = await corporaClient.ListCorporaAsync(pageSize: 10);
foreach (var c in list?.Corpora ?? new()) Console.WriteLine(c.Name);
var corpusToUpdate = new Corpus { Name = "corpora/my-corpus-id", DisplayName = "My Updated Corpus Name" };
var updated = await corporaClient.UpdateCorpusAsync("corpora/my-corpus-id", corpusToUpdate, "displayName");
await corporaClient.DeleteCorpusAsync("corpora/my-corpus-id", force: true);Low-level client for corpora/*/documents.
| Method | Description |
|---|---|
CreateDocumentAsync(string parent, Document document) |
Creates a document in a corpus |
QueryDocumentAsync(string name, QueryDocumentRequest request) |
Semantic search inside one document |
ListDocumentsAsync(string parent, int? pageSize = null, string? pageToken = null) |
Lists documents (ListDocumentsResponse.Documents) |
GetDocumentAsync(string name) |
Gets a document |
UpdateDocumentAsync(string name, Document document, string updateMask) |
Updates the fields listed in updateMask (displayName, customMetadata) |
DeleteDocumentAsync(string name, bool? force = null) |
Deletes a document. Pass force: true to also delete its chunks |
var document = await documentsClient.CreateDocumentAsync("corpora/my-corpus-id", new Document
{
DisplayName = "My Sample Document",
CustomMetadata = new List<CustomMetadata> { new CustomMetadata { Key = "my key", StringValue = "This is a test document" } }
});
var docResults = await documentsClient.QueryDocumentAsync(document!.Name!,
new QueryDocumentRequest("What is mentioned about topic X in this document?") { ResultsCount = 5 });
foreach (var relevant in docResults?.RelevantChunks ?? new())
Console.WriteLine(relevant.Chunk?.Data?.StringValue);
var fetched = await documentsClient.GetDocumentAsync(document.Name!);
Console.WriteLine(fetched?.DisplayName);
await documentsClient.UpdateDocumentAsync(document.Name!,
new Document { Name = document.Name, DisplayName = "My Updated Document Name" }, "displayName");
await documentsClient.DeleteDocumentAsync(document.Name!, force: true);Low-level client for corpora/*/documents/*/chunks.
| Method | Description |
|---|---|
CreateChunkAsync(string parent, Chunk chunk) |
Creates a chunk in a document |
ListChunksAsync(string parent, int? pageSize = null, string? pageToken = null) |
Lists chunks (ListChunksResponse.Chunks) |
GetChunkAsync(string name) |
Gets a chunk |
UpdateChunkAsync(Chunk chunk, string updateMask) |
Updates a chunk (chunk.Name must be set), for example with "data,customMetadata"
|
DeleteChunkAsync(string name) |
Deletes a chunk |
BatchCreateChunksAsync(string parent, List<CreateChunkRequest> requests) |
Creates several chunks (BatchCreateChunksResponse.Chunks) |
BatchUpdateChunksAsync(string parent, List<UpdateChunkRequest> requests) |
Updates several chunks (BatchUpdateChunksResponse.Chunks) |
BatchDeleteChunksAsync(string parent, List<DeleteChunkRequest> requests) |
Deletes several chunks |
var parent = "corpora/my-corpus-id/documents/my-document-id";
var chunk = await chunkClient.CreateChunkAsync(parent, new Chunk
{
Data = new ChunkData { StringValue = "This is the content of my chunk." },
CustomMetadata = new List<CustomMetadata> { new CustomMetadata { Key = "key1", StringValue = "value1" } }
});
// chunk.State is STATE_PENDING_PROCESSING until the chunk is indexed, then STATE_ACTIVE
var page = await chunkClient.ListChunksAsync(parent, pageSize: 20);
foreach (var c in page?.Chunks ?? new()) Console.WriteLine($"{c.Name}: {c.Data?.StringValue}");
await chunkClient.UpdateChunkAsync(new Chunk
{
Name = chunk!.Name,
Data = new ChunkData { StringValue = "This is the updated chunk content." }
}, "data");
var created = await chunkClient.BatchCreateChunksAsync(parent, new List<CreateChunkRequest>
{
new CreateChunkRequest(parent, new Chunk { Data = new ChunkData { StringValue = "Chunk 1 content" } }),
new CreateChunkRequest(parent, new Chunk { Data = new ChunkData { StringValue = "Chunk 2 content" } }),
});
await chunkClient.BatchUpdateChunksAsync(parent, new List<UpdateChunkRequest>
{
new UpdateChunkRequest
{
Chunk = new Chunk { Name = $"{parent}/chunks/chunk1", Data = new ChunkData { StringValue = "Updated Chunk 1 content" } },
UpdateMask = "data"
}
});
await chunkClient.BatchDeleteChunksAsync(parent, new List<DeleteChunkRequest>
{
new DeleteChunkRequest { Name = $"{parent}/chunks/chunk1" },
new DeleteChunkRequest { Name = $"{parent}/chunks/chunk2" },
});
await chunkClient.DeleteChunkAsync(chunk.Name!);Manages who can read or write a corpus.
| Method | Description |
|---|---|
CreatePermissionAsync(string parent, Permission permission) |
Grants a permission on a corpus |
ListPermissionsAsync(string parent, int? pageSize = null, string? pageToken = null) |
Lists permissions (ListPermissionsResponse.Permissions) |
GetPermissionAsync(string name) |
Gets a permission |
UpdatePermissionAsync(string permissionName, Permission permission, string? updateMask = null) |
Updates a permission (for example "role") |
DeletePermissionAsync(string name) |
Revokes a permission |
Permission has GranteeType (USER, GROUP, EVERYONE), EmailAddress (required for USER and GROUP) and
Role (OWNER, WRITER, READER).
var created = await permissionClient.CreatePermissionAsync("corpora/my-corpus-id", new Permission
{
GranteeType = GranteeType.USER,
EmailAddress = "user@example.com",
Role = Role.READER
});
var permissions = await permissionClient.ListPermissionsAsync("corpora/my-corpus-id");
foreach (var p in permissions?.Permissions ?? new())
Console.WriteLine($"{p.Name}: {p.EmailAddress} ({p.Role})");
await permissionClient.UpdatePermissionAsync(created!.Name!, new Permission { Name = created.Name, Role = Role.WRITER }, "role");
await permissionClient.DeletePermissionAsync(created.Name!);- Resource names look like
corpora/{corpus},corpora/{corpus}/documents/{document},corpora/{corpus}/documents/{document}/chunks/{chunk}andcorpora/{corpus}/permissions/{permission}. -
updateMaskdecides which fields an update changes. Fields not listed in the mask are left as they are. - Errors come back as
ApiException(see Configuration and Error Handling). Watch the rate limits when you add many chunks, and prefer the batch methods. -
Moving off this API:
-
File Search: managed upload, chunking and retrieval on the Gemini API. Ground any Gemini model with
GenerativeModel.UseFileSearch(storeName). - Vertex RAG Engine: RAG corpora on Vertex AI, with managed or external vector databases.
-
File Search: managed upload, chunking and retrieval on the Gemini API. Ground any Gemini model with
Getting Started
- Initialization
- Authentication
- Configuration & Error Handling
- Supported Models
- Migration Guide (v4)
- Release Notes (v4)
Core Features
- Generate Content
- Chat Session
- Streaming
- Multimodal Features
- JSON Mode
- Function Calling
- Embeddings
- Context Caching
Gemini APIs
- Interactions API
- Multimodal Live API
- File Search
- Batch API
- Model Tuning
- Webhooks
- Agent APIs
- Image Generation
- Video Generation
- Speech Generation
- Files Client
- Model Client
Vertex AI
Integrations
Guides
Legacy