Associazione di input di ricerca semantica OpenAI di Azure per Funzioni di Azure

Importante

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

L'associazione di input di ricerca semantica OpenAI di Azure consente di usare la ricerca semantica negli incorporamenti.

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.

Annotazioni

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

Annotazioni

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

Annotazioni

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.

In questo esempio viene illustrato come eseguire una ricerca semantica in un file.

[Function("PromptFile")]
public static IActionResult PromptFile(
    [HttpTrigger(AuthorizationLevel.Function, "post")] SemanticSearchRequest unused,
    [SemanticSearchInput("AISearchEndpoint", "openai-index", Query = "{prompt}", ChatModel = "%CHAT_MODEL_DEPLOYMENT_NAME%", EmbeddingsModel = "%EMBEDDING_MODEL_DEPLOYMENT_NAME%", AIConnectionName = "AzureOpenAI")] SemanticSearchContext result)
{
    return new ContentResult { Content = result.Response, ContentType = "text/plain" };
}

In questo esempio viene illustrato come eseguire una ricerca semantica in un file.

@FunctionName("PromptFile")
public HttpResponseMessage promptFile(
    @HttpTrigger(
        name = "req", 
        methods = {HttpMethod.POST},
        authLevel = AuthorizationLevel.FUNCTION)
        HttpRequestMessage<SemanticSearchRequest> request,
    @SemanticSearch(name = "search", searchConnectionName = "AISearchEndpoint", collection = "openai-index", query = "{prompt}", chatModel = "%CHAT_MODEL_DEPLOYMENT_NAME%", embeddingsModel = "%EMBEDDING_MODEL_DEPLOYMENT_NAME%", isReasoningModel = false, aiConnectionName = "AzureOpenAI" ) String semanticSearchContext,
    final ExecutionContext context) {
        String response = new JSONObject(semanticSearchContext).getString("Response");
        return request.createResponseBuilder(HttpStatus.OK)
        .header("Content-Type", "application/json")
        .body(response)
        .build();        
}
public class SemanticSearchRequest {
    public String prompt;
    public String getPrompt() {
        return prompt;
    }
    public void setPrompt(String prompt) {
        this.prompt = prompt;
    }        
}

In questo esempio viene illustrato come eseguire una ricerca semantica in un file.

const semanticSearchInput = input.generic({
    type: "semanticSearch",
    searchConnectionName: "AISearchEndpoint",
    collection: "openai-index",
    query: "{prompt}",
    chatModel: "%CHAT_MODEL_DEPLOYMENT_NAME%",
    embeddingsModel: "%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    aiConnectionName: 'AzureOpenAI',
});

app.http('PromptFile', {
    methods: ['POST'],
    authLevel: 'function',
    extraInputs: [semanticSearchInput],
    handler: async (_request, context) => {
        var responseBody = context.extraInputs.get(semanticSearchInput)

        return { status: 200, body: responseBody.Response.trim() }
    }
});
const semanticSearchInput = input.generic({
    type: "semanticSearch",
    searchConnectionName: "AISearchEndpoint",
    collection: "openai-index",
    query: "{prompt}",
    chatModel: "%CHAT_MODEL_DEPLOYMENT_NAME%",
    aiConnectionName: 'AzureOpenAI',
    embeddingsModel: "%EMBEDDING_MODEL_DEPLOYMENT_NAME%"
});

app.http('PromptFile', {
    methods: ['POST'],
    authLevel: 'function',
    extraInputs: [semanticSearchInput],
    handler: async (_request, context) => {
        var responseBody: any = context.extraInputs.get(semanticSearchInput)

        return { status: 200, body: responseBody.Response.trim() }
    }
});

In questo esempio viene illustrato come eseguire una ricerca semantica in un file.

Ecco il filefunction.json per richiedere un file:

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "name": "SemanticSearchInput",
      "type": "semanticSearch",
      "direction": "in",
      "searchConnectionName": "AISearchEndpoint",
      "collection": "openai-index",
      "query": "{prompt}",
      "chatModel": "%CHAT_MODEL_DEPLOYMENT_NAME%",
      "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, $SemanticSearchInput)

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
        StatusCode = [HttpStatusCode]::OK
        Body       = $SemanticSearchInput.Response
    })

