Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Foundry kaynağı modellere, aracılara ve araç gereçlere birleşik erişim sağlar. Bu makalede senaryonuz için hangi SDK ve uç noktanın kullanılacağı açıklanmaktadır.
| SDK | Ne için? | Bitiş noktası |
|---|---|---|
| Foundry SDK | OpenAI uyumlu arabirimlerle dökümhaneye özgü özellikler. Yanıtlar API'si aracılığıyla (Sohbet Tamamlamaları değil) Foundry'nin doğrudan modellerine erişim içerir. | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK'sı | Tam OpenAI API yüzeyiyle en son OpenAI SDK modelleri ve özellikleri. Dökümhane doğrudan modeller, Sohbet Tamamlama API'si (Yanıtlar değil) aracılığıyla kullanılabilir. | https://<resource-name>.openai.azure.com/openai/v1 |
| Döküm Araçları SDK'ları | Önceden oluşturulmuş çözümler (Görüntü İşleme, Konuşma, İçerik Güvenliği ve daha fazlası). | Araçlara özgü uç noktalar (hizmete göre değişir). |
| Ajanda Çerçevesi | Kodda çok ajanlı orkestrasyon. Buluttan bağımsız. | Döküm SDK'sı aracılığıyla proje uç noktasını kullanır. |
SDK'nızı seçin:
- Aracılar, değerlendirmeler veya Foundry'ye özgü özelliklerle uygulama oluştururken Foundry SDK'sı kullanma
- En yüksek OpenAI uyumluluğu gerektiğinde OpenAI SDK'sı kullanın veya Sohbet Tamamlamaları aracılığıyla Foundry doğrudan modellerini kullanın
- Belirli yapay zeka hizmetleriyle (Görüntü İşleme, Konuşma, Dil vb.) çalışırken Döküm Araçları SDK'larını kullanma
- Kodda çok aracılı sistemler oluştururken Agent Framework kullanma (yerel düzenleme)
Uyarı
Kaynak türleri: Foundry kaynağı, daha önce listelenen tüm uç noktaları sağlar. Azure OpenAI kaynağı yalnızca /openai/v1 uç noktayı sağlar.
Kimlik doğrulama: Buradaki örneklerde Microsoft Entra Id (DefaultAzureCredential kullanılır). API anahtarları /openai/v1 üzerinde çalışır. Anahtarı belirteç sağlayıcısı yerine api_key geçirin.
Önkoşullar
-
Aktif bir aboneliğe sahip bir Azure hesabı. Hesabınız yoksa ücretsiz deneme aboneliği içeren ücretsiz bir Azure hesabı oluşturun.
Foundry kaynaklarını oluşturmak ve yönetmek için aşağıdaki Azure RBAC rollerinden birine sahip olmak:
- Azure AI Kullanıcısı (geliştirme için en az ayrıcalıklı rol)
- Azure AI Proje Yöneticisi (Dökümhane projelerini yönetmek için)
- Katkıda Bulunan veya Sahip (abonelik düzeyinde izinler için)
Her rolün izinleri hakkında ayrıntılı bilgi için bkz. Microsoft Foundry için rol tabanlı erişim denetimi.
Geliştirme ortamınızı hazırlama bölümünde açıklandığı gibi gerekli dil çalışma zamanlarını, genel araçları ve VS Code uzantılarını yükleyin.
Önemli
Başlamadan önce geliştirme ortamınızın hazır olduğundan emin olun.
Bu makalede SDK yüklemesi, kimlik doğrulaması ve örnek kodu çalıştırma gibi senaryoya özgü adımlara odaklanılır.
Önkoşulları doğrulama
Devam etmeden önce şunları onaylayın:
- [ ] Azure aboneliği etkin:
az account show - [ ] Gerekli RBAC rolüne sahipsiniz: Azure portalına gidin → Foundry kaynağı → Erişim denetimi (IAM) kontrol edin
- [ ] Dil çalışma zamanı yüklendi:
- Python:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - Java:
java --version(≥11)
- Python:
Dökümhane SDK'sı
Foundry SDK'sı, en popüler Foundry özelliklerine erişim sağlayan tek bir proje uç noktasına bağlanır:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Uyarı
Kuruluşunuz özel bir alt etki alanı kullanıyorsa, uç nokta URL'sindeki <resource-name> öğesini <your-custom-subdomain> ile değiştirin.
Bu yaklaşım, uygulama yapılandırmasını basitleştirir. Birden çok uç noktayı yönetmek yerine birini yapılandırabilirsiniz.
SDK’yı yükleyin
Uyarı
SDK sürümleri: 2.x önizleme SDK'sı yeni Foundry portalını ve API'yi hedefler. 1.x GA SDK'sı Foundry klasikini hedefler. takip ettiğiniz örneklerin yüklü paketinizle eşleştiğinden emin olun.
| SDK Sürümü | Portal Sürümü | Statü | Python Paketi |
|---|---|---|---|
| 2.x (önizleme) | Dökümhane (yeni) | Önizle | azure-ai-projects>=2.0.0b1 --pre |
| 1.x (GA) | Dökümhane klasik | İstikrarlı | azure-ai-projects==1.0.0 |
Python için Azure AI Projeleri istemci kitaplığı, tek bir proje uç noktasına bağlanarak birden çok istemci kitaplığını birlikte kullanmanızı sağlayan birleşik bir kitaplıktır.
Foundry projelerinin önizleme paketlerini yüklemek için bu komutları çalıştırın.
pip install --pre azure-ai-projects
pip install azure-identity openai
| SDK Sürümü | Portal Sürümü | Statü | Java Paketi |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 |
Dökümhane (yeni) | Önizle | azure-ai-projectsazure-ai-agents |
| SDK Sürümü | Portal Sürümü | Statü | JavaScript Paketi |
|---|---|---|---|
| 2.0.0-beta.4 (önizleme) | Dökümhane (yeni) | Önizle | @azure/ai-projects 'prerelease' |
| 1.0.1 | Dökümhane klasik | İstikrarlı | @azure/ai-projects |
| SDK Sürümü | Portal Sürümü | Statü | .NET Paketi |
|---|---|---|---|
| 1.2.0-beta.5 (önizleme) | Dökümhane (yeni) | Önizle | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (GA) | Dökümhane klasik | İstikrarlı | Azure.AI.Projects |
Java için Azure AI Projeleri istemci kitaplığı (önizleme), tek bir proje uç noktasına bağlanarak birden çok istemci kitaplığını birlikte kullanmanızı sağlayan birleşik bir kitaplıktır.
Önemli
Bu makalede işaretlenen (önizleme) öğeler şu anda genel önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.
Foundry projeleri için bu paketleri yüklemenize ekleyin.
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;
JavaScript için Azure AI Projeleri istemci kitaplığı, tek bir proje uç noktasına bağlanarak birden çok istemci kitaplığını birlikte kullanmanızı sağlayan birleşik bir kitaplıktır.
Foundry projeleri için önizleme JavaScript paketlerini yüklemek için bu komutu çalıştırın.
npm install @azure/ai-projects@beta @azure/identity dotenv
.NET için Azure AI Projeleri istemci kitaplığı, tek bir proje uç noktasına bağlanarak birden çok istemci kitaplığını birlikte kullanmanızı sağlayan birleşik bir kitaplıktır.
Azure.AI.Projects paketini .NET projenize eklemek için bu komutu çalıştırın.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
Foundry SDK'sını kullanma
Foundry ve OpenAI farklı API şekillerine sahip olduğundan SDK iki istemci türünü kullanıma sunar:
- Proje istemcisi – OpenAI'nin eşdeğeri olmayan Foundry yerel işlemleri için kullanın. Örnekler: bağlantıları listeleme, proje özelliklerini alma, izlemeyi etkinleştirme.
-
OpenAI uyumlu istemci – OpenAI kavramlarını temel alan Foundry işlevselliği için kullanın. Yanıtlar API'sinde, aracılarda, değerlendirmelerde ve ince ayarlamalarda OpenAI stili istek/yanıt desenleri kullanılır. Bu istemci ayrıca Foundry doğrudan modellerine (Foundry'de barındırılanAzure-OpenAI olmayan modeller) erişmenizi sağlar. Proje uç noktası bu trafiğe
/openaiyolda hizmet verir.
Çoğu uygulama her iki istemciyi de kullanır. Kurulum ve yapılandırma için proje istemcisini kullanın, ardından aracıları, değerlendirmeleri ve çağrı modellerini (Foundry doğrudan modelleri dahil) çalıştırmak için OpenAI uyumlu istemcisini kullanın.
Proje istemcisi oluşturma:
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())
Projenizden OpenAI uyumlu bir istemci oluşturun:
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}")
Beklenen çıkış:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Proje istemcisi oluşturma:
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();
Proje istemcisi oluşturma:
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());
Projenizden OpenAI uyumlu bir istemci oluşturun:
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}`);
Proje istemcisi oluşturma:
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());
Projenizden OpenAI uyumlu bir istemci oluşturun:
#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
DökümHANE SDK'sı ile yapabilecekler
- Azure OpenAI dahil olmak üzere Access Foundry Modelleri
- Foundry Agent Hizmeti'ni kullanın
- Bulut değerlendirmelerini çalıştırma
- Uygulama izlemeyi etkinleştirme
- Modelde ince ayar yapma
- Döküm Araçları, yerel orkestrasyon ve daha fazlası için uç noktaları ve anahtarları alın
Sorun giderme
Kimlik doğrulama hataları
şunu görüyorsanız DefaultAzureCredential failed to retrieve a token:
Azure CLI kimliğinin doğrulandığından emin olun:
az account show az login # if not logged inRBAC role atamasını kontrol edin:
- Foundry projesinde en az Azure AI Kullanıcı rolüne sahip olduğunuzu onaylayın
- Bkz Azure rollerini atama
Üretimde yönetilen kimlik için:
- Yönetilen kimliğin uygun bir role atanmış olduğundan emin olun
- Yönetilen kimlikleri yapılandırma konusuna bkz. Yönetilen kimlikleri yapılandırma
Uç nokta yapılandırma hataları
Eğer Connection refused veya 404 Not Found görüyorsanız:
- Kaynak ve proje adlarının gerçek dağıtımınızla eşleştiğinden emin olun
-
Uç nokta URL biçimini denetleme: Şu olmalıdır:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Özel alt etki alanları için:
<resource-name>ile özel alt etki alanınızı değiştirin
SDK sürümü uyuşmazlıkları
Kod örnekleri AttributeError veya ModuleNotFoundError ile başarısız olursa:
-
SDK sürümünü denetleyin:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NET - Takma ad hizalamasını doğrulama: 2.x SDK için Foundry portalı, 1.x SDK için Foundry klasik gerekir
- Doğru sürüm bayraklarıyla yeniden yükleme: Yukarıdaki her dil bölümünde yükleme komutlarına bakın
OpenAI SDK'sı
Tam OpenAI API yüzeyini ve en yüksek istemci uyumluluğunu istediğinizde OpenAI SDK'sını kullanın. Bu uç nokta, Azure OpenAI modellerine ve Foundry doğrudan modellerine (Yanıtlar API'si aracılığıyla) erişim sağlar. Aracılar ve değerlendirmeler gibi Foundry'ye özgü özelliklere erişim sağlamaz.
Aşağıdaki kod parçacığında Azure OpenAI /openai/v1 uç noktasının doğrudan nasıl kullanılacağı gösterilmektedir.
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))
Beklenen çıkış:
{
"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)."
}
Daha fazla bilgi için bkz. Azure OpenAI tarafından desteklenen programlama dilleri
Önemli
Bu makalede işaretlenen (önizleme) öğeler şu anda genel önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.
Aşağıdaki kod parçacığında Azure OpenAI /openai/v1 uç noktasının doğrudan nasıl kullanılacağı gösterilmektedir.
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());
OpenAI SDK'sını kullanma hakkında daha fazla bilgi için bkz. Azure OpenAI tarafından desteklenen programlama dilleri
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}`);
OpenAI SDK'sını kullanma hakkında daha fazla bilgi için bkz. Azure OpenAI tarafından desteklenen programlama dilleri
- OpenAI paketini yükleyin: OpenAI istemci kitaplığını .NET projenize eklemek için bu komutu çalıştırın.
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.
OpenAI SDK'sını kullanma hakkında daha fazla bilgi için bkz. Azure OpenAI tarafından desteklenen programlama dilleri
Yerel orkestrasyon için Aracı Framework'ü kullanma
Microsoft Agent Framework, bulut sağlayıcısı-bağımsız arabirimiyle kodda (örneğin, .NET ve Python) çok aracılı sistemler oluşturmaya yönelik bir açık kaynak SDK'dır.
Aracıları yerel olarak tanımlamak ve yönetmek istediğinizde Agent Framework kullanın. Bu aracıların Foundry modellerinde çalıştırılmasını istediğinizde veya Aracı Çerçevesi'nin Foundry'de barındırılan aracıları düzenlemesini istediğinizde, bunu Foundry SDK'sı ile eşleştirin.
Daha fazla bilgi için bkz. Microsoft Agent Framework'e genel bakış.
Döküm Araçları SDK'ları
Döküm Araçları (eski adıyla Azure AI Services), ayrılmış SDK'lar ile önceden oluşturulmuş nokta çözümleridir. Döküm Araçları ile çalışmak için aşağıdaki uç noktaları kullanın.
Hangi uç noktayı kullanmalısınız?
Gereksinimlerinize göre bir uç nokta seçin:
Görüntü İşleme, İçerik Güvenliği, Belge Zekası, Dil, Çeviri ve Belirteç Döküm Araçları'na erişmek için Azure AI Services uç noktasını kullanın.
Döküm Araçları uç noktası: https://<your-resource-name>.cognitiveservices.azure.com/
Uyarı
Uç birimler kaynak adınızı veya özel alt etki alanınızı kullanır. Kuruluşunuz özel bir alt etki alanı ayarladıysa, tüm uç nokta örneklerinde your-resource-name ile your-custom-subdomain'i değiştirin.
Konuşma ve Çeviri Döküm Araçları için aşağıdaki tablolardaki uç noktaları kullanın. Yer tutucuları kaynak bilgilerinizle değiştirin.
Konuşma Uç Noktaları
| Döküm Aracı | Bitiş noktası |
|---|---|
| Konuşmayı Metne Dönüştürme (Standart) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Metinden Sese Dönüştürme (Nöral) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Custom Voice | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Çeviri Uç Noktaları
| Döküm Aracı | Bitiş noktası |
|---|---|
| Metin Çevirisi | https://api.cognitive.microsofttranslator.com/ |
| Doküman Çevirisi | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Aşağıdaki bölümlerde, Döküm Araçları SDK'ları için hızlı başlangıç bağlantıları ve başvuru bilgileri yer almaktadır.
