Informazioni di riferimento sul parametro di distribuzione per il recupero agentico in Foundry Local

Questo articolo fornisce informazioni di riferimento sui parametri di configurazione, variabili di ambiente e linee guida per la risoluzione dei problemi per la distribuzione del recupero agentico.

Importante

Il recupero agentico in Foundry Local è attualmente disponibile in ANTEPRIMA. Vedi le Condizioni supplementari d'uso per le anteprime di Microsoft Azure per conoscere le condizioni legali applicabili alle funzionalità di Azure che sono in beta, in anteprima o non ancora rilasciate nella disponibilità generale.

Parametri di configurazione

Quando si installa l'estensione Recupero agentico vengono usati i parametri di configurazione seguenti:

Parametro Obbligatorio Description
byom.enabled Sì Sempre true. BYOM è l'unico percorso del modello linguistico.
byom.apiEndpoint Sì URL endpoint completo. Per Foundry Local: https://gpt-oss-20b.foundry-local-operator.svc.cluster.local:5000/v1/chat/completions. Per Microsoft Foundry: https://<resource>.cognitiveservices.azure.com/openai/deployments/<model>/chat/completions?api-version=<version>.
byom.apiModel Condizionale Non obbligatorio per gli endpoint locali di Foundry. Nome del modello da inviare nelle richieste (ad esempio, gpt-oss-20b).
byom.maxTokensInK Sì Numero massimo di token in migliaia (ad esempio, 16).
foundryClientId Condizionale Obbligatorio solo quando si usa un'origine modello locale Foundry con useFoundryLocal=true. Non obbligatorio per gli endpoint locali non foundry.
auth.tenantId Sì ID del tenant Microsoft Entra ID.
auth.clientId Sì ID client di registrazione di agenti e strumenti dell'app.
isManagedIdentityRequired Sì Sempre true. Abilita l'acquisizione del token di identità gestita.
layerSelection Sì combined, agentic o knowledge.
ingress.domainname Sì Nome DNS completo per l'accesso esterno (ad esempio, mycluster.eastus.cloudapp.azure.com).
gpu_enabled No Impostare su true per i cluster GPU. Abilita i modelli di incorporamento con accelerazione GPU.
min_gpu_nodes No Numero minimo di nodi GPU necessari. Impostazione predefinita: 2.
AgentOperationTimeoutInMinutes No Timeout per le operazioni dell'agente. Impostazione predefinita: 30.
model No Sempre byom. Nessun'altra opzione.
llm.dapr.accessControl.defaultAction No Controllo di accesso dapr. Impostare su allow.
embeddingmodel.image.gpu.repository No Repository di immagini del modello di incorporamento GPU.
embeddingmodel.image.gpu.tag No Tag immagine del modello di incorporamento GPU.

La chiave API BYOM non viene passata come parametro di configurazione. Viene archiviato come segreto Kubernetes (byom-api-key) nello spazio dei nomi prima dell'installazione arc-rag dell'estensione.

Il interfaccia della riga di comando di Azure accetta sia --config che --configuration-settings per i parametri dell'estensione Arc. Entrambe le sintassi sono equivalenti.

Variabili di ambiente

I modelli Helm popolano le variabili di ambiente seguenti per tutti i pod di inferenza:

Variable origine
BYOM_ENABLED Sempre true
BYOM_ENDPOINT byom.apiEndpoint
BYOM_MODEL byom.apiModel
BYOM_API_KEY byom.apiKey
FOUNDRY_CLIENT_ID foundryClientId (se configurata)

Risolvere i problemi di integrazione locale di Foundry

Usare i comandi seguenti per diagnosticare i problemi locali di Foundry:

Command Purpose
kubectl describe mdep <name> Controllare lo stato e gli eventi di ModelDeployment.
kubectl logs -f deployment/inference-operator -n foundry-local-operator Controllare i log degli operatori.
kubectl get pods -l app.kubernetes.io/managed-by=inference-operator Controllare lo stato del pod di inferenza.
kubectl describe pod <pod_name> Ottenere i dettagli e gli eventi del pod.
kubectl get deploy,svc,ing -l foundry.azure.com/deployment=<name> Elencare tutte le risorse create da una distribuzione.
kubectl get configmap foundry-local-catalog -n foundry-local-operator -o yaml Controllare il file ConfigMap del catalogo dei modelli.

