Incorporamenti OpenAI di Azure archivia l'associazione di output per Funzioni di Azure

Importante

L'estensione OpenAI di Azure per Funzioni di Azure è attualmente in anteprima.

L'associazione di output dell'archivio di incorporamenti OpenAI di Azure consente di scrivere file in un archivio documenti semantico a cui è possibile fare riferimento in un secondo momento in una ricerca semantica.

Per informazioni sull'installazione e la configurazione dell'estensione OpenAI di Azure, vedere Estensioni OpenAI di Azure per Funzioni di Azure. Per altre informazioni sulla classificazione semantica in Ricerca di intelligenza artificiale di Azure, vedere Classificazione semantica in Ricerca di intelligenza artificiale di Azure.

Nota

I riferimenti e gli esempi vengono forniti solo per il modello Node.js v4.

Nota

I riferimenti e gli esempi vengono forniti solo per il modello Python v2.

Nota

Anche se sono supportati entrambi i modelli di processo C#, vengono forniti solo esempi di modelli di lavoro isolati.

Esempio

Il supporto Go non è attualmente disponibile per questo binding.

Questo esempio scrive un flusso di input HTTP in un archivio documenti semantico nell'URL fornito.

public class EmbeddingsRequest
{
    [JsonPropertyName("url")]
    public string? Url { get; set; }
}
[Function("IngestFile")]
public static async Task<EmbeddingsStoreOutputResponse> IngestFile(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
{
    using StreamReader reader = new(req.Body);
    string request = await reader.ReadToEndAsync();

    EmbeddingsStoreOutputResponse badRequestResponse = new()
    {
        HttpResponse = new BadRequestResult(),
        SearchableDocument = new SearchableDocument(string.Empty)
    };

    if (string.IsNullOrWhiteSpace(request))
    {
        return badRequestResponse;
    }

    EmbeddingsRequest? requestBody = JsonSerializer.Deserialize<EmbeddingsRequest>(request);

    if (string.IsNullOrWhiteSpace(requestBody?.Url))
    {
        throw new ArgumentException("Invalid request body. Make sure that you pass in {\"url\": value } as the request body.");
    }

    if (!Uri.TryCreate(requestBody.Url, UriKind.Absolute, out Uri? uri))
    {
        return badRequestResponse;
    }

    string filename = Path.GetFileName(uri.AbsolutePath);

    return new EmbeddingsStoreOutputResponse
    {
        HttpResponse = new OkObjectResult(new { status = HttpStatusCode.OK }),
        SearchableDocument = new SearchableDocument(filename)
    };
}

Questo esempio scrive un flusso di input HTTP in un archivio documenti semantico nell'URL fornito.

@FunctionName("IngestFile")
public HttpResponseMessage ingestFile(
    @HttpTrigger(
        name = "req", 
        methods = {HttpMethod.POST},
        authLevel = AuthorizationLevel.FUNCTION)
        HttpRequestMessage<EmbeddingsRequest> request,
    @EmbeddingsStoreOutput(name="EmbeddingsStoreOutput", input = "{url}", inputType = InputType.Url,
            storeConnectionName = "AISearchEndpoint", collection = "openai-index",
            embeddingsModel = "%EMBEDDING_MODEL_DEPLOYMENT_NAME%", aiConnectionName = "AzureOpenAI") OutputBinding<EmbeddingsStoreOutputResponse> output,
    final ExecutionContext context) throws URISyntaxException {

    if (request.getBody() == null || request.getBody().getUrl() == null)
    {
        throw new IllegalArgumentException("Invalid request body. Make sure that you pass in {\"url\": value } as the request body.");
    }

    URI uri = new URI(request.getBody().getUrl());
    String filename = Paths.get(uri.getPath()).getFileName().toString();

    EmbeddingsStoreOutputResponse embeddingsStoreOutputResponse = new EmbeddingsStoreOutputResponse(new SearchableDocument(filename));

    output.setValue(embeddingsStoreOutputResponse);

    JSONObject response = new JSONObject();
    response.put("status", "success");
    response.put("title", filename);

    return request.createResponseBuilder(HttpStatus.CREATED)
            .header("Content-Type", "application/json")
            .body(response)
            .build();
}

public class EmbeddingsStoreOutputResponse {
    private SearchableDocument searchableDocument;

    public EmbeddingsStoreOutputResponse(SearchableDocument searchableDocument) {
        this.searchableDocument = searchableDocument;
    }
    public SearchableDocument getSearchableDocument() {
        return searchableDocument;
    }

}

Questo esempio scrive un flusso di input HTTP in un archivio documenti semantico nell'URL fornito.

const embeddingsStoreOutput = output.generic({
    type: "embeddingsStore",
    input: "{url}", 
    inputType: "url", 
    storeConnectionName: "AISearchEndpoint", 
    collection: "openai-index", 
    embeddingsModel: "%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    aiConnectionName: 'AzureOpenAI',
});

app.http('IngestFile', {
    methods: ['POST'],
    authLevel: 'function',
    extraOutputs: [embeddingsStoreOutput],
    handler: async (request, context) => {
        let requestBody = await request.json();
        if (!requestBody || !requestBody.url) {
            throw new Error("Invalid request body. Make sure that you pass in {\"url\": value } as the request body.");
        }

        let uri = requestBody.url;
        let url = new URL(uri);

        let fileName = path.basename(url.pathname);
        context.extraOutputs.set(embeddingsStoreOutput, { title: fileName });

        let response = {
            status: "success",
            title: fileName
        };

        return { status: 202, jsonBody: response } 
    }
});

interface EmbeddingsRequest {
    url?: string;
}

const embeddingsStoreOutput = output.generic({
    type: "embeddingsStore",
    input: "{url}", 
    inputType: "url", 
    storeConnectionName: "AISearchEndpoint", 
    collection: "openai-index", 
    embeddingsModel: "%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    aiConnectionName: 'AzureOpenAI',
});

app.http('IngestFile', {
    methods: ['POST'],
    authLevel: 'function',
    extraOutputs: [embeddingsStoreOutput],
    handler: async (request, context) => {
        let requestBody: EmbeddingsRequest | null = await request.json();
        if (!requestBody || !requestBody.url) {
            throw new Error("Invalid request body. Make sure that you pass in {\"url\": value } as the request body.");
        }

        let uri = requestBody.url;
        let url = new URL(uri);

        let fileName = path.basename(url.pathname);
        context.extraOutputs.set(embeddingsStoreOutput, { title: fileName });

        let response = {
            status: "success",
            title: fileName
        };

        return { status: 202, jsonBody: response } 
    }
});

Questo esempio scrive un flusso di input HTTP in un archivio documenti semantico nell'URL fornito.

Ecco il file function.json per l'inserimento di file:

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "name": "EmbeddingsStoreOutput",
      "type": "embeddingsStore",
      "direction": "out",
      "input": "{url}",
      "inputType": "Url",
      "storeConnectionName": "AISearchEndpoint",
      "collection": "openai-index",
      "embeddingsModel": "%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
      "aiConnectionName": "AzureOpenAI"
    }
  ]
}

