or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai@v0.9.0

docs

authentication.mdazure-on-your-data.mdcontent-filtering.mdindex.mdtypes.md
tile.json

tessl/golang-github-com-azure-azure-sdk-for-go-sdk-ai-azopenai

tessl install tessl/golang-github-com-azure-azure-sdk-for-go-sdk-ai-azopenai@0.9.0

Azure OpenAI extensions module for Go providing models and convenience functions to simplify integration with Azure OpenAI features.

azure-on-your-data.mddocs/

Azure OpenAI On Your Data

Azure OpenAI On Your Data enables retrieval-augmented generation (RAG) by integrating your data sources directly into chat completions. The system retrieves relevant information from configured data sources and includes it in the model's context, enabling more accurate and contextual responses.

Core Function

func WithDataSources(dataSources ...AzureChatExtensionConfigurationClassification) option.RequestOption

Adds Azure data sources to be used with chat completion requests. Returns an option.RequestOption that can be passed to client.Chat.Completions.New().

Parameters:

  • dataSources: One or more data source configurations implementing AzureChatExtensionConfigurationClassification

Returns: An option that configures the chat completion request to use the specified data sources

Usage Example

import (
    "context"
    "github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
    "github.com/openai/openai-go/v3"
)

// Configure Azure AI Search as a data source
dataSource := &azopenai.AzureSearchChatExtensionConfiguration{
    Parameters: &azopenai.AzureSearchChatExtensionParameters{
        Endpoint:  to.Ptr("https://my-search.search.windows.net"),
        IndexName: to.Ptr("my-index"),
        Authentication: &azopenai.OnYourDataSystemAssignedManagedIdentityAuthenticationOptions{},
    },
}

// Use the data source in a chat completion request
resp, err := client.Chat.Completions.New(
    context.TODO(),
    chatParams,
    azopenai.WithDataSources(dataSource),
)

Base Configuration Interface

All data source configurations implement the AzureChatExtensionConfigurationClassification interface:

type AzureChatExtensionConfigurationClassification interface {
    GetAzureChatExtensionConfiguration() *AzureChatExtensionConfiguration
}

type AzureChatExtensionConfiguration struct {
    Type *AzureChatExtensionType // REQUIRED
}

func (a *AzureChatExtensionConfiguration) GetAzureChatExtensionConfiguration() *AzureChatExtensionConfiguration

This interface allows different data source types to be used interchangeably with the WithDataSources function. Each specific data source configuration type (Azure Search, Cosmos DB, Elasticsearch, MongoDB, Pinecone) implements this interface.

Data Source Configurations

Azure AI Search (Cognitive Search)

type AzureSearchChatExtensionConfiguration struct {
    Parameters *AzureSearchChatExtensionParameters // REQUIRED
    Type       *AzureChatExtensionType            // REQUIRED
}

type AzureSearchChatExtensionParameters struct {
    // Required fields
    Endpoint  *string // REQUIRED; Azure Cognitive Search endpoint
    IndexName *string // REQUIRED; Search index name

    // Optional configuration
    AllowPartialResult     *bool
    Authentication         OnYourDataAuthenticationOptionsClassification
    EmbeddingDependency    OnYourDataVectorizationSourceClassification
    FieldsMapping          *AzureSearchIndexFieldMappingOptions
    Filter                 *string
    InScope                *bool
    IncludeContexts        []OnYourDataContextProperty
    MaxSearchQueries       *int32
    QueryType              *AzureSearchQueryType
    SemanticConfiguration  *string
    Strictness             *int32
    TopNDocuments          *int32
}

type AzureSearchIndexFieldMappingOptions struct {
    ContentFields          []string
    ContentFieldsSeparator *string
    FilepathField          *string
    ImageVectorFields      []string
    TitleField             *string
    URLField               *string
    VectorFields           []string
}

Supported Authentication Types:

  • APIKey
  • SystemAssignedManagedIdentity
  • UserAssignedManagedIdentity

Query Types:

type AzureSearchQueryType string

const (
    AzureSearchQueryTypeSimple                AzureSearchQueryType = "simple"
    AzureSearchQueryTypeSemantic              AzureSearchQueryType = "semantic"
    AzureSearchQueryTypeVector                AzureSearchQueryType = "vector"
    AzureSearchQueryTypeVectorSimpleHybrid    AzureSearchQueryType = "vector_simple_hybrid"
    AzureSearchQueryTypeVectorSemanticHybrid  AzureSearchQueryType = "vector_semantic_hybrid"
)