In questo esempio viene illustrato come eseguire una ricerca semantica in un file.

@app.function_name("PromptFile")
@app.route(methods=["POST"])
@app.semantic_search_input(
    arg_name="result",
    search_connection_name="AISearchEndpoint",
    collection="openai-index",
    query="{prompt}",
    embeddings_model="%EMBEDDING_MODEL_DEPLOYMENT_NAME%",
    ai_connection_name="AzureOpenAI",
    chat_model="%CHAT_MODEL_DEPLOYMENT_NAME%",
)
def prompt_file(req: func.HttpRequest, result: str) -> func.HttpResponse:
    result_json = json.loads(result)
    response_json = {
        "content": result_json.get("Response"),
        "content_type": "text/plain",
    }
    return func.HttpResponse(
        json.dumps(response_json), status_code=200, mimetype="application/json"
    )

Attributi

Applicare l'attributo per definire un'associazione SemanticSearchInput di input di ricerca semantica, che supporta questi parametri:

Parametro Descrizione
SearchConnectionName 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.
Quesito Testo della query semantica da usare per la ricerca. Questa proprietà supporta le espressioni di associazione.
EmbeddingsModel Facoltativo. ID del modello da usare per gli incorporamenti. Il valore predefinito è text-embedding-3-small. Questa proprietà supporta le espressioni di associazione.
ChatModel Facoltativo. Ottiene o imposta il nome del modello linguistico Large da richiamare per le risposte di chat. Il valore predefinito è gpt-3.5-turbo. Questa proprietà supporta le espressioni di associazione.
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.
SystemPrompt Facoltativo. Ottiene o imposta il prompt di sistema da utilizzare per richiedere il modello linguistico di grandi dimensioni. Il prompt di sistema viene aggiunto con le informazioni recuperate in seguito a Query. Il prompt combinato viene inviato all'API Chat OpenAI. Questa proprietà supporta le espressioni di associazione.
MaxKnowledgeCount Facoltativo. Ottiene o imposta il numero di elementi di knowledge base da inserire nell'oggetto SystemPrompt.
IsReasoningModel Facoltativo. Ottiene o imposta un valore che indica se il modello di completamento della chat è un modello di ragionamento. Questa opzione è sperimentale e associata al modello di ragionamento fino a quando tutti i modelli non hanno parità nelle proprietà previste, con un valore predefinito di false.

Annotazioni

L'annotazione SemanticSearchInput consente di definire un'associazione di input di ricerca semantica, che supporta questi parametri:

Elemento Descrizione
nome Ottiene o imposta il nome del binding di input.
searchConnectionName 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.
quesito Testo della query semantica da usare per la ricerca. Questa proprietà supporta le espressioni di associazione.
embeddingsModel Facoltativo. ID del modello da usare per gli incorporamenti. Il valore predefinito è text-embedding-3-small. Questa proprietà supporta le espressioni di associazione.
chatModel Facoltativo. Ottiene o imposta il nome del modello linguistico Large da richiamare per le risposte di chat. Il valore predefinito è gpt-3.5-turbo. Questa proprietà supporta le espressioni di associazione.
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.
systemPrompt Facoltativo. Ottiene o imposta il prompt di sistema da utilizzare per richiedere il modello linguistico di grandi dimensioni. Il prompt di sistema viene aggiunto con le informazioni recuperate in seguito a Query. Il prompt combinato viene inviato all'API Chat OpenAI. Questa proprietà supporta le espressioni di associazione.
maxKnowledgeCount Facoltativo. Ottiene o imposta il numero di elementi di knowledge base da inserire nell'oggetto SystemPrompt.
isReasoningModel Facoltativo. Ottiene o imposta un valore che indica se il modello di completamento della chat è un modello di ragionamento. Questa opzione è sperimentale e associata al modello di ragionamento fino a quando tutti i modelli non hanno parità nelle proprietà previste, con un valore predefinito di false.

Elementi Decorator

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