Per altre informazioni sulle proprietà dei file function.json, vedere la sezione configurazione.

using namespace System.Net

param($Request, $TriggerMetadata)

$ErrorActionPreference = 'Stop'

$inputJson = $Request.Body

if (-not $inputJson -or -not $inputJson.Url) {
    throw 'Invalid request body. Make sure that you pass in {\"url\": value } as the request body.'
}

$uri = [URI]$inputJson.Url
$filename = [System.IO.Path]::GetFileName($uri.AbsolutePath)


Push-OutputBinding -Name EmbeddingsStoreOutput -Value @{
    "title" = $filename
}

$response = @{
    "status" = "success"
    "title" = $filename
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
        StatusCode = [HttpStatusCode]::OK
        Body = $response
        Headers    = @{
            "Content-Type" = "application/json"
        }
})

Questo esempio scrive un flusso di input HTTP in un archivio documenti semantico nell'URL fornito.

@app.function_name("IngestFile")
@app.route(methods=["POST"])
@app.embeddings_store_output(
    arg_name="requests",
    input="{url}",
    input_type="url",
    store_connection_name="AISearchEndpoint",
    collection="openai-index",
    embeddings_model="%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    ai_connection_name="AzureOpenAI",
)
def ingest_file(
    req: func.HttpRequest, requests: func.Out[str]
) -> func.HttpResponse:
    user_message = req.get_json()
    if not user_message:
        return func.HttpResponse(
            json.dumps({"message": "No message provided"}),
            status_code=400,
            mimetype="application/json",
        )
    file_name_with_extension = os.path.basename(user_message["url"])
    title = os.path.splitext(file_name_with_extension)[0]
    create_request = {"title": title}
    requests.set(json.dumps(create_request))
    response_json = {"status": "success", "title": title}
    return func.HttpResponse(
        json.dumps(response_json), status_code=200, mimetype="application/json"
    )