func PossibleAzureSearchQueryTypeValues() []AzureSearchQueryType
  • AzureSearchQueryTypeSimple - Default simple query parser
  • AzureSearchQueryTypeSemantic - Semantic query parser for advanced modeling
  • AzureSearchQueryTypeVector - Vector search over computed data
  • AzureSearchQueryTypeVectorSimpleHybrid - Simple + vector combination
  • AzureSearchQueryTypeVectorSemanticHybrid - Semantic + vector combination

Azure Cosmos DB for MongoDB vCore

type AzureCosmosDBChatExtensionConfiguration struct {
    Parameters *AzureCosmosDBChatExtensionParameters // REQUIRED
    Type       *AzureChatExtensionType              // REQUIRED
}

type AzureCosmosDBChatExtensionParameters struct {
    // Required fields
    ContainerName       *string                                              // REQUIRED
    DatabaseName        *string                                              // REQUIRED
    EmbeddingDependency OnYourDataVectorizationSourceClassification          // REQUIRED
    FieldsMapping       *AzureCosmosDBFieldMappingOptions                    // REQUIRED
    IndexName           *string                                              // REQUIRED

    // Optional configuration
    AllowPartialResult  *bool
    Authentication      OnYourDataAuthenticationOptionsClassification
    InScope             *bool
    IncludeContexts     []OnYourDataContextProperty
    MaxSearchQueries    *int32
    Strictness          *int32
    TopNDocuments       *int32
}

type AzureCosmosDBFieldMappingOptions struct {
    ContentFields          []string // REQUIRED
    VectorFields           []string // REQUIRED
    ContentFieldsSeparator *string
    FilepathField          *string
    TitleField             *string
    URLField               *string
}

Supported Authentication: ConnectionString

Elasticsearch

type ElasticsearchChatExtensionConfiguration struct {
    Parameters *ElasticsearchChatExtensionParameters // REQUIRED
    Type       *AzureChatExtensionType              // REQUIRED
}

type ElasticsearchChatExtensionParameters struct {
    // Required fields
    Endpoint  *string // REQUIRED
    IndexName *string // REQUIRED

    // Optional configuration
    AllowPartialResult     *bool
    Authentication         OnYourDataAuthenticationOptionsClassification
    EmbeddingDependency    OnYourDataVectorizationSourceClassification
    FieldsMapping          *ElasticsearchIndexFieldMappingOptions
    InScope                *bool
    IncludeContexts        []OnYourDataContextProperty
    MaxSearchQueries       *int32
    QueryType              *ElasticsearchQueryType
    Strictness             *int32
    TopNDocuments          *int32
}

type ElasticsearchIndexFieldMappingOptions struct {
    ContentFields          []string
    ContentFieldsSeparator *string
    FilepathField          *string
    TitleField             *string
    URLField               *string
    VectorFields           []string
}

Supported Authentication Types:

  • KeyAndKeyId
  • EncodedAPIKey

Query Types:

type ElasticsearchQueryType string

const (
    ElasticsearchQueryTypeSimple ElasticsearchQueryType = "simple"
    ElasticsearchQueryTypeVector ElasticsearchQueryType = "vector"
)

func PossibleElasticsearchQueryTypeValues() []ElasticsearchQueryType
  • ElasticsearchQueryTypeSimple - Default simple query parser
  • ElasticsearchQueryTypeVector - Vector search over computed data

MongoDB

type MongoDBChatExtensionConfiguration struct {
    Parameters *MongoDBChatExtensionParameters // REQUIRED
    Type       *AzureChatExtensionType        // REQUIRED
}

type MongoDBChatExtensionParameters struct {
    // Required fields
    AppName             *string                                              // REQUIRED
    CollectionName      *string                                              // REQUIRED
    DatabaseName        *string                                              // REQUIRED
    EmbeddingDependency *MongoDBChatExtensionParametersEmbeddingDependency  // REQUIRED
    Endpoint            *string                                              // REQUIRED
    FieldsMapping       *MongoDBChatExtensionParametersFieldsMapping        // REQUIRED
    IndexName           *string                                              // REQUIRED

    // Optional configuration
    AllowPartialResult  *bool
    Authentication      *OnYourDataUsernameAndPasswordAuthenticationOptions
    InScope             *bool
    IncludeContexts     []OnYourDataContextProperty
    MaxSearchQueries    *int32
    Strictness          *int32
    TopNDocuments       *int32
}

