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.
Sedang menampilkan:
Versi portal Foundry (klasik) - Beralih ke versi portal Foundry yang baru
Sumber daya Foundry memberikan 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. Termasuk akses ke model langsung Foundry melalui API Respon (bukan Penyelesaian Obrolan). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Model dan fitur OpenAI SDK terbaru dengan surface 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 yang 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
Nota
Artikel ini berlaku untuk proyek Foundry. Kode yang ditampilkan di sini tidak berfungsi untuk proyek berbasis hub. Untuk informasi selengkapnya, lihat Jenis proyek.
Nota
Versi SDK: Artikel ini membahas penginstalan SDK 1.x. Pastikan sampel yang Anda ikuti cocok dengan paket yang diinstal. Beralih ke dokumentasi portal Foundry baru untuk melihat artikel untuk 2.x.
| 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 1.x untuk proyek klasik Foundry.
pip install openai azure-identity azure-ai-projects==1.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-beta.1 (preview) | Foundry (baru) | Pratinjau | Azure.AI.ProjectsAzure.AI.Projects.OpenAI |
| 1.1.0 (GA) | Foundry klasik | Stabil | Azure.AI.Projects |
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.
Penting
Paket Java azure-ai-projects tidak memiliki rilis GA 1.x. Sampel kode di bagian Java menggunakan paket azure-ai-inference secara langsung, yang tidak digunakan lagi dan akan dihentikan pada 30 Mei 2026.
Untuk SDK Proyek 2.x, beralihlah ke dokumentasi portal Foundry baru.
Tambahkan dependensi ini ke konfigurasi Maven pom.xml untuk proyek klasik Foundry Anda.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-inference</artifactId>
<version>1.0.0-beta.6</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.2</version>
</dependency>
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 1.x untuk proyek klasik Foundry.
npm install @azure/ai-projects@1.0.1 @azure/identity
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 1.x Azure AI SDK untuk proyek klasik Foundry.
# Add 1.x Azure AI SDK packages
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects --version 1.1.0
dotnet add package Azure.AI.Agents.Persistent --version 1.1.0
dotnet add package Azure.AI.Inference
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 project melayani lalu lintas ini pada rute
/openai.
Sebagian besar aplikasi menggunakan kedua klien. Gunakan klien project 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.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
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:
models = project_client.get_openai_client(api_version="2024-10-21")
chat_responses = models.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the size of France in square miles?"},
],
)
print(chat_responses.choices[0].message.content)
Buat klien proyek:
package com.azure.ai.foundry.samples;
import com.azure.ai.inference.ChatCompletionsClient;
import com.azure.ai.inference.ChatCompletionsClientBuilder;
import com.azure.ai.inference.models.ChatCompletions;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.credential.TokenCredential;
import com.azure.core.exception.HttpResponseException;
import com.azure.core.util.logging.ClientLogger;
import com.azure.identity.DefaultAzureCredentialBuilder;
String prompt = "What best practices should I follow when asking an AI model to review Java code?";
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
.credential(credential)
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
ChatCompletions completions = client.complete(prompt);
String content = completions.getChoice().getMessage().getContent();
System.out.println("\nResponse from AI assistant:\n" + content);
Buat klien proyek:
const endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deployment = "gpt-4o";
const project = new AIProjectClient(endpoint, new DefaultAzureCredential());
Buat klien yang kompatibel dengan OpenAI dari proyek Anda:
const client = await project.getAzureOpenAIClient({
// The API version should match the version of the Azure OpenAI resource
apiVersion: "2024-12-01-preview"
});
const chatCompletion = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(chatCompletion.choices[0].message.content);
Buat klien proyek:
using System.ClientModel.Primitives;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.Identity;
using OpenAI.Chat;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
Buat klien yang kompatibel dengan OpenAI dari proyek Anda:
ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null)
{
throw new InvalidOperationException("Invalid URI.");
}
uri = new Uri($"https://{uri.Host}");
const string modelDeploymentName = "gpt-4o";
AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential());
ChatClient chatClient = azureOpenAIClient.GetChatClient(deploymentName: modelDeploymentName);
Console.WriteLine("Complete a chat");
ChatCompletion result = chatClient.CompleteChat("List all the rainbow colors");
Console.WriteLine(result.Content[0].Text);
Apa yang dapat Anda lakukan dengan Foundry SDK
- Access Foundry Models, termasuk Azure OpenAI
- Gunakan Foundry Agent Service
- Lakukan evaluasi cloud
- Mengaktifkan pelacakan aplikasi
- Melakukan fine-tuning pada 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 projekt sesuai dengan penyebaran sebenarnya Anda
-
Check 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 cakupan penuh API OpenAI dan kompatibilitas maksimum dengan klien. Titik akhir ini menyediakan akses ke model Azure OpenAI dan model Foundry langsung (melalui Antar Muka Penyelesaian Obrolan API). 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))
Untuk informasi selengkapnya, lihat bahasa pemrograman yang didukung Azure OpenAI. 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
Penting
Item-item yang ditandai (pratinjau) dalam artikel ini saat ini sedang berada dalam pratinjau publik. Pratinjau ini disediakan tanpa kesepakatan tingkat layanan, dan kami tidak merekomendasikannya untuk penggunaan dalam lingkungan produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.
Cuplikan berikut menunjukkan cara menggunakan titik akhir Azure OpenAI /openai/v1 secara langsung.
import com.azure.ai.openai.OpenAIClient;
import com.azure.ai.openai.OpenAIClientBuilder;
import com.azure.ai.openai.models.ChatChoice;
import com.azure.ai.openai.models.ChatCompletions;
import com.azure.ai.openai.models.ChatCompletionsOptions;
import com.azure.ai.openai.models.ChatRequestAssistantMessage;
import com.azure.ai.openai.models.ChatRequestMessage;
import com.azure.ai.openai.models.ChatRequestSystemMessage;
import com.azure.ai.openai.models.ChatRequestUserMessage;
import com.azure.ai.openai.models.ChatResponseMessage;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Configuration;
import java.util.ArrayList;
import java.util.List;
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(defaultCredential)
.endpoint("{endpoint}")
.buildClient();
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant."));
chatMessages.add(new ChatRequestUserMessage("What is the speed of light?"));
ChatCompletions chatCompletions = client.getChatCompletions(deploymentName, new ChatCompletionsOptions(chatMessages));
System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
ChatResponseMessage message = choice.getMessage();
System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
System.out.println("Message:");
System.out.println(message.getContent());
Untuk informasi selengkapnya tentang menggunakan OpenAI SDK, lihat Azure Bahasa pemrograman yang didukung OpenAI.
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const deployment = "gpt-4o";
const endpoint = "https://<resource-name>.openai.azure.com";
const scope = "https://ai.azure.com/.default";
const apiVersion = "2024-04-01-preview";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const options = { azureADTokenProvider, deployment, apiVersion, endpoint };
const client = new AzureOpenAI(options);
const result = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(result.choices[0].message.content);
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 `ChatClient` for the Azure OpenAI v1 endpoint. ```csharp using System.ClientModel.Primitives; using Azure.Identity; using OpenAI; using OpenAI.Chat; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string modelDeploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ChatClient chatClient = openAIClient.GetChatClient(modelDeploymentName); ChatCompletion completion = await chatClient.CompleteChatAsync( [ new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("How many feet are in a mile?") ]); Console.WriteLine(completion.Content[0].Text); #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.