Attributi

Applicare l'attributo EmbeddingsStoreOutput per definire un'associazione di output dell'archivio incorporamenti, che supporta questi parametri:

Parametro Descrizione
Inserimento Stringa di input per cui generare incorporamenti.
AIConnectionName Facoltativo. Ottiene o imposta il nome della sezione di configurazione per le impostazioni di connettività del servizio di intelligenza artificiale. Per Azure OpenAI: se specificato, cerca i valori "Endpoint" e "Key" in questa sezione di configurazione. Se non specificato o la sezione non esiste, esegue il fallback alle variabili di ambiente: AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY. Per l'autenticazione dell'identità gestita assegnata dall'utente, questa proprietà è obbligatoria. Per il servizio OpenAI (non Azure), impostare la variabile di ambiente OPENAI_API_KEY.
EmbeddingsModel Facoltativo. ID del modello da usare, che per impostazione predefinita è text-embedding-ada-002. Non è consigliabile modificare il modello per un database esistente. Per altre informazioni, vedere Utilizzo.
MaxChunkLength Facoltativo. Numero massimo di caratteri utilizzati per la suddivisione in blocchi dell'input. Per altre informazioni, vedere Utilizzo.
MaxOverlap Facoltativo. Ottiene o imposta il numero massimo di caratteri da sovrapporre tra blocchi.
InputType Facoltativo. Ottiene il tipo dell'input.
StoreConnectionName Nome di un'impostazione dell'app o di una variabile di ambiente che contiene il valore della stringa di connessione. Questa proprietà supporta le espressioni di associazione.
Raccolta Nome della raccolta, della tabella o dell'indice da cercare. Questa proprietà supporta le espressioni di associazione.

Annotazioni

L'annotazione EmbeddingsStoreOutput consente di definire un'associazione di output dell'archivio incorporamenti, che supporta questi parametri:

Elemento Descrizione
nome Ottiene o imposta il nome dell'associazione di output.
immissione Stringa di input per cui generare incorporamenti.
aiConnectionName Facoltativo. Ottiene o imposta il nome della sezione di configurazione per le impostazioni di connettività del servizio di intelligenza artificiale. Per Azure OpenAI: se specificato, cerca i valori "Endpoint" e "Key" in questa sezione di configurazione. Se non specificato o la sezione non esiste, esegue il fallback alle variabili di ambiente: AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY. Per l'autenticazione dell'identità gestita assegnata dall'utente, questa proprietà è obbligatoria. Per il servizio OpenAI (non Azure), impostare la variabile di ambiente OPENAI_API_KEY.
embeddingsModel Facoltativo. ID del modello da usare, che per impostazione predefinita è text-embedding-ada-002. Non è consigliabile modificare il modello per un database esistente. Per altre informazioni, vedere Utilizzo.
maxChunkLength Facoltativo. Numero massimo di caratteri utilizzati per la suddivisione in blocchi dell'input. Per altre informazioni, vedere Utilizzo.
maxOverlap Facoltativo. Ottiene o imposta il numero massimo di caratteri da sovrapporre tra blocchi.
inputType Facoltativo. Ottiene il tipo dell'input.
storeConnectionName Nome di un'impostazione dell'app o di una variabile di ambiente che contiene il valore della stringa di connessione. Questa proprietà supporta le espressioni di associazione.
raccolta Nome della raccolta, della tabella o dell'indice da cercare. Questa proprietà supporta le espressioni di associazione.

Elementi Decorator

Durante l'anteprima, definire l'associazione di output come associazione generic_output_binding di tipo semanticSearch, che supporta questi parametri:

Parametro Descrizione
arg_name Nome della variabile che rappresenta il parametro di associazione.
immissione Stringa di input per cui generare incorporamenti.
ai_connection_name Facoltativo. Ottiene o imposta il nome della sezione di configurazione per le impostazioni di connettività del servizio di intelligenza artificiale. Per Azure OpenAI: se specificato, cerca i valori "Endpoint" e "Key" in questa sezione di configurazione. Se non specificato o la sezione non esiste, esegue il fallback alle variabili di ambiente: AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY. Per l'autenticazione dell'identità gestita assegnata dall'utente, questa proprietà è obbligatoria. Per il servizio OpenAI (non Azure), impostare la variabile di ambiente OPENAI_API_KEY.
embeddings_model Facoltativo. ID del modello da usare, che per impostazione predefinita è text-embedding-ada-002. Non è consigliabile modificare il modello per un database esistente. Per altre informazioni, vedere Utilizzo.
maxChunkLength Facoltativo. Numero massimo di caratteri utilizzati per la suddivisione in blocchi dell'input. Per altre informazioni, vedere Utilizzo.
max_overlap Facoltativo. Ottiene o imposta il numero massimo di caratteri da sovrapporre tra blocchi.
input_type Ottiene il tipo dell'input.
store_connection_name Nome di un'impostazione dell'app o di una variabile di ambiente che contiene il valore della stringa di connessione. Questa proprietà supporta le espressioni di associazione.
raccolta Nome della raccolta, della tabella o dell'indice da cercare. Questa proprietà supporta le espressioni di associazione.

Impostazione

L'associazione supporta queste proprietà di configurazione impostate nel file function.json.

Proprietà Descrizione
tipo Deve essere embeddingsStore.
direzione Deve essere out.
nome Nome dell'associazione di output.
immissione Stringa di input per cui generare incorporamenti.
aiConnectionName Facoltativo. Ottiene o imposta il nome della sezione di configurazione per le impostazioni di connettività del servizio di intelligenza artificiale. Per Azure OpenAI: se specificato, cerca i valori "Endpoint" e "Key" in questa sezione di configurazione. Se non specificato o la sezione non esiste, esegue il fallback alle variabili di ambiente: AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY. Per l'autenticazione dell'identità gestita assegnata dall'utente, questa proprietà è obbligatoria. Per il servizio OpenAI (non Azure), impostare la variabile di ambiente OPENAI_API_KEY.
embeddingsModel Facoltativo. ID del modello da usare, che per impostazione predefinita è text-embedding-ada-002. Non è consigliabile modificare il modello per un database esistente. Per altre informazioni, vedere Utilizzo.
maxChunkLength Facoltativo. Numero massimo di caratteri utilizzati per la suddivisione in blocchi dell'input. Per altre informazioni, vedere Utilizzo.
maxOverlap Facoltativo. Ottiene o imposta il numero massimo di caratteri da sovrapporre tra blocchi.
inputType Facoltativo. Ottiene il tipo dell'input.
storeConnectionName Nome di un'impostazione dell'app o di una variabile di ambiente che contiene il valore della stringa di connessione. Questa proprietà supporta le espressioni di associazione.
raccolta Nome della raccolta, della tabella o dell'indice da cercare. Questa proprietà supporta le espressioni di associazione.