type MongoDBChatExtensionParametersFieldsMapping struct {
    ContentFields          []string // REQUIRED
    VectorFields           []string // REQUIRED
    ContentFieldsSeparator *string
    FilepathField          *string
    TitleField             *string
    URLField               *string
}

Supported Authentication Types:

  • AccessToken
  • SystemAssignedManagedIdentity
  • UserAssignedManagedIdentity

Creating Embedding Dependency:

func NewMongoDBChatExtensionParametersEmbeddingDependency[T OnYourDataDeploymentNameVectorizationSource | OnYourDataEndpointVectorizationSource](value T) *MongoDBChatExtensionParametersEmbeddingDependency

Pinecone

type PineconeChatExtensionConfiguration struct {
    Parameters *PineconeChatExtensionParameters // REQUIRED
    Type       *AzureChatExtensionType         // REQUIRED
}

type PineconeChatExtensionParameters struct {
    // Required fields
    EmbeddingDependency OnYourDataVectorizationSourceClassification // REQUIRED
    Environment         *string                                     // REQUIRED
    FieldsMapping       *PineconeFieldMappingOptions               // REQUIRED
    IndexName           *string                                     // REQUIRED

    // Optional configuration
    AllowPartialResult  *bool
    Authentication      OnYourDataAuthenticationOptionsClassification
    InScope             *bool
    IncludeContexts     []OnYourDataContextProperty
    MaxSearchQueries    *int32
    Strictness          *int32
    TopNDocuments       *int32
}

type PineconeFieldMappingOptions struct {
    ContentFields          []string // REQUIRED
    ContentFieldsSeparator *string
    FilepathField          *string
    TitleField             *string
    URLField               *string
}

Supported Authentication: APIKey

Response Data

Extracting Context from Responses

type ChatCompletionMessage openai.ChatCompletionMessage

func (c ChatCompletionMessage) Context() (*AzureChatExtensionsMessageContext, error)

Use the Context() method to access Azure chat extensions data from completion messages:

azureMessage := azopenai.ChatCompletionMessage(resp.Choices[0].Message)
context, err := azureMessage.Context()
if err == nil && context != nil {
    // Access citations
    for _, citation := range context.Citations {
        fmt.Printf("Citation: %s\n", *citation.Content)
    }

    // Access all retrieved documents
    for _, doc := range context.AllRetrievedDocuments {
        fmt.Printf("Document: %s\n", *doc.Content)
    }

    // Access detected intent
    if context.Intent != nil {
        fmt.Printf("Intent: %s\n", *context.Intent)
    }
}

Context Types

type AzureChatExtensionsMessageContext struct {
    AllRetrievedDocuments []AzureChatExtensionRetrievedDocument
    Citations             []AzureChatExtensionDataSourceResponseCitation
    Intent                *string
}

type AzureChatExtensionDataSourceResponseCitation struct {
    Content     *string   // REQUIRED; Citation content
    ChunkID     *string
    Filepath    *string
    RerankScore *float64
    Title       *string
    URL         *string
}

type AzureChatExtensionRetrievedDocument struct {
    Content             *string                                        // REQUIRED
    DataSourceIndex     *int32                                         // REQUIRED
    SearchQueries       []string                                       // REQUIRED
    ChunkID             *string
    Filepath            *string
    FilterReason        *AzureChatExtensionRetrieveDocumentFilterReason
    OriginalSearchScore *float64
    RerankScore         *float64
    Title               *string
    URL                 *string
}

Vectorization Sources

Data sources that support vector search require a vectorization source to generate embeddings.

Deployment Name Vectorization

Uses an embedding model deployment within the same Azure OpenAI resource via internal call:

type OnYourDataDeploymentNameVectorizationSource struct {
    DeploymentName *string                         // REQUIRED
    Type           *OnYourDataVectorizationSourceType // REQUIRED
    Dimensions     *int32                          // Optional; for text-embedding-3+
}

Example:

vectorSource := &azopenai.OnYourDataDeploymentNameVectorizationSource{
    DeploymentName: to.Ptr("my-embedding-deployment"),
    Type:           to.Ptr(azopenai.OnYourDataVectorizationSourceTypeDeploymentName),
    Dimensions:     to.Ptr(int32(1536)),
}

Endpoint Vectorization

Uses a public Azure OpenAI embedding endpoint:

type OnYourDataEndpointVectorizationSource struct {
    Authentication OnYourDataVectorSearchAuthenticationOptionsClassification // REQUIRED
    Endpoint       *string                                                   // REQUIRED
    Type           *OnYourDataVectorizationSourceType                        // REQUIRED
}

Example:

vectorSource := &azopenai.OnYourDataEndpointVectorizationSource{
    Endpoint: to.Ptr("https://my-resource.openai.azure.com/openai/deployments/my-embedding/embeddings"),
    Type:     to.Ptr(azopenai.OnYourDataVectorizationSourceTypeEndpoint),
    Authentication: &azopenai.OnYourDataVectorSearchAPIKeyAuthenticationOptions{
        Key:  to.Ptr("your-api-key"),
        Type: to.Ptr(azopenai.OnYourDataVectorSearchAuthenticationTypeAPIKey),
    },
}

Integrated Vectorization

Uses the vectorizer defined within the search resource:

type OnYourDataIntegratedVectorizationSource struct {
    Type *OnYourDataVectorizationSourceType // REQUIRED
}

Model ID Vectorization (Elasticsearch only)

Uses a specific embedding model ID defined in the search service:

type OnYourDataModelIDVectorizationSource struct {
    ModelID *string                         // REQUIRED
    Type    *OnYourDataVectorizationSourceType // REQUIRED
}

Configuration Parameters

Common Parameters

Most data source configurations support these common parameters:

AllowPartialResult (*bool): If true, allows partial search results when some queries fail. If false or not specified, the request fails if any search query fails.

InScope (*bool): Whether queries should be restricted to use of indexed data only.

IncludeContexts ([]OnYourDataContextProperty): Specifies which properties to include in the output context. Default is citations and intent. Options:

  • OnYourDataContextPropertyCitations
  • OnYourDataContextPropertyIntent
  • OnYourDataContextPropertyAllRetrievedDocuments

MaxSearchQueries (*int32): Maximum number of rewritten queries to send to the search provider for one user message. If not specified, the system decides the number.

Strictness (*int32): Configured strictness of search relevance filtering. Higher values mean higher precision but lower recall.

TopNDocuments (*int32): Configured top number of documents to feature for the configured query.

Field Mapping

Field mapping options control how index fields are interpreted and used:

ContentFields ([]string): Names of index fields to treat as content (typically required)

VectorFields ([]string): Names of fields representing vector data (required for vector search)

ContentFieldsSeparator (*string): Separator pattern for combining content fields

FilepathField (*string): Field to use as filepath in citations

TitleField (*string): Field to use as title in citations

URLField (*string): Field to use as URL in citations

ImageVectorFields ([]string): Fields representing image vector data (Azure Search only)

Extension Type Constants

type AzureChatExtensionType string

const (
    AzureChatExtensionTypeAzureCosmosDB AzureChatExtensionType = "azure_cosmos_db"
    AzureChatExtensionTypeAzureSearch   AzureChatExtensionType = "azure_search"
    AzureChatExtensionTypeElasticsearch AzureChatExtensionType = "elasticsearch"
    AzureChatExtensionTypeMongoDB       AzureChatExtensionType = "mongo_db"
    AzureChatExtensionTypePinecone      AzureChatExtensionType = "pinecone"
)

func PossibleAzureChatExtensionTypeValues() []AzureChatExtensionType

Filter Reasons

type AzureChatExtensionRetrieveDocumentFilterReason string

const (
    AzureChatExtensionRetrieveDocumentFilterReasonRerank AzureChatExtensionRetrieveDocumentFilterReason = "rerank"
    AzureChatExtensionRetrieveDocumentFilterReasonScore  AzureChatExtensionRetrieveDocumentFilterReason = "score"
)

func PossibleAzureChatExtensionRetrieveDocumentFilterReasonValues() []AzureChatExtensionRetrieveDocumentFilterReason

Rerank: Document filtered by rerank score and top_n_documents configuration Score: Document filtered by original search score threshold (strictness)