Parametro Descrizione
arg_name Nome della variabile che rappresenta il parametro di associazione.
search_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.
quesito Testo della query semantica da usare per la ricerca. Questa proprietà supporta le espressioni di associazione.
embeddings_model Facoltativo. ID del modello da usare per gli incorporamenti. Il valore predefinito è text-embedding-3-small. Questa proprietà supporta le espressioni di associazione.
chat_model Facoltativo. Ottiene o imposta il nome del modello linguistico Large da richiamare per le risposte di chat. Il valore predefinito è gpt-3.5-turbo. Questa proprietà supporta le espressioni di associazione.
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.
system_prompt Facoltativo. Ottiene o imposta il prompt di sistema da utilizzare per richiedere il modello linguistico di grandi dimensioni. Il prompt di sistema viene aggiunto con le informazioni recuperate in seguito a Query. Il prompt combinato viene inviato all'API Chat OpenAI. Questa proprietà supporta le espressioni di associazione.
max_knowledge_count Facoltativo. Ottiene o imposta il numero di elementi di knowledge base da inserire nell'oggetto SystemPrompt.
is_reasoning _model Facoltativo. Ottiene o imposta un valore che indica se il modello di completamento della chat è un modello di ragionamento. Questa opzione è sperimentale e associata al modello di ragionamento fino a quando tutti i modelli non hanno parità nelle proprietà previste, con un valore predefinito di false.

Configurazione

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

Proprietà Descrizione
tipo Deve essere semanticSearch.
direzione Deve essere in.
nome Nome dell'associazione di input.
searchConnectionName Ottiene o imposta il nome di un'impostazione dell'app o di una variabile di ambiente che contiene un 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.
quesito Testo della query semantica da usare per la ricerca. Questa proprietà supporta le espressioni di associazione.
embeddingsModel Facoltativo. ID del modello da usare per gli incorporamenti. Il valore predefinito è text-embedding-3-small. Questa proprietà supporta le espressioni di associazione.
chatModel Facoltativo. Ottiene o imposta il nome del modello linguistico Large da richiamare per le risposte di chat. Il valore predefinito è gpt-3.5-turbo. Questa proprietà supporta le espressioni di associazione.
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.
systemPrompt Facoltativo. Ottiene o imposta il prompt di sistema da utilizzare per richiedere il modello linguistico di grandi dimensioni. Il prompt di sistema viene aggiunto con le informazioni recuperate in seguito a Query. Il prompt combinato viene inviato all'API Chat OpenAI. Questa proprietà supporta le espressioni di associazione.
maxKnowledgeCount Facoltativo. Ottiene o imposta il numero di elementi di knowledge base da inserire nell'oggetto SystemPrompt.
isReasoningModel Facoltativo. Ottiene o imposta un valore che indica se il modello di completamento della chat è un modello di ragionamento. Questa opzione è sperimentale e associata al modello di ragionamento fino a quando tutti i modelli non hanno parità nelle proprietà previste, con un valore predefinito di false.

Configurazione

Il binding supporta queste proprietà, definite nel codice:

Proprietà Descrizione
searchConnectionName 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.
quesito Testo della query semantica da usare per la ricerca. Questa proprietà supporta le espressioni di associazione.
embeddingsModel Facoltativo. ID del modello da usare per gli incorporamenti. Il valore predefinito è text-embedding-3-small. Questa proprietà supporta le espressioni di associazione.
chatModel Facoltativo. Ottiene o imposta il nome del modello linguistico Large da richiamare per le risposte di chat. Il valore predefinito è gpt-3.5-turbo. Questa proprietà supporta le espressioni di associazione.
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.
systemPrompt Facoltativo. Ottiene o imposta il prompt di sistema da utilizzare per richiedere il modello linguistico di grandi dimensioni. Il prompt di sistema viene aggiunto con le informazioni recuperate in seguito a Query. Il prompt combinato viene inviato all'API Chat OpenAI. Questa proprietà supporta le espressioni di associazione.
maxKnowledgeCount Facoltativo. Ottiene o imposta il numero di elementi di knowledge base da inserire nell'oggetto SystemPrompt.
isReasoningModel Facoltativo. Ottiene o imposta un valore che indica se il modello di completamento della chat è un modello di ragionamento. Questa opzione è sperimentale e associata al modello di ragionamento fino a quando tutti i modelli non hanno parità nelle proprietà previste, con un valore predefinito di false.

Uso

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.