Impostazione

Il binding supporta queste proprietà, definite nel codice:

Proprietà Descrizione
immissione Stringa di input per cui generare incorporamenti.
aiConnectionName Facoltativo. Ottiene o imposta il nome della sezione di configurazione per le impostazioni di connettività del servizio di intelligenza artificiale. Per Azure OpenAI: se specificato, cerca i valori "Endpoint" e "Key" in questa sezione di configurazione. Se non specificato o la sezione non esiste, esegue il fallback alle variabili di ambiente: AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY. Per l'autenticazione dell'identità gestita assegnata dall'utente, questa proprietà è obbligatoria. Per il servizio OpenAI (non Azure), impostare la variabile di ambiente OPENAI_API_KEY.
embeddingsModel Facoltativo. ID del modello da usare, che per impostazione predefinita è text-embedding-ada-002. Non è consigliabile modificare il modello per un database esistente. Per altre informazioni, vedere Utilizzo.
maxChunkLength Facoltativo. Numero massimo di caratteri utilizzati per la suddivisione in blocchi dell'input. Per altre informazioni, vedere Utilizzo.
maxOverlap Facoltativo. Ottiene o imposta il numero massimo di caratteri da sovrapporre tra blocchi.
inputType Facoltativo. Ottiene il tipo dell'input.
storeConnectionName Nome di un'impostazione dell'app o di una variabile di ambiente che contiene il valore della stringa di connessione. Questa proprietà supporta le espressioni di associazione.
raccolta Nome della raccolta, della tabella o dell'indice da cercare. Questa proprietà supporta le espressioni di associazione.

Utilizzo

Per esempi completi, vedere la sezione di esempio.

Connections

Per utilizzare l'estensione di binding Azure OpenAI, è necessario specificare una connessione a una definizione di modello OpenAI. Imposta la connessione del modello OpenAI nei tuoi bindings usando uno di questi approcci:

  • Usa la AIConnectionName proprietà binding (preferita per Azure OpenAI).
  • Imposta AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_KEY nelle impostazioni dell'app (per Azure OpenAI).
  • Imposta solo Open_API_Key nelle impostazioni dell'app (per https://api.openai.com).

Il modo in cui si imposta la connessione dipende sia dall'API del modello sia dal metodo di autenticazione, come indicato dalla seguente tabella:

