Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować się zalogować lub zmienić katalog.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Zasób foundry zapewnia ujednolicony dostęp do modeli, agentów i narzędzi. W tym artykule wyjaśniono, który zestaw SDK i punkt końcowy mają być używane w danym scenariuszu.
| SDK | Do czego to służy | Endpoint |
|---|---|---|
| Foundry SDK | Funkcje specyficzne dla rozwiązania Foundry z interfejsami zgodnymi z technologią OpenAI. Obejmuje dostęp do modeli bezpośrednich Foundry za pośrednictwem interfejsu API Odpowiedzi (nie Uzupełniania Czatu). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Najnowsze modele i funkcje zestawu OpenAI SDK z pełną powierzchnią interfejsu API openAI. Modele bezpośrednie Foundry dostępne za pośrednictwem interfejsu API dopełniania rozmów (nie przez odpowiedzi). | https://<resource-name>.openai.azure.com/openai/v1 |
| Zestawy SDK narzędzi Foundry | Wstępnie utworzone rozwiązania (Rozpoznawanie wizji, Rozpoznawanie mowy, Bezpieczeństwo treści i inne). | Punkty końcowe specyficzne dla narzędzi (różnią się w zależności od usługi). |
| Struktura agenta | Koordynacja wielu agentów w kodzie. Niezależne od chmury. | Używa punktu końcowego projektu z użyciem Foundry SDK. |
Wybierz zestaw SDK:
- Używanie zestawu SDK usługi Foundry podczas kompilowania aplikacji z agentami, ocenami lub funkcjami specyficznymi dla rozwiązania Foundry
- Używaj OpenAI SDK , gdy wymagana jest maksymalna zgodność z OpenAI lub korzystając z modeli bezpośrednich Foundry przez funkcję Chat Completions
- Używanie zestawów SDK narzędzi Foundry podczas pracy z określonymi usługami sztucznej inteligencji (przetwarzanie obrazów, mowa, język itp.)
- Używanie struktury agentów podczas kompilowania systemów z wieloma agentami w kodzie (lokalna aranżacja)
Uwaga / Notatka
Typy zasobów: Zasób foundry zawiera wszystkie punkty końcowe wymienione wcześniej. Zasób usługi Azure OpenAI zapewnia tylko /openai/v1 punkt końcowy.
Uwierzytelniania: Przykłady w tym miejscu używają identyfikatora Entra firmy Microsoft (DefaultAzureCredential). Klucze API działają na /openai/v1. Przekaż klucz jako api_key zamiast dostawcy tokenu.
Wymagania wstępne
-
Konto platformy Azure z aktywną subskrypcją. Jeśli go nie masz, utwórz bezpłatne konto platformy Azure, które obejmuje subskrypcję bezpłatnej wersji próbnej.
Aby utworzyć zasoby usługi Foundry i zarządzać nimi, posiadaj jedną z następujących ról RBAC na platformie Azure:
- Użytkownik sztucznej inteligencji platformy Azure (rola z najmniejszymi uprawnieniami na potrzeby programowania)
- Menedżer projektów sztucznej inteligencji platformy Azure (do zarządzania projektami foundry)
- Współautor lub właściciel (w przypadku uprawnień na poziomie subskrypcji)
Aby uzyskać szczegółowe informacje na temat uprawnień poszczególnych ról, zobacz Kontrola dostępu oparta na rolach dla usługi Microsoft Foundry.
Zainstaluj wymagane środowiska uruchomieniowe języka, narzędzia globalne i rozszerzenia programu VS Code zgodnie z opisem w temacie Przygotowywanie środowiska projektowego.
Ważna
Przed rozpoczęciem upewnij się, że środowisko deweloperskie jest gotowe.
Ten artykuł koncentruje się na krokach specyficznych dla scenariusza , takich jak instalacja, uwierzytelnianie i uruchamianie przykładowego kodu zestawu SDK.
Sprawdź wymagania wstępne
Przed kontynuowaniem potwierdź:
- [ ] Subskrypcja platformy Azure jest aktywna:
az account show - [ ] Masz wymaganą rolę RBAC: Sprawdź w witrynie Azure Portal → zasób usługi Foundry → Kontrola dostępu (Zarządzanie dostępem i tożsamościami)
- [ ] Zainstalowane środowisko uruchomieniowe języka:
- Python:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - Java:
java --version(≥11)
- Python:
Foundry SDK
Zestaw SDK rozwiązania Foundry łączy się z pojedynczym punktem końcowym projektu, który zapewnia dostęp do najpopularniejszych funkcji rozwiązania Foundry:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Uwaga / Notatka
Jeśli twoja organizacja używa niestandardowej poddomeny, zastąp ciąg <resource-name> ciągiem <your-custom-subdomain> w adresie URL punktu końcowego.
Takie podejście upraszcza konfigurację aplikacji. Zamiast zarządzać wieloma punktami końcowymi, należy je skonfigurować.
Zainstaluj zestaw SDK
Uwaga / Notatka
Wersje zestawu SDK: Zestaw SDK w wersji zapoznawczej 2.x jest przeznaczony dla nowego portalu i interfejsu API rozwiązania Foundry. Zestaw SDK GA w wersji 1.x jest przeznaczony bezpośrednio dla klasycznej wersji Foundry. Upewnij się, że obserwowane przykłady są zgodne z zainstalowanym pakietem.
| Wersja zestawu SDK | Wersja portalu | Status | Pakiet języka Python |
|---|---|---|---|
| 2.x (wersja zapoznawcza) | Odlewnia (nowa) | Preview | azure-ai-projects>=2.0.0b1 --pre |
| 1.x (ogólna dostępność) | Wersja klasyczna usługi Foundry | Stabilny | azure-ai-projects==1.0.0 |
Biblioteka klienta usługi Azure AI Projects dla języka Python to ujednolicona biblioteka umożliwiająca jednoczesne używanie wielu bibliotek klienckich przez połączenie z pojedynczym punktem końcowym projektu.
Uruchom te polecenia, aby zainstalować pakiety w wersji zapoznawczej dla projektów Foundry.
pip install --pre azure-ai-projects
pip install azure-identity openai
| Wersja zestawu SDK | Wersja portalu | Status | Pakiet Java |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 |
Odlewnia (nowa) | Preview | azure-ai-projectsazure-ai-agents |
| Wersja zestawu SDK | Wersja portalu | Status | Pakiet JavaScript |
|---|---|---|---|
| 2.0.0-beta.4 (wersja zapoznawcza) | Odlewnia (nowa) | Preview | @azure/ai-projects 'prerelease' |
| 1.0.1 | Wersja klasyczna usługi Foundry | Stabilny | @azure/ai-projects |
| Wersja zestawu SDK | Wersja portalu | Status | Pakiet .NET |
|---|---|---|---|
| 1.2.0-beta.5 (wersja zapoznawcza) | Odlewnia (nowa) | Preview | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (ogólna dostępność) | Wersja klasyczna usługi Foundry | Stabilny | Azure.AI.Projects |
Biblioteka klienta usługi Azure AI Projects dla języka Java (wersja zapoznawcza) to ujednolicona biblioteka, która umożliwia jednoczesne używanie wielu bibliotek klienckich przez połączenie z pojedynczym punktem końcowym projektu.
Ważna
Elementy oznaczone jako (wersja zapoznawcza) w tym artykule są aktualnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.
Dodaj te pakiety do instalacji dla projektów Foundry.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
Biblioteka kliencka usługi Azure AI Projects dla języka JavaScript to ujednolicona biblioteka, która umożliwia jednoczesne używanie wielu bibliotek klienckich przez połączenie z pojedynczym punktem końcowym projektu.
Uruchom to polecenie, aby zainstalować pakiety JavaScript w wersji zapoznawczej dla projektów foundry.
npm install @azure/ai-projects@beta @azure/identity dotenv
Biblioteka klienta usługi Azure AI Projects dla platformy .NET to ujednolicona biblioteka, która umożliwia używanie wielu bibliotek klienckich razem przez nawiązanie połączenia z jednym punktem końcowym projektu.
Uruchom to polecenie, aby dodać pakiet Azure.AI.Projects do projektu platformy .NET.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
Korzystanie z zestawu SDK usługi Foundry
Zestaw SDK uwidacznia dwa typy klientów, ponieważ narzędzia Foundry i OpenAI mają różne kształty interfejsu API:
- Klient projektu — służy do operacji natywnych dla platformy Foundry, w których interfejs OpenAI nie ma odpowiednika. Przykłady: wyświetlanie listy połączeń, pobieranie właściwości projektu, włączanie śledzenia.
-
Klient zgodny z interfejsem OpenAI — służy do obsługi funkcji rozwiązania Foundry, która opiera się na pojęciach dotyczących interfejsu OpenAI. Interfejs API odpowiedzi, agenci, oceny i dostrajanie używają wzorców żądań/odpowiedzi według wzorców OpenAI. Ten klient zapewnia również dostęp do bezpośrednich modeli Foundry (modeli innych niż Azure-OpenAI hostowanych w Foundry). Punkt końcowy projektu obsługuje ten ruch na
/openaitrasie.
Większość aplikacji używa obu klientów. Użyj klienta projektu do instalacji i konfiguracji, a następnie skorzystaj z klienta kompatybilnego z OpenAI do uruchamiania agentów, ocen oraz wywoływania modeli (w tym bezpośrednich modeli Foundry).
Utwórz klienta projektu:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
Utwórz klienta zgodnego z platformą OpenAI na podstawie projektu:
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
Oczekiwane dane wyjściowe:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Utwórz klienta projektu:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Utwórz klienta projektu:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
Utwórz klienta zgodnego z platformą OpenAI na podstawie projektu:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Utwórz klienta projektu:
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI.Responses;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
Utwórz klienta zgodnego z platformą OpenAI na podstawie projektu:
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001
Co można zrobić za pomocą zestawu SDK usługi Foundry
- Modele odnajdowania dostępu, w tym Azure OpenAI
- Korzystanie z usługi agenta programu Foundry
- Uruchamianie ocen w chmurze
- Włączanie śledzenia aplikacji
- Dostrajanie modelu
- Uzyskiwanie punktów końcowych i kluczy dla narzędzi Foundry, lokalnej orkiestracji i nie tylko
Rozwiązywanie problemów
Błędy uwierzytelniania
Jeśli widzisz DefaultAzureCredential failed to retrieve a token:
Sprawdź, czy interfejs wiersza polecenia platformy Azure jest uwierzytelniony:
az account show az login # if not logged inSprawdź przypisanie roli RBAC:
- Upewnij się, że masz co najmniej rolę użytkownika sztucznej inteligencji platformy Azure w projekcie Foundry
- Zobacz Przypisywanie ról platformy Azure
W przypadku tożsamości zarządzanej w środowisku produkcyjnym:
- Upewnij się, że tożsamość zarządzana ma przypisaną odpowiednią rolę
- Zobacz Konfigurowanie tożsamości zarządzanych
Błędy konfiguracji punktu końcowego
Jeśli widzisz wartość Connection refused lub 404 Not Found:
- Sprawdzanie, czy nazwy zasobów i projektów są zgodne z rzeczywistym wdrożeniem
-
Sprawdź format adresu URL punktu końcowego: powinien mieć wartość
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
W przypadku domen podrzędnych niestandardowych: zastąp
<resource-name>element niestandardową poddomeną
Niezgodność wersji zestawu SDK
Jeśli przykłady kodu kończą się niepowodzeniem z błędem AttributeError lub ModuleNotFoundError:
-
Sprawdź wersję zestawu SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NET - Sprawdź dopasowanie nazwy: SDK 2.x wymaga portalu Foundry, SDK 1.x wymaga Foundry w wersji klasycznej.
- Zainstaluj ponownie z poprawnymi flagami wersji: Zobacz polecenia instalacji w każdej sekcji języka powyżej
OpenAI SDK
Użyj zestawu OpenAI SDK, jeśli chcesz uzyskać pełną powierzchnię interfejsu API OpenAI i maksymalną zgodność klienta. Ten punkt końcowy zapewnia dostęp do modeli usługi Azure OpenAI i modeli bezpośrednich rozwiązania Foundry (za pośrednictwem interfejsu API odpowiedzi). Nie zapewnia dostępu do funkcji specyficznych dla rozwiązania Foundry, takich jak agenci i oceny.
Poniższy fragment kodu pokazuje, jak bezpośrednio używać punktu końcowego usługi Azure OpenAI /openai/v1 .
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)
client = OpenAI(
base_url = "https://<resource-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
Oczekiwane dane wyjściowe:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
Aby uzyskać więcej informacji, zobacz Języki programowania obsługiwane przez usługę Azure OpenAI
Ważna
Elementy oznaczone jako (wersja zapoznawcza) w tym artykule są aktualnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.
Poniższy fragment kodu pokazuje, jak bezpośrednio używać punktu końcowego usługi Azure OpenAI /openai/v1 .
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://cognitiveservices.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
Aby uzyskać więcej informacji na temat korzystania z zestawu OpenAI SDK, zobacz Języki programowania obsługiwane przez usługę Azure OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Aby uzyskać więcej informacji na temat korzystania z zestawu OpenAI SDK, zobacz Języki programowania obsługiwane przez usługę Azure OpenAI
- Zainstaluj pakiet OpenAI: uruchom to polecenie, aby dodać bibliotekę klienta OpenAI do projektu platformy .NET.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ResponseClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using Azure.Core; using OpenAI; using System; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"); OpenAIResponseClient client = new( model: deploymentName, authenticationPolicy: tokenPolicy, // To use Entra // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponseCreationOptions options = new ResponseCreationOptions { Temperature = (float)0.7, }; OpenAIResponse modelDirectResponse = client.CreateResponse( [ ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"), ], options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}"); #pragma warning restore OPENAI001 // The ResponseClient lets you interact with models and services in your project.
Aby uzyskać więcej informacji na temat korzystania z zestawu OpenAI SDK, zobacz Języki programowania obsługiwane przez usługę Azure OpenAI
Używanie Agent Framework do orkiestracji lokalnej
Microsoft Agent Framework to zestaw SDK typu open source do tworzenia systemów wieloagentowych w kodzie (na przykład .NET i Python) z interfejsem niezależnym od dostawcy chmury.
Użyj struktury agentów, jeśli chcesz definiować i organizować agentów lokalnie. Połącz go z Foundry SDK, jeśli chcesz, aby ci agenci działali na modelach Foundry, lub gdy chcesz, aby Agent Framework koordynował agentów hostowanych w Foundry.
Aby uzyskać więcej informacji, zobacz Omówienie programu Microsoft Agent Framework.
Zestawy SDK narzędzi Foundry
Narzędzia Foundry Tools (dawniej Azure AI Services) to wstępnie utworzone rozwiązania punktowe z dedykowanymi zestawami SDK. Użyj następujących punktów końcowych, aby korzystać z narzędzi Foundry.
Którego punktu końcowego należy użyć?
Wybierz punkt końcowy w zależności od potrzeb:
Użyj punktu końcowego usług Azure AI, aby uzyskać dostęp do narzędzi przetwarzania obrazów, bezpieczeństwa zawartości, analizy dokumentów, języka, tłumaczenia i tokenów.
Adres końcowy narzędzi Foundry: https://<your-resource-name>.cognitiveservices.azure.com/
Uwaga / Notatka
Punkty końcowe używają nazwy zasobu lub niestandardowej poddomeny. Jeśli twoja organizacja skonfiguruje niestandardową poddomenę, zastąp ciąg your-resource-name we your-custom-subdomain wszystkich przykładach punktów końcowych.
W przypadku narzędzi usługi Speech and Translation Foundry użyj punktów końcowych w poniższych tabelach. Zastąp elementy zastępcze informacjami o zasobie.
Punkty końcowe mowy
| Narzędzie Foundry | Endpoint |
|---|---|
| Zamiana mowy na tekst (Standardowa) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Przekształcanie tekstu na mowę (neuronowe) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| głos niestandardowy | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Punkty końcowe tłumaczenia
| Narzędzie Foundry | Endpoint |
|---|---|
| Tłumaczenie tekstu | https://api.cognitive.microsofttranslator.com/ |
| Tłumaczenie dokumentu | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
W poniższych sekcjach znajdują się linki szybkiego startu dla zestawów SDK narzędzi Foundry i informacje referencyjne.
