Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Sumber daya Foundry menyediakan akses terpadu ke model, agen, dan alat. Artikel ini menjelaskan SDK dan titik akhir mana yang akan digunakan untuk skenario Anda.
| SDK | Apa kegunaannya | Titik akhir |
|---|---|---|
| Foundry SDK | Kemampuan khusus foundry dengan antarmuka yang kompatibel dengan OpenAI. Menyertakan akses ke model langsung Foundry melalui API Responses (bukan Chat Completions). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Model dan fitur OpenAI SDK terbaru dengan permukaan OpenAI API lengkap. Model langsung Foundry tersedia melalui Chat Completions API (bukan Respon). | https://<resource-name>.openai.azure.com/openai/v1 |
| SDK Foundry Tools | Solusi bawaan (Visi, Ucapan, Keamanan Konten, dan banyak lagi). | Titik akhir khusus alat (bervariasi menurut layanan). |
| Kerangka Kerja Agen | Orkestrasi multiagen pada kode. Cloud-agnostic. | Menggunakan titik akhir proyek melalui Foundry SDK. |
Pilih SDK Anda:
- Gunakan Foundry SDK saat membangun aplikasi dengan agen, evaluasi, atau fitur khusus Foundry
- Gunakan OpenAI SDK saat dibutuhkan kompatibilitas maksimum dengan OpenAI, atau saat menggunakan model Foundry langsung melalui fungsi Penyelesaian Obrolan.
- Gunakan SDK Foundry Tools saat bekerja dengan layanan AI tertentu (Visi, Ucapan, Bahasa, dll.)
- Gunakan Kerangka Kerja Agen saat membangun sistem multi-agen dalam kode (orkestrasi lokal)
Nota
Jenis sumber daya: Sumber daya Foundry menyediakan semua titik akhir yang sebelumnya tercantum. Sumber daya OpenAI Azure hanya menyediakan titik akhir /openai/v1.
Authentication: Sampel di sini menggunakan Microsoft Entra ID (DefaultAzureCredential). Kunci API berfungsi pada /openai/v1. Teruskan kunci sebagai api_key alih-alih penyedia token.
Prasyarat
-
Akun Azure dengan langganan aktif. Jika Anda tidak memilikinya, buat akun Azure free, yang menyertakan langganan uji coba gratis.
Miliki salah satu peran RBAC Azure berikut untuk membuat dan mengelola sumber daya Foundry:
- Pengguna AI Azure (peran dengan hak istimewa minimum untuk pengembangan)
- Azure Manajer Project AI (untuk mengelola proyek Foundry)
- Kontributor atau Pemilik (untuk izin tingkat langganan)
Untuk detail tentang izin setiap peran, lihat kontrol akses berbasis Role untuk Microsoft Foundry.
Instal runtime bahasa yang diperlukan, alat global, dan ekstensi Visual Studio Code seperti yang dijelaskan dalam Menyiapkan lingkungan pengembangan Anda.
Penting
Sebelum memulai, pastikan lingkungan pengembangan Anda siap.
Artikel ini berfokus pada langkah-langkah khusus skenario seperti penginstalan SDK, autentikasi, dan menjalankan kode sampel.
Memverifikasi prasyarat
Sebelum melanjutkan, konfirmasikan:
- langganan Azure aktif:
az account show - Anda memiliki peran RBAC yang diperlukan: Periksa portal Azure → sumber daya Foundry → Kontrol akses (IAM)
- Bahasa runtime telah terpasang.
- Python:
python --version(≥3.8)
- Python:
- Bahasa runtime telah terpasang.
- Node.js:
node --version(≥18)
- Node.js:
- Bahasa runtime telah terpasang.
- .NET:
dotnet --version(≥6.0)
- .NET:
- Bahasa runtime telah terpasang.
- Java:
java --version(≥11)
- Java:
Foundry SDK
Foundry SDK terhubung ke satu titik akhir proyek yang menyediakan akses ke kemampuan Foundry paling populer:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Nota
Jika organisasi Anda menggunakan subdomain kustom, ganti <resource-name> dengan <your-custom-subdomain> di URL titik akhir.
Pendekatan ini menyederhanakan konfigurasi aplikasi. Daripada mengelola beberapa titik akhir, Anda mengonfigurasi satu titik saja.
Pasang SDK
| Versi SDK | Versi Portal | Kedudukan | Paket Python |
|---|---|---|---|
| 2.x | Foundry (baru) | Stabil | azure-ai-projects>=2.0.0 |
| 1.x | Foundry (klasik) | Stabil | azure-ai-projects==1.0.0 |
Pustaka klien Azure AI Projects untuk Python adalah pustaka terpadu yang memungkinkan Anda menggunakan beberapa pustaka klien bersama-sama dengan menyambungkan ke satu titik akhir proyek.
Jalankan perintah ini untuk menginstal paket untuk proyek Foundry.
pip install azure-ai-projects >=2.0.0
| Versi SDK | Versi Portal | Kedudukan | Paket Java |
|---|---|---|---|
| 2.0.0 | Foundry (baru) | Stabil | azure-ai-projectsazure-ai-agents |
| Versi SDK | Versi Portal | Kedudukan | Paket JavaScript |
|---|---|---|---|
| 2.0.1 | Foundry (baru) | Stabil | @azure/ai-projects |
| 1.0.1 | Foundry klasik | Stabil | @azure/ai-projects |
| Versi SDK | Versi Portal | Kedudukan | Paket .NET |
|---|---|---|---|
| 2.0.0 (GA) | Foundry (baru) | Stabil | Azure.AI.ProjectsAzure.AI.Projects.AgentsAzure.AI.Extensions.OpenAI |
| 1.1.0 (GA) | Foundry klasik | Stabil | Azure.AI.Projects |
Penting
Jangan instal Azure.AI.Projects.OpenAI (versi pratinjau) bersamaan dengan Azure.AI.Extensions.OpenAI (GA). Kedua paket menentukan jenis yang sama di namespace yang berbeda, yang menyebabkan kesalahan referensi ambigu. Gunakan hanya Azure.AI.Extensions.OpenAI untuk skenario agen.
Pustaka klien Azure AI Projects untuk Java adalah pustaka terpadu yang memungkinkan Anda menggunakan beberapa pustaka klien bersama-sama dengan menyambungkan ke satu titik akhir proyek.
Tambahkan paket ini ke penginstalan Anda untuk proyek 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;
Pustaka klien Azure AI Projects untuk JavaScript adalah pustaka terpadu yang memungkinkan Anda menggunakan beberapa pustaka klien bersama-sama dengan menyambungkan ke satu titik akhir proyek.
Jalankan perintah ini untuk menginstal paket JavaScript untuk proyek Foundry.
npm install @azure/ai-projects @azure/identity dotenv
Pustaka klien Azure AI Projects untuk .NET adalah pustaka terpadu yang memungkinkan Anda menggunakan beberapa pustaka klien bersama-sama dengan menyambungkan ke satu titik akhir proyek.
Jalankan perintah ini untuk menambahkan paket yang diperlukan ke proyek .NET Anda.
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
Menggunakan SDK Foundry
SDK mengekspos dua jenis klien karena Foundry dan OpenAI memiliki bentuk API yang berbeda:
- Klien Proyek – Gunakan untuk operasi native-foundry di mana OpenAI tidak memiliki padanan. Contoh: mencantumkan koneksi, mengambil properti proyek, mengaktifkan pelacakan.
-
Klien yang kompatibel dengan OpenAI - Gunakan untuk fungsionalitas Foundry yang dibangun berdasarkan konsep OpenAI. API Respons, agen, evaluasi, dan penyempurnaan semuanya menggunakan pola permintaan/respons ala OpenAI. Klien ini juga memberi Anda akses ke model langsung Foundry (model non-Azure-OpenAI yang dihosting di Foundry). Titik akhir proyek melayani lalu lintas ini pada
/openairute.
Sebagian besar aplikasi menggunakan kedua klien. Gunakan klien proyek untuk penyiapan dan konfigurasi, lalu gunakan klien yang kompatibel dengan OpenAI untuk menjalankan agen, evaluasi, dan model panggilan (termasuk model langsung Foundry).
Buat klien proyek:
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())
Buat klien yang kompatibel dengan OpenAI dari proyek Anda:
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}")
Output yang diharapkan:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Buat klien proyek:
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();
Buat klien proyek:
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());
Buat klien yang kompatibel dengan OpenAI dari proyek Anda:
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}`);
Buat klien proyek:
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());
Buat klien yang kompatibel dengan OpenAI dari proyek Anda:
var responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel("gpt-5.2");
var response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
Apa yang dapat Anda lakukan dengan Foundry SDK
- Access Foundry Models, termasuk Azure OpenAI
- Menggunakan Foundry Agent Service
- Menjalankan evaluasi batch
- Mengaktifkan pelacakan aplikasi
- Menyempurnakan model
- Mendapatkan titik akhir dan kunci untuk Foundry Tools, orkestrasi lokal, dan lainnya
Troubleshooting
Kesalahan autentikasi
Jika Anda melihat DefaultAzureCredential failed to retrieve a token:
Verifikasi Azure CLI telah terautentikasi:
az account show az login # if not logged inPeriksa penetapan peran RBAC:
- Konfirmasikan bahwa Anda memiliki setidaknya peran Pengguna AI Azure pada proyek Foundry
- Lihat tetapkan peran Azure
Untuk identitas terkelola dalam produksi:
- Pastikan identitas terkelola memiliki peran yang sesuai yang ditetapkan
- Lihat Mengonfigurasi identitas terkelola
Kesalahan konfigurasi titik akhir
Jika Anda melihat Connection refused atau 404 Not Found:
- Verifikasi nama sumber daya dan proyek yang cocok dengan penyebaran Anda yang sebenarnya
-
Periksa format URL titik akhir: Harus
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Untuk subdomain kustom: Ganti
<resource-name>dengan subdomain kustom Anda
Ketidakcocokan versi SDK
Jika sampel kode gagal dengan AttributeError atau ModuleNotFoundError:
Periksa versi SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NETInstal ulang dengan bendera versi yang benar: Lihat perintah penginstalan di setiap bagian bahasa di atas
OpenAI SDK
Gunakan OpenAI SDK saat Anda menginginkan permukaan OpenAI API lengkap dan kompatibilitas klien maksimum. Endpoint ini menyediakan akses ke model Azure OpenAI dan model langsung Foundry (melalui API Respons). Ini tidak menyediakan akses ke fitur khusus Foundry seperti agen dan evaluasi.
Cuplikan berikut menunjukkan cara menggunakan titik akhir Azure OpenAI /openai/v1 secara langsung.
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))
Output yang diharapkan:
{
"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)."
}
Untuk informasi selengkapnya, lihat bahasa pemrograman yang didukung Azure OpenAI
Cuplikan berikut menunjukkan cara menggunakan titik akhir Azure OpenAI /openai/v1 secara langsung.
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());
Untuk informasi selengkapnya tentang menggunakan OpenAI SDK, lihat Azure Bahasa pemrograman yang didukung OpenAI
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}`);
Untuk informasi selengkapnya tentang menggunakan OpenAI SDK, lihat Azure Bahasa pemrograman yang didukung OpenAI
- Instal paket OpenAI: Jalankan perintah ini untuk menambahkan pustaka klien OpenAI ke proyek .NET Anda.
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
Untuk informasi selengkapnya tentang menggunakan OpenAI SDK, lihat Azure Bahasa pemrograman yang didukung OpenAI
Menggunakan Kerangka Kerja Agen untuk orkestrasi lokal
Microsoft Agent Framework adalah SDK sumber terbuka untuk membangun sistem multi-agen dalam kode (misalnya, .NET dan Python) dengan antarmuka cloud-provider-agnostic.
Gunakan Kerangka Kerja Agen saat Anda ingin menentukan dan mengatur agen secara lokal. Pasangkan dengan Foundry SDK ketika Anda ingin agen tersebut berjalan terhadap model Foundry atau ketika Anda ingin Agent Framework mengatur agen yang dihosting di Foundry.
Untuk informasi selengkapnya, lihat gambaran umum Microsoft Agent Framework.
SDK Alat Foundri
Foundry Tools (sebelumnya Azure Layanan AI) adalah solusi titik bawaan dengan SDK khusus. Gunakan titik akhir berikut untuk bekerja dengan Foundry Tools.
Titik akhir mana yang harus Anda gunakan?
Pilih titik akhir berdasarkan kebutuhan Anda:
Gunakan titik akhir Layanan AI Azure untuk mengakses Computer Vision, Keamanan Konten, Kecerdasan Dokumen, Bahasa, Terjemahan, dan Alat Foundry Token.
Titik akhir Foundry Tools: https://<your-resource-name>.cognitiveservices.azure.com/
Nota
Titik akhir menggunakan nama sumber daya Anda atau subdomain kustom. Jika organisasi Anda menyiapkan subdomain kustom, ganti your-resource-name dengan your-custom-subdomain di semua contoh titik akhir.
Untuk Perangkat Kerja Foundry untuk Pidato dan Terjemahan, gunakan endpoint API dalam tabel berikut. Ganti placeholder dengan informasi sumber daya Anda.
Titik Akhir Ucapan
| Alat Pengecoran | Titik akhir |
|---|---|
| Ucapan ke Teks (Standar) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Teks ke Ucapan (Neural) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Suara Kustom | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Titik Akhir Terjemahan
| Alat Pengecoran | Titik akhir |
|---|---|
| Terjemahan Teks | https://api.cognitive.microsofttranslator.com/ |
| Penerjemahan Dokumen | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Bagian berikut ini menyertakan tautan mulai cepat untuk SDK Foundry Tools dan informasi referensi.