Problemi di integrazione comuni

Sintomo Motivo Resolution
Connessione rifiutata o timeout Foundry Local not running or network policy blocking egress .Foundry Local not running or network policy blocking egress. Verificare che i pod Foundry siano in esecuzione. Verificare che sia consentito l'uscita dallo arc-rag spazio dei nomi al traffico in ingresso Foundry.
SSL: CERTIFICATE_VERIFY_FAILED foundryClientId non impostato nella configurazione dell'estensione. Impostata foundryClientId : consente di fissare il montaggio del bundle ca. Senza di esso, il certificato autofirmato Foundry non è attendibile.
400 Bad Request: plain HTTP sent to HTTPS port Uso http:// di https:// anziché in byom.apiEndpoint. Modificare l'endpoint in https://. Foundry Local abilita TLS per impostazione predefinita.
400 Invalid JSON in request body Uso del onnx-genai runtime con agenti o modalità combinata. Passare al vllm runtime. Il onnx-genai runtime non supporta tools o tool_choice parametri.
401 Token validation failed Ruoli controllo degli accessi in base al ruolo non assegnati per l'identità gestita. Assegnare Reader + + Cognitive Services OpenAI UserFoundryInferenceAccess il ruolo dell'app. Vedere Configurare l'autenticazione dell'inferenza locale di Foundry.
401 Entra ID authentication is not enabled Invio di token di identità gestita a Foundry con entraAuth.enabled=false. Abilitare l'autenticazione Microsoft Entra in Foundry oppure deselezionare FOUNDRY_CLIENT_ID in modo che agenti e strumenti usino l'autenticazione della chiave API.
401 Invalid API key Chiave API ruotata dopo la ridistribuzione del modello. Rileggere la chiave dal gpt-oss-20b-api-keys segreto e aggiornare byom-api-key nello spazio dei arc-rag nomi .
404 Not Found da Foundry Modello non distribuito. Eseguire kubectl get mdep -n foundry-local-operator e verificare che il nome del modello corrisponda a byom.apiModel.
Le chiamate LLM hanno esito negativo ma il lavoro di incorporamento e inserimento Comportamento previsto. I modelli di incorporamento sono locali; solo l'inferenza LLM usa Foundry. Controllare lo stato di connettività e distribuzione del modello di Foundry.
L'acquisizione del token di identità gestita ha esito negativo Microsoft Entra ID non raggiungibile o msi-adapter non in esecuzione. Controllare i log sidecar dell'adattatore msi. La richiesta esegue il fallback solo all'autenticazione della chiave API.
Pod in sospeso (risorse insufficienti) Cluster troppo piccolo per la modalità combinata (60+ pod). La modalità combinata richiede almeno 3 nodi di lavoro Standard_D8s_v3 (24 vCPU, 96 GB di RAM) + 1 nodo GPU. Ridimensionare i pool di nodi con az aksarc nodepool scale.
Installazione dell'estensione: webhook nginx non aggiornato L'installazione precedente ha lasciato ValidatingWebhookConfiguration. Eseguire kubectl delete validatingwebhookconfiguration ingress-nginx-admission prima della reinstallazione.

Parametri dell'operatore Foundry Local

È possibile impostare questi parametri facoltativi durante l'installazione dell'operatore di inferenza Foundry:

Parametro Description
entraAuth.enabled Se abilitata, Microsoft Entra SDK di autenticazione e sidecar dell'adattatore msi vengono inseriti in pod di inferenza per la convalida JWT e l'autorizzazione del controllo degli accessi in base al ruolo arm. Se disabilitato tenantId , e clientId sono facoltativi. Impostazione predefinita: true.
watch.namespaces Configurare se l'operatore deve gestire le risorse in più spazi dei nomi. Impostazione predefinita: foundry-local-operator. Passare come: --config watch.namespaces[0]="<namespace_1>" --config watch.namespaces[1]="<namespace_2>".

Gestione delle chiavi locali foundry

È possibile recuperare e ruotare le chiavi API usando il servizio di inferenza locale Foundry:

Punto finale Description
GET /namespaces/<namespace>/deployments/<name>/keys Recuperare sia le chiavi primarie che secondarie.
POST /namespaces/<namespace>/deployments/<name>/keys/{primary\|secondary}/rotate Ruotare una chiave specifica.

Contenuti correlati

  • Last updated on