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, etmenlere ve araçlara bütünleş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'deki doğrudan modellere erişimi içerir. | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK'sı | Eklemeler de dahil olmak üzere tam OpenAI API yüzeyiyle en son OpenAI SDK modelleri ve özellikleri. Doğrudan Foundry modelleri, Yanıtlar değil, Sohbet Tamamlamaları API'si 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 (hizmetten hizmete değişir). |
| Agent Framework | Kod içerisinde çok etmenli 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, eklemeler oluştururken veya Sohbet Tamamlamaları aracılığıyla Dökümhane doğrudan modellerini kullanırken OpenAI SDK'sını 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)
Not
Kaynak türleri: Foundry kaynağı, daha önce listelenen tüm uç noktaları sağlar. Azure OpenAI kaynağı yalnızca /openai/v1 uç noktasını sağlar.
Authentication: 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 olarak kullanın.
Önkoşullar
-
Etkin aboneliği olan bir Azure hesabı. Hesabınız yoksa ücretsiz deneme aboneliği içeren bir
free 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 düşük ayrıcalık rolü)
- Azure AI Project 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ını denetleyin → Döküm kaynağı → Erişim denetimi (IAM)
- Dil çalışma zamanı yüklendi:
- Python:
python --version(≥3.8)
- Python:
- Dil çalışma zamanı yüklendi:
- Node.js:
node --version(≥18)
- Node.js:
- Dil çalışma zamanı yüklendi:
- .NET:
dotnet --version(≥6.0)
- .NET:
- Dil çalışma zamanı yüklendi:
- Java:
java --version(≥11)
- Java:
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>
Not
Kuruluşunuz özel bir alt etki alanı kullanıyorsa, uç nokta URL'sinde <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'yi yükleme
| SDK Sürümü | Portal Sürümü | Durum | Python Paketi |
|---|---|---|---|
| 2.x | Dökümhane (yeni) | Istikrarlı | azure-ai-projects>=2.0.0 |
| 1.x | Dökümhane (klasik) | Istikrarlı | azure-ai-projects==1.0.0 |
PythonAzure 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 paketlerini yüklemek için bu komutu çalıştırın.
pip install "azure-ai-projects>=2.0.0"
| SDK Sürümü | Portal Sürümü | Durum | Java Paketi |
|---|---|---|---|
| 2.0.0 | Dökümhane (yeni) | Istikrarlı | azure-ai-projectsazure-ai-agents |
| SDK Sürümü | Portal Sürümü | Durum | JavaScript Paketi |
|---|---|---|---|
| 2.0.1 | Dökümhane (yeni) | Istikrarlı | @azure/ai-projects |
| 1.0.1 | Klasik dökümhane | Istikrarlı | @azure/ai-projects |
| SDK Sürümü | Portal Sürümü | Durum | .NET Paketi |
|---|---|---|---|
| 2.0.0 (GA) | Dökümhane (yeni) | Istikrarlı | Azure.AI.ProjectsAzure.AI.Projects.AgentsAzure.AI.Extensions.OpenAI |
| 1.1.0 (GA) | Klasik dökümhane | Istikrarlı | Azure.AI.Projects |
Önemli
Azure.AI.Projects.OpenAI (GA) ile birlikte Azure.AI.Extensions.OpenAI (önizleme) yüklemeyin. Her iki paket de farklı ad alanında aynı türleri tanımlar ve bu da belirsiz başvuru hatalarına neden olur. Aracı senaryoları için yalnızca Azure.AI.Extensions.OpenAI kullanın.
Java için
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
Foundry projeleri için JavaScript paketlerini yüklemek için bu komutu çalıştırın.
npm install @azure/ai-projects @azure/identity dotenv
.NET için
gerekli paketleri .NET projenize eklemek için bu komutları çalıştırın.
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
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:
- Project client – 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;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
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:
var responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel("gpt-5.2");
var response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
DökümHANE SDK'sı ile yapabilecekler
- Access Modelleme Modelleri, Azure OpenAI dahil olmak üzere
- Foundry Agent Hizmeti'ni kullanma
- Toplu değerlendirmeleri çalıştırma
- Uygulama izlemeyi etkinleştirme
- Modelde ince ayar yapma
- Foundry araçları, yerel orkestrasyon ve daha fazlası için uç noktaları ve anahtarları alma
Sorun giderme
Kimlik doğrulama hataları
Eğer şunu görürseniz DefaultAzureCredential failed to retrieve a token:
Verify Azure CLI kimliği doğrulandı:
az account show az login # if not logged inRBAC rol atamayı denetleyin:
- Foundry projesinde en az Azure yapay zeka kullanıcısı rolüne sahip olduğunuzu onaylayın
- Bkz. Azure rollerini atama
Üretim ortamında yönetilen kimlikler için:
- Yönetilen kimliğin atanmış uygun role sahip olduğundan emin olun
- Yönetilen kimlikleri yapılandırma bölümüne bakın
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>öğesini özel alt etki alanınızla 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 # .NETDoğ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, eklemeler, sohbet tamamlamaları ve görüntü oluşturma dahil olmak üzere 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.
Ipucu
Eklemeler oluşturmak için OpenAI SDK uç noktasını kullanın. Döküm SDK'sı tarafından kullanılan proje uç noktası şu anda ekleme isteklerini yönlendirmemektedir.
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://ai.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
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://ai.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 desteklenen programlama dilleri
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://ai.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 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 `ResponsesClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using OpenAI; using OpenAI.Responses; 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://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponsesClient client = openAIClient.GetResponsesClient(); CreateResponseOptions options = new() { Model = deploymentName, InputItems = { ResponseItem.CreateUserMessageItem("What is the size of France in square miles?") }, Temperature = (float)0.7, }; var modelDirectResponse = client.CreateResponse(options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.Value.GetOutputText()}"); #pragma warning restore OPENAI001
OpenAI SDK'sını kullanma hakkında daha fazla bilgi için bkz. Azure OpenAI desteklenen programlama dilleri
OpenAI SDK'sı ile ekleme oluşturma
Dağıtılan bir ekleme modeliyle eklemeler oluşturmak için aynı /openai/v1 uç noktayı kullanın.
embedding = client.embeddings.create(
model="text-embedding-3-large",
input="How do I get started with Microsoft Foundry?",
)
print(f"Embedding dimension: {len(embedding.data[0].embedding)}")
const embedding = await client.embeddings.create({
model: "text-embedding-3-large",
input: "How do I get started with Microsoft Foundry?",
});
console.log(`Embedding dimension: ${embedding.data[0].embedding.length}`);
var embeddingClient = openAIClient.GetEmbeddingClient("text-embedding-3-large");
var result = embeddingClient.GenerateEmbedding(
"How do I get started with Microsoft Foundry?");
Console.WriteLine($"Embedding dimension: {result.Value.ToFloats().Length}");
// Use the same OpenAI client created above
// Embeddings are available through the OpenAI SDK embeddings API
Tam ekleme nasıl yapılır bilgileri için bkz. Ekleme oluşturma.
Yerel orkestrasyon için Agent Framework'ü kullanma
Microsoft Agent Framework, bulut sağlayıcısı-agnostic arabirimiyle kodda çok aracılı sistemler (örneğin, .NET ve Python) 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'lara sahip ö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ümHane Araçları'na erişmek için Azure AI Hizmetleri uç noktasını kullanın.
Döküm Araçları uç noktası: https://<your-resource-name>.cognitiveservices.azure.com/
Not
Uç noktalar kaynak adınızı veya özel bir alt etki alanı kullanır. Kuruluşunuz özel bir alt etki alanı ayarladıysa, tüm uç nokta örneklerinde your-resource-name öğesini your-custom-subdomain ile değiştirin.
İş yükleriniz yaklaşım analizi, anahtar ifade ayıklama, özetleme, varlık bağlama, CLU veya CQA gibi kullanımdan kaldıran Azure Yapay Zeka Dil özelliklerini kullanıyorsa Microsoft Foundry alternatiflerine geçmeyi planlayın. Yeni geliştirme için, bu makalenin önceki bölümlerinde açıklandığı gibi Foundry SDK'sını veya OpenAI uyumlu uç noktayı kullanmayı göz önünde bulundurun. Bkz. Migrate from Language Studio to Microsoft Foundry.
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 (Sinirsel) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Özel Ses | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Çeviri Uç Noktaları
| Döküm Aracı | Bitiş noktası |
|---|---|
| Metin çevirisi | https://api.cognitive.microsofttranslator.com/ |
| Belge Çevirisi | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Dil Uç Noktaları
| Döküm Aracı | Bitiş noktası |
|---|---|
| Metin analizi | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com |
Önemli
20 Mart 2027'de Azure Language Studio kullanımdan kaldırıp Microsoft Foundry'ye geçirilecek; tüm özellikler ve gelecekteki geliştirmeler Microsoft Foundry'de kullanıma sunulacaktır.
31 Mart 2029'da, aşağıdaki Azure Dil özellikleri devre dışı bırakılacaktır (destek sonu). Bu tarihten önce, kullanıcıların gelişmiş doğal dil anlama ve basitleştirilmiş uygulama tümleştirmesi için mevcut iş yüklerini geçirmesi ve yeni projeleri Microsoft Foundry modellerine eklemesi gerekir:
- Anahtar İfade Çıkarma
- Yaklaşım Analizi ve Görüş Madenciliği
- Özel Metin Sınıflandırması
- Konuşma Dili Anlama (CLU)
- Özel Soru Yanıtlama (CQA)
- Orkestrasyon İş Akışı
- Özetleme (belgeler ve konuşmalar için ayıklayıcı ve soyutlayıcı)
- Varlık Bağlama
Sürekli destekli temel özellikler: Dil Algılama, PII Algılama, Sağlık için Metin Analitiği, Önceden oluşturulmuş NER ve Özel NER.
Geçiş seçenekleri için bkz. Migrate from Language Studio to Microsoft Foundry.