API di autenticazione/modello Azure OpenAI OpenAI (https://api.openai.com)
Connessione di identità gestita AIConnectionName Non supportato
Riferimento Key Vault AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY		 Open_API_Key
Riferimento alla configurazione dell'app AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY		 Open_API_Key
Segreto condiviso AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY		 Open_API_Key

Usa connessioni gestite basate sull'identità e la AIConnectionName proprietà.

Quando si usa AIConnectionName, il valore di questa impostazione di proprietà dipende dal tipo di connessione:

  • Connessione di identità gestita: La AIConnectionName proprietà è <CONNECTION_NAME_PREFIX> condivisa da un gruppo di impostazioni che insieme definiscono una connessione basata sull'identità con Azure OpenAI. Per ulteriori informazioni, vedi Definire connessioni identitari.
  • Riferimento Key Vault: L'impostazione AIConnectionName della proprietà restituisce un riferimento Azure Key Vault alla posizione in cui la chiave API è mantenuta centralmente. Per maggiori informazioni, vedi Definire le connessioni Key Vault.
  • Riferimento App Configuration: L'impostazione AIConnectionName della proprietà restituisce un riferimento Configurazione app di Azure che restituisce una chiave API o un riferimento a Key Vault. Per ulteriori informazioni, consulta Configurazione app di Azure nell'articolo sulle connessioni.
  • Chiave API: L'impostazione AIConnectionName della proprietà si risolve nelle impostazioni dell'app che contengono direttamente l'endpoint e la chiave. Poiché le chiavi condivise possono essere compromesse, usa le connessioni di identità gestite quando possibile. Per maggiori informazioni, vedi Definisci le connessioni.

Per saperne di più sulle connessioni dei binding, consulta Manage connections in Funzioni di Azure.

I bindings di OpenAI includono una AIConnectionName proprietà che puoi usare per specificare <ConnectionNamePrefix> il gruppo di impostazioni dell'app che definiscono la connessione ad Azure OpenAI:

Nome della impostazione Descrizione
<CONNECTION_NAME_PREFIX>__endpoint Imposta l'endpoint URI del servizio Azure OpenAI. Questa impostazione è sempre obbligatoria.
<CONNECTION_NAME_PREFIX>__clientId Imposta l'identità assegnata dall'utente specifica da usare per ottenere un token di accesso. Richiede che <CONNECTION_NAME_PREFIX>__credential sia impostato su managedidentity. La proprietà accetta un ID client corrispondente a un'identità assegnata dall'utente assegnata all'applicazione. Non è valido specificare sia un ID risorsa che un ID client. Se non specifichi questa proprietà, viene utilizzata l'identità assegnata dal sistema. Questa proprietà viene usata in modo diverso in scenari di sviluppo locale, quando non è consigliabile impostare credential.
<CONNECTION_NAME_PREFIX>__credential Definisce il modo in cui viene ottenuto un token access per la connessione. Usare managedidentity per l'autenticazione dell'identità gestita. Questo valore è valido solo quando un'identità gestita è disponibile nell'ambiente di hosting.
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId Quando credential è impostato su managedidentity, imposta questa proprietà per specificare l'Identificatore della risorsa da utilizzare quando si ottiene un token. La proprietà accetta un identificatore di risorsa corrispondente all'ID risorsa dell'identità gestita definita dall'utente. Non è valido specificare sia un ID risorsa che un ID client. Se non specifichi nessuno dei due, viene utilizzata l'identità assegnata dal sistema. Questa proprietà viene usata in modo diverso in scenari di sviluppo locale, quando non è consigliabile impostare credential.
<CONNECTION_NAME_PREFIX>__key Imposta la chiave segreta condivisa necessaria per accedere all'endpoint del servizio Azure OpenAI utilizzando l'autenticazione basata su chiavi. Come buona pratica di sicurezza, usa sempre Microsoft Entra ID con identità gestite per l'autenticazione.

Considera queste impostazioni di connessione di identità gestita quando imposti la AIConnectionName proprietà su myAzureOpenAI:

  • myAzureOpenAI__endpoint=https://contoso.openai.azure.com/
  • myAzureOpenAI__credential=managedidentity
  • myAzureOpenAI__clientId=aaaaaaaa-bbbb-cccc-1111-222222222222

Durante l'esecuzione, l'host interpreta queste impostazioni come un'unica myAzureOpenAI impostazione:

"myAzureOpenAI":
{
    "endpoint": "https://contoso.openai.azure.com/",
    "credential": "managedidentity",
    "clientId": "aaaaaaaa-bbbb-cccc-1111-222222222222"
}

Quando usi le identità gestite, assicurati di aggiungere la tua identità al ruolo Cognitive Services OpenAI User .

Quando si esegue in località, aggiungi queste impostazioni al filelocal.settings.json progetto. Per altre informazioni, vedere Sviluppo locale con connessioni basate su identità.

Per altre informazioni, vedere Work with application settings.For more information, see Work with application settings.

Contenuto correlato

  • Last updated on