Azure OpenAI 支援的程式設計語言
適用於 .NET 的 Azure OpenAI 用戶端連結庫是官方 OpenAI 用戶端連結庫 for .NET 的隨附專案。 Azure OpenAI 連結庫會設定用戶端來與 Azure OpenAI 搭配使用，並為 Azure OpenAI 案例專屬的要求和回應模型提供額外的強型別延伸模組支援。
穩定版本：
原始程式碼套件 （NuGet） | 套件參考檔 API 參考檔範例 | |
預覽版本：
預覽版本將可存取最新功能。
原始程式碼套件 （NuGet） | API 參考檔 | 套件參考檔範例 |
Azure OpenAI API 版本支援
不同於適用於 Python 和 JavaScript 的 Azure OpenAI 用戶端連結庫，Azure OpenAI .NET 套件僅限於以 Azure OpenAI API 版本的特定子集為目標。 一般而言，每個 Azure OpenAI .NET 套件都會解除鎖定存取較新的 Azure OpenAI API 版本功能。 存取最新 API 版本會影響功能可用性。
版本選取是由列舉所 AzureOpenAIClientOptions.ServiceVersion 控制。
穩定版本目前的目標如下：
2024-06-01
預覽版本目前可設為下列目標：
2024-06-012024-08-01-preview2024-09-01-preview2024-10-01-preview
安裝
dotnet add package Azure.AI.OpenAI --prerelease
此 Azure.AI.OpenAI 套件是以 官方 OpenAI 套件為基礎建置，此套件會隨附為相依性。
驗證
若要與 Azure OpenAI 或 OpenAI 互動，請使用下列其中一種方法建立 的實例 AzureOpenAIClient ：
安全的無密鑰驗證方法是透過 Azure 身分識別連結庫使用Microsoft Entra ID（先前稱為 Azure Active Directory）。 若要使用連結庫：
dotnet add package Azure.Identity
從連結庫使用所需的認證類型。 例如： DefaultAzureCredential
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-mini-deployment");
音訊
AzureOpenAIClient.GetAudioClient
文字記錄
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
AudioClient client = azureClient.GetAudioClient("whisper");
string audioFilePath = Path.Combine("Assets", "speech.mp3");
AudioTranscriptionOptions options = new()
{
ResponseFormat = AudioTranscriptionFormat.Verbose,
TimestampGranularities = AudioTimestampGranularities.Word | AudioTimestampGranularities.Segment,
};
AudioTranscription transcription = client.TranscribeAudio(audioFilePath, options);
Console.WriteLine("Transcription:");
Console.WriteLine($"{transcription.Text}");
Console.WriteLine();
Console.WriteLine($"Words:");
foreach (TranscribedWord word in transcription.Words)
{
Console.WriteLine($" {word.Word,15} : {word.StartTime.TotalMilliseconds,5:0} - {word.EndTime.TotalMilliseconds,5:0}");
}
Console.WriteLine();
Console.WriteLine($"Segments:");
foreach (TranscribedSegment segment in transcription.Segments)
{
Console.WriteLine($" {segment.Text,90} : {segment.StartTime.TotalMilliseconds,5:0} - {segment.EndTime.TotalMilliseconds,5:0}");
}
文字到語音轉換 （TTS）
using Azure.AI.OpenAI;
using Azure.Identity;
using OpenAI.Audio;
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
AudioClient client = azureClient.GetAudioClient("tts-hd"); //Replace with your Azure OpenAI model deployment
string input = "Testing, testing, 1, 2, 3";
BinaryData speech = client.GenerateSpeech(input, GeneratedSpeechVoice.Alloy);
using FileStream stream = File.OpenWrite($"{Guid.NewGuid()}.mp3");
speech.ToStream().CopyTo(stream);
聊天
AzureOpenAIClient.GetChatClient
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-deployment");
ChatCompletion completion = chatClient.CompleteChat(
[
// System messages represent instructions or other guidance about how the assistant should behave
new SystemChatMessage("You are a helpful assistant that talks like a pirate."),
// User messages represent user input, whether historical or the most recent input
new UserChatMessage("Hi, can you help me?"),
// Assistant messages in a request represent conversation history for responses
new AssistantChatMessage("Arrr! Of course, me hearty! What can I do for ye?"),
new UserChatMessage("What's the best way to train a parrot?"),
]);
Console.WriteLine($"{completion.Role}: {completion.Content[0].Text}");
串流聊天訊息
串流聊天完成會使用 CompleteChatStreaming 和 CompleteChatStreamingAsync 方法，其會傳回 ResultCollection<StreamingChatCompletionUpdate> 或 AsyncCollectionResult<StreamingChatCompletionUpdate> 而不是 ClientResult<ChatCompletion>。
您可以使用 foreach 或 await foreach 逐一查看這些結果集合，每次更新都會隨著串流回應中可用的新數據而抵達。
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-deployment");
CollectionResult<StreamingChatCompletionUpdate> completionUpdates = chatClient.CompleteChatStreaming(
[
new SystemChatMessage("You are a helpful assistant that talks like a pirate."),
new UserChatMessage("Hi, can you help me?"),
new AssistantChatMessage("Arrr! Of course, me hearty! What can I do for ye?"),
new UserChatMessage("What's the best way to train a parrot?"),
]);
foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates)
{
foreach (ChatMessageContentPart contentPart in completionUpdate.ContentUpdate)
{
Console.Write(contentPart.Text);
}
}
Embeddings
AzureOpenAIClient.GetEmbeddingClient
using Azure.AI.OpenAI;
using Azure.Identity;
using OpenAI.Embeddings;
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
EmbeddingClient client = azureClient.GetEmbeddingClient("text-embedding-3-large"); //Replace with your model deployment name
string description = "This is a test embedding";
OpenAIEmbedding embedding = client.GenerateEmbedding(description);
ReadOnlyMemory<float> vector = embedding.ToFloats();
Console.WriteLine(string.Join(", ", vector.ToArray()));
微調
Azure OpenAI .NET 套件目前不支援。
Batch
Azure OpenAI .NET 套件目前不支援。
影像
AzureOpenAIClient.GetImageClient
using Azure.AI.OpenAI;
using Azure.Identity;
using OpenAI.Images;
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ImageClient client = azureClient.GetImageClient("dall-e-3"); // replace with your model deployment name.
string prompt = "A rabbit eating pancakes.";
ImageGenerationOptions options = new()
{
Quality = GeneratedImageQuality.High,
Size = GeneratedImageSize.W1792xH1024,
Style = GeneratedImageStyle.Vivid,
ResponseFormat = GeneratedImageFormat.Bytes
};
GeneratedImage image = client.GenerateImage(prompt, options);
BinaryData bytes = image.ImageBytes;
using FileStream stream = File.OpenWrite($"{Guid.NewGuid()}.png");
bytes.ToStream().CopyTo(stream);
完成 (舊版)
Azure OpenAI .NET 套件不支援。
錯誤處理
錯誤碼
| 狀態碼 | 錯誤類型 |
|---|---|
| 400 | Bad Request Error |
| 401 | Authentication Error |
| 403 | Permission Denied Error |
| 404 | Not Found Error |
| 422 | Unprocessable Entity Error |
| 429 | Rate Limit Error |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
| 504 | Gateway Timeout |
重試
客戶端類別會使用指數輪詢自動重試下列錯誤，最多三次：
- 408 要求逾時
- 429 要求太多
- 500 內部伺服器錯誤
- 502 錯誤的閘道
- 503 服務無法使用
- 504 閘道逾時
原始程式碼套件 （pkg.go.dev） | API 參考檔 | 套件參考檔範例 |
Azure OpenAI API 版本支援
不同於適用於 Python 和 JavaScript 的 Azure OpenAI 用戶端連結庫，Azure OpenAI Go 連結庫是以特定 Azure OpenAI API 版本為目標。 存取最新 API 版本會影響功能可用性。
目前的 Azure OpenAI API 版本目標： 2024-10-01-preview
這會定義在 custom_client.go 檔案中。
安裝
azopenai使用 go 安裝 與 azidentity 模組：
go get github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai
# optional
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
驗證
使用 Azure OpenAI 進行 Azure Active Directory 驗證時，會 使用 azidentity 模組進行 Azure Active Directory 驗證。
package main
import (
"log"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)
func main() {
dac, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
// NOTE: this constructor creates a client that connects to an Azure OpenAI endpoint.
// To connect to the public OpenAI endpoint, use azopenai.NewClientForOpenAI
client, err := azopenai.NewClient("https://<your-azure-openai-host>.openai.azure.com", dac, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
_ = client
}
音訊
Client.GenerateSpeechFromText
ackage main
import (
"context"
"fmt"
"io"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
openAIKey := os.Getenv("OPENAI_API_KEY")
// Ex: "https://api.openai.com/v1"
openAIEndpoint := os.Getenv("OPENAI_ENDPOINT")
modelDeploymentID := "tts-1"
if openAIKey == "" || openAIEndpoint == "" || modelDeploymentID == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(openAIKey)
client, err := azopenai.NewClientForOpenAI(openAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
audioResp, err := client.GenerateSpeechFromText(context.Background(), azopenai.SpeechGenerationOptions{
Input: to.Ptr("i am a computer"),
Voice: to.Ptr(azopenai.SpeechVoiceAlloy),
ResponseFormat: to.Ptr(azopenai.SpeechGenerationResponseFormatFlac),
DeploymentName: to.Ptr("tts-1"),
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
defer audioResp.Body.Close()
audioBytes, err := io.ReadAll(audioResp.Body)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
fmt.Fprintf(os.Stderr, "Got %d bytes of FLAC audio\n", len(audioBytes))
}
Client.GetAudioTranscription
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_WHISPER_API_KEY")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_WHISPER_ENDPOINT")
modelDeploymentID := os.Getenv("AOAI_WHISPER_MODEL")
if azureOpenAIKey == "" || azureOpenAIEndpoint == "" || modelDeploymentID == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
mp3Bytes, err := os.ReadFile("testdata/sampledata_audiofiles_myVoiceIsMyPassportVerifyMe01.mp3")
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetAudioTranscription(context.TODO(), azopenai.AudioTranscriptionOptions{
File: mp3Bytes,
// this will return _just_ the translated text. Other formats are available, which return
// different or additional metadata. See [azopenai.AudioTranscriptionFormat] for more examples.
ResponseFormat: to.Ptr(azopenai.AudioTranscriptionFormatText),
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
fmt.Fprintf(os.Stderr, "Transcribed text: %s\n", *resp.Text)
}
聊天
Client.GetChatCompletions
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_CHAT_COMPLETIONS_API_KEY")
modelDeploymentID := os.Getenv("AOAI_CHAT_COMPLETIONS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_CHAT_COMPLETIONS_ENDPOINT")
if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
// This is a conversation in progress.
// NOTE: all messages, regardless of role, count against token usage for this API.
messages := []azopenai.ChatRequestMessageClassification{
// You set the tone and rules of the conversation with a prompt as the system role.
&azopenai.ChatRequestSystemMessage{Content: azopenai.NewChatRequestSystemMessageContent("You are a helpful assistant. You will talk like a pirate.")},
// The user asks a question
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("Can you help me?")},
// The reply would come back from the ChatGPT. You'd add it to the conversation so we can maintain context.
&azopenai.ChatRequestAssistantMessage{Content: azopenai.NewChatRequestAssistantMessageContent("Arrrr! Of course, me hearty! What can I do for ye?")},
// The user answers the question based on the latest reply.
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("What's the best way to train a parrot?")},
// from here you'd keep iterating, sending responses back from ChatGPT
}
gotReply := false
resp, err := client.GetChatCompletions(context.TODO(), azopenai.ChatCompletionsOptions{
// This is a conversation in progress.
// NOTE: all messages count against token usage for this API.
Messages: messages,
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, choice := range resp.Choices {
gotReply = true
if choice.ContentFilterResults != nil {
fmt.Fprintf(os.Stderr, "Content filter results\n")
if choice.ContentFilterResults.Error != nil {
fmt.Fprintf(os.Stderr, " Error:%v\n", choice.ContentFilterResults.Error)
}
fmt.Fprintf(os.Stderr, " Hate: sev: %v, filtered: %v\n", *choice.ContentFilterResults.Hate.Severity, *choice.ContentFilterResults.Hate.Filtered)
fmt.Fprintf(os.Stderr, " SelfHarm: sev: %v, filtered: %v\n", *choice.ContentFilterResults.SelfHarm.Severity, *choice.ContentFilterResults.SelfHarm.Filtered)
fmt.Fprintf(os.Stderr, " Sexual: sev: %v, filtered: %v\n", *choice.ContentFilterResults.Sexual.Severity, *choice.ContentFilterResults.Sexual.Filtered)
fmt.Fprintf(os.Stderr, " Violence: sev: %v, filtered: %v\n", *choice.ContentFilterResults.Violence.Severity, *choice.ContentFilterResults.Violence.Filtered)
}
if choice.Message != nil && choice.Message.Content != nil {
fmt.Fprintf(os.Stderr, "Content[%d]: %s\n", *choice.Index, *choice.Message.Content)
}
if choice.FinishReason != nil {
// this choice's conversation is complete.
fmt.Fprintf(os.Stderr, "Finish reason[%d]: %s\n", *choice.Index, *choice.FinishReason)
}
}
if gotReply {
fmt.Fprintf(os.Stderr, "Got chat completions reply\n")
}
}
Client.GetChatCompletionsStream
package main
import (
"context"
"errors"
"fmt"
"io"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_CHAT_COMPLETIONS_API_KEY")
modelDeploymentID := os.Getenv("AOAI_CHAT_COMPLETIONS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_CHAT_COMPLETIONS_ENDPOINT")
if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
// This is a conversation in progress.
// NOTE: all messages, regardless of role, count against token usage for this API.
messages := []azopenai.ChatRequestMessageClassification{
// You set the tone and rules of the conversation with a prompt as the system role.
&azopenai.ChatRequestSystemMessage{Content: azopenai.NewChatRequestSystemMessageContent("You are a helpful assistant. You will talk like a pirate and limit your responses to 20 words or less.")},
// The user asks a question
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("Can you help me?")},
// The reply would come back from the ChatGPT. You'd add it to the conversation so we can maintain context.
&azopenai.ChatRequestAssistantMessage{Content: azopenai.NewChatRequestAssistantMessageContent("Arrrr! Of course, me hearty! What can I do for ye?")},
// The user answers the question based on the latest reply.
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("What's the best way to train a parrot?")},
// from here you'd keep iterating, sending responses back from ChatGPT
}
resp, err := client.GetChatCompletionsStream(context.TODO(), azopenai.ChatCompletionsStreamOptions{
// This is a conversation in progress.
// NOTE: all messages count against token usage for this API.
Messages: messages,
N: to.Ptr[int32](1),
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
defer resp.ChatCompletionsStream.Close()
gotReply := false
for {
chatCompletions, err := resp.ChatCompletionsStream.Read()
if errors.Is(err, io.EOF) {
break
}
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, choice := range chatCompletions.Choices {
gotReply = true
text := ""
if choice.Delta.Content != nil {
text = *choice.Delta.Content
}
role := ""
if choice.Delta.Role != nil {
role = string(*choice.Delta.Role)
}
fmt.Fprintf(os.Stderr, "Content[%d], role %q: %q\n", *choice.Index, role, text)
}
}
if gotReply {
fmt.Fprintf(os.Stderr, "Got chat completions streaming reply\n")
}
}
Embeddings
Client.GetEmbeddings
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_EMBEDDINGS_API_KEY")
modelDeploymentID := os.Getenv("AOAI_EMBEDDINGS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_EMBEDDINGS_ENDPOINT")
if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetEmbeddings(context.TODO(), azopenai.EmbeddingsOptions{
Input: []string{"Testing, testing, 1,2,3."},
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, embed := range resp.Data {
// embed.Embedding contains the embeddings for this input index.
fmt.Fprintf(os.Stderr, "Got embeddings for input %d\n", *embed.Index)
}
}
映射產生
Client.GetImageGenerations
package main
import (
"context"
"fmt"
"log"
"net/http"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_DALLE_API_KEY")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_DALLE_ENDPOINT")
azureDeployment := os.Getenv("AOAI_DALLE_MODEL")
if azureOpenAIKey == "" || azureOpenAIEndpoint == "" || azureDeployment == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetImageGenerations(context.TODO(), azopenai.ImageGenerationOptions{
Prompt: to.Ptr("a cat"),
ResponseFormat: to.Ptr(azopenai.ImageGenerationResponseFormatURL),
DeploymentName: &azureDeployment,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, generatedImage := range resp.Data {
// the underlying type for the generatedImage is dictated by the value of
// ImageGenerationOptions.ResponseFormat. In this example we used `azopenai.ImageGenerationResponseFormatURL`,
// so the underlying type will be ImageLocation.
resp, err := http.Head(*generatedImage.URL)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
_ = resp.Body.Close()
fmt.Fprintf(os.Stderr, "Image generated, HEAD request on URL returned %d\n", resp.StatusCode)
}
}
完成 (舊版)
Client.GetChatCompletions
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_COMPLETIONS_API_KEY")
modelDeployment := os.Getenv("AOAI_COMPLETIONS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_COMPLETIONS_ENDPOINT")
if azureOpenAIKey == "" || modelDeployment == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetCompletions(context.TODO(), azopenai.CompletionsOptions{
Prompt: []string{"What is Azure OpenAI, in 20 words or less"},
MaxTokens: to.Ptr(int32(2048)),
Temperature: to.Ptr(float32(0.0)),
DeploymentName: &modelDeployment,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, choice := range resp.Choices {
fmt.Fprintf(os.Stderr, "Result: %s\n", *choice.Text)
}
}
錯誤處理
當這些要求失敗時，傳送 HTTP 要求的所有方法都會傳回 *azcore.ResponseError 。 ResponseError 有錯誤詳細數據和來自服務的原始回應。
記錄
此課程模組使用 azcore 中的記錄實作。 若要開啟所有 Azure SDK 模組的記錄，請將AZURE_SDK_GO_LOGGING設為all。 根據預設，記錄器會寫入 stderr。 使用 azcore/log 套件來控制記錄輸出。 例如，只記錄 HTTP 要求和回應事件，並將其列印至 stdout：
import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// Print log events to stdout
azlog.SetListener(func(cls azlog.Event, msg string) {
fmt.Println(msg)
})
// Includes only requests and responses in credential logs
azlog.SetEvents(azlog.EventRequest, azlog.EventResponse)
原始碼成品 （Maven） | API 參考檔 | 套件參考檔範例 |
Azure OpenAI API 版本支援
不同於適用於 Python 和 JavaScript 的 Azure OpenAI 用戶端連結庫，為了確保 Azure OpenAI Java 套件的相容性僅限於以 Azure OpenAI API 版本的特定子集為目標。 一般而言，每個 Azure OpenAI Java 套件都會解除鎖定較新的 Azure OpenAI API 版本功能的存取權。 存取最新 API 版本會影響功能可用性。
版本選取是由列舉所 OpenAIServiceVersion 控制。
支援的最新 Azure OpenAI 預覽 API 如下：
-2024-08-01-preview
支援的最新穩定版 （GA） 版本如下：
-2024-06-01
安裝
套件詳細資料
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-openai</artifactId>
<version>1.0.0-beta.12</version>
</dependency>
驗證
若要與 Azure OpenAI 服務互動，您必須建立用戶端類別的實體， OpenAIAsyncClient 或使用 OpenAIClient OpenAIClientBuilder。 若要設定用戶端以搭配 Azure OpenAI 使用，請提供有效的端點 URI 給 Azure OpenAI 資源，以及授權使用 Azure OpenAI 資源的對應密鑰認證、令牌認證或 Azure 身分識別認證。
使用 Microsoft Entra 識別碼進行驗證需要一些初始設定：
新增 Azure 身分識別套件：
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.13.3</version>
</dependency>
設定之後，您可以選擇要使用的認證 azure.identity 類型。 例如， DefaultAzureCredential 可用來驗證用戶端：將Microsoft Entra ID 應用程式的用戶端標識碼、租使用者標識碼和用戶端密碼的值設定為環境變數：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。
使用 DefaultAzureCredential 最簡單的授權。 它會尋找在其執行環境中使用的最佳認證。
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(defaultCredential)
.endpoint("{endpoint}")
.buildClient();
音訊
client.getAudioTranscription
String fileName = "{your-file-name}";
Path filePath = Paths.get("{your-file-path}" + fileName);
byte[] file = BinaryData.fromFile(filePath).toBytes();
AudioTranscriptionOptions transcriptionOptions = new AudioTranscriptionOptions(file)
.setResponseFormat(AudioTranscriptionFormat.JSON);
AudioTranscription transcription = client.getAudioTranscription("{deploymentOrModelName}", fileName, transcriptionOptions);
System.out.println("Transcription: " + transcription.getText());
client.generateSpeechFromText
文字到語音轉換 （TTS）
String deploymentOrModelId = "{azure-open-ai-deployment-model-id}";
SpeechGenerationOptions options = new SpeechGenerationOptions(
"Today is a wonderful day to build something people love!",
SpeechVoice.ALLOY);
BinaryData speech = client.generateSpeechFromText(deploymentOrModelId, options);
// Checkout your generated speech in the file system.
Path path = Paths.get("{your-local-file-path}/speech.wav");
Files.write(path, speech.toBytes());
聊天
client.getChatCompletions
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatRequestUserMessage("Can you help me?"));
chatMessages.add(new ChatRequestAssistantMessage("Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatRequestUserMessage("What's the best way to train a parrot?"));
ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}",
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());
}
串流
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatRequestUserMessage("Can you help me?"));
chatMessages.add(new ChatRequestAssistantMessage("Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatRequestUserMessage("What's the best way to train a parrot?"));
ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}",
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());
}
使用影像的聊天完成
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant that describes images"));
chatMessages.add(new ChatRequestUserMessage(Arrays.asList(
new ChatMessageTextContentItem("Please describe this image"),
new ChatMessageImageContentItem(
new ChatMessageImageUrl("https://raw.githubusercontent.com/MicrosoftDocs/azure-ai-docs/main/articles/ai-services/openai/media/how-to/generated-seattle.png"))
)));
ChatCompletionsOptions chatCompletionsOptions = new ChatCompletionsOptions(chatMessages);
ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}", chatCompletionsOptions);
System.out.println("Chat completion: " + chatCompletions.getChoices().get(0).getMessage().getContent());
Embeddings
client.getEmbeddings
EmbeddingsOptions embeddingsOptions = new EmbeddingsOptions(
Arrays.asList("Your text string goes here"));
Embeddings embeddings = client.getEmbeddings("{deploymentOrModelName}", embeddingsOptions);
for (EmbeddingItem item : embeddings.getData()) {
System.out.printf("Index: %d.%n", item.getPromptIndex());
for (Float embedding : item.getEmbedding()) {
System.out.printf("%f;", embedding);
}
}
影像產生
ImageGenerationOptions imageGenerationOptions = new ImageGenerationOptions(
"A drawing of the Seattle skyline in the style of Van Gogh");
ImageGenerations images = client.getImageGenerations("{deploymentOrModelName}", imageGenerationOptions);
for (ImageGenerationData imageGenerationData : images.getData()) {
System.out.printf(
"Image location URL that provides temporary access to download the generated image is %s.%n",
imageGenerationData.getUrl());
}
處理錯誤
啟用用戶端記錄
若要針對 Azure OpenAI 連結庫的問題進行疑難解答，請務必先啟用記錄來監視應用程式的行為。 記錄中的錯誤和警告通常會提供錯誤狀況的實用見解，有時包括修正問題的更正動作。 適用於 Java 的 Azure 用戶端連結庫有兩個記錄選項：
- 內建記錄架構。
- 支援使用 SLF4J 介面進行記錄。
請參閱本參考檔中的指示，以瞭解如何 [在 Azure SDK for Java 中設定記錄][logging_overview]。
啟用 HTTP 要求/回應記錄
檢閱透過網路傳送或從 Azure OpenAI 服務接收的 HTTP 要求，對於疑難解答問題很有用。 若要啟用記錄 HTTP 要求和響應承載，可以設定 [OpenAIClient][openai_client]，如下所示。 如果類別路徑上沒有 SLF4J Logger ，請在您的電腦中設定環境變數 [AZURE_LOG_LEVEL][azure_log_level]，以啟用記錄。
OpenAIClient openAIClient = new OpenAIClientBuilder()
.endpoint("{endpoint}")
.credential(new AzureKeyCredential("{key}"))
.httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
.buildClient();
// or
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
OpenAIClient configurationClientAad = new OpenAIClientBuilder()
.credential(credential)
.endpoint("{endpoint}")
.httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
.buildClient();
或者，您可以藉由設定下列環境變數，為整個應用程式設定記錄 HTTP 要求和回應。 請注意，這項變更會針對支持記錄 HTTP 要求/回應的每個 Azure 用戶端啟用記錄。
環境變數名稱： AZURE_HTTP_LOG_DETAIL_LEVEL
| 值 | 記錄層級 |
|---|---|
| none | 已停用 HTTP 要求/回應記錄 |
| basic | 僅記錄 URL、HTTP 方法和完成要求的時間。 |
| 標題 | 記錄 BASIC 中的所有專案，以及所有要求和回應標頭。 |
| 本文 | 記錄 BASIC 中的所有專案，以及所有要求和回應本文。 |
| body_and_headers | 記錄 HEADERS 和 BODY 中的所有專案。 |
注意
記錄要求和回應的本文時，請確定它們不包含機密資訊。 記錄標頭時，客戶端連結庫有一組默認標頭，這些標頭被視為安全可記錄，但更新產生器中的記錄選項即可更新此集合，如下所示。
clientBuilder.httpLogOptions(new HttpLogOptions().addAllowedHeaderName("safe-to-log-header-name"))
疑難解答例外狀況
Azure OpenAI 服務方法會在失敗時擲回[HttpResponseException 或其子類別。
HttpResponseException OpenAI 用戶端連結庫擲回的 包含詳細的回應錯誤物件，可提供對發生錯誤情況的特定實用見解，並包含修正常見問題的更正動作。
您可以在物件的 message 屬性 HttpResponseException 內找到此錯誤資訊。
以下是如何使用同步客戶端攔截它的範例
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatRequestUserMessage("Can you help me?"));
chatMessages.add(new ChatRequestAssistantMessage("Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatRequestUserMessage("What's the best way to train a parrot?"));
try {
ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}",
new ChatCompletionsOptions(chatMessages));
} catch (HttpResponseException e) {
System.out.println(e.getMessage());
// Do something with the exception
}
透過異步用戶端，您可以在錯誤回呼中攔截和處理例外狀況：
asyncClient.getChatCompletions("{deploymentOrModelName}", new ChatCompletionsOptions(chatMessages))
.doOnSuccess(ignored -> System.out.println("Success!"))
.doOnError(
error -> error instanceof ResourceNotFoundException,
error -> System.out.println("Exception: 'getChatCompletions' could not be performed."));
驗證錯誤
Azure OpenAI 支援Microsoft Entra ID 驗證。 OpenAIClientBuilder has 方法可設定 credential。 若要提供有效的認證，您可以使用 azure-identity 相依性。
原始程式碼套件 （npm）參考 | | |
Azure OpenAI API 版本支援
Azure OpenAI 中的功能可用性取決於您的目標 REST API 版本。 針對最新的功能，以最新的預覽 API 為目標。
| 最新的 GA API | 最新預覽 API |
|---|---|
2024-10-21 |
2024-10-01-preview |
安裝
npm install openai
驗證
有數種方式可使用 Microsoft Entra ID 權杖向 Azure OpenAI 服務進行驗證。 預設方式是從封裝使用 DefaultAzureCredential 類別 @azure/identity 。
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
然後，系統會將這個物件傳遞至 OpenAIClient 和 AssistantsClient 用戶端建構函式的第二個引數。
不過，為了驗證 AzureOpenAI 用戶端，我們需要從 @azure/identity 套件使用 getBearerTokenProvider 函式。 此函式會建立權杖提供者，AzureOpenAI 會在內部使用此提供者來為每個要求取得權杖。 權杖提供者便會建立，如下所示：
import { AzureOpenAI } from 'openai';
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const credential = new DefaultAzureCredential();
const endpoint = "https://your-azure-openai-resource.com";
const apiVersion = "2024-10-21"
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const client = new AzureOpenAI({
endpoint,
apiVersions,
azureADTokenProvider
});
音訊
文字記錄
import { createReadStream } from "fs";
const result = await client.audio.transcriptions.create({
model: '',
file: createReadStream(audioFilePath),
});
聊天
chat.completions.create
const result = await client.chat.completions.create({ messages, model: '', max_tokens: 100 });
串流
const stream = await client.chat.completions.create({ model: '', messages, max_tokens: 100, stream: true });
Embeddings
const embeddings = await client.embeddings.create({ input, model: '' });
影像產生
const results = await client.images.generate({ prompt, model: '', n, size });
錯誤處理
錯誤碼
| 狀態碼 | 錯誤類型 |
|---|---|
| 400 | Bad Request Error |
| 401 | Authentication Error |
| 403 | Permission Denied Error |
| 404 | Not Found Error |
| 422 | Unprocessable Entity Error |
| 429 | Rate Limit Error |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
| 504 | Gateway Timeout |
重試
根據預設，下列錯誤會使用短暫的指數輪詢自動淘汰兩次：
- 線上錯誤
- 408 要求逾時
- 429 速率限制
>=500 內部錯誤
使用 maxRetries 來設定/停用重試行為：
// Configure the default for all requests:
const client = new AzureOpenAI({
maxRetries: 0, // default is 2
});
// Or, configure per-request:
await client.chat.completions.create({ messages: [{ role: 'user', content: 'How can I get the name of the current day in Node.js?' }], model: '' }, {
maxRetries: 5,
});
連結庫原始程式碼 | 套件 （PyPi）參考 | |
注意
程式庫是由 OpenAI 進行維護。 參照版本歷程記錄來追蹤程式庫的最新更新。
Azure OpenAI API 版本支援
Azure OpenAI 中的功能可用性取決於您的目標 REST API 版本。 針對最新的功能，以最新的預覽 API 為目標。
| 最新的 GA API | 最新預覽 API |
|---|---|
2024-10-21 |
2024-10-01-preview |
安裝
pip install openai
如需最新版本：
pip install openai --upgrade
驗證
import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)
client = AzureOpenAI(
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),
azure_ad_token_provider=token_provider,
api_version="2024-10-21"
)
音訊
audio.speech.create（）
此函式目前需要預覽 API 版本。
設定 api_version="2024-10-01-preview" 為使用此函式。
# from openai import AzureOpenAI
# client = AzureOpenAI()
from pathlib import Path
import os
speech_file_path = Path("speech.mp3")
response = client.audio.speech.create(
model="tts-hd", #Replace with model deployment name
voice="alloy",
input="Testing, testing, 1,2,3."
)
response.write_to_file(speech_file_path)
audio.transcriptions.create（）
# from openai import AzureOpenAI
# client = AzureOpenAI()
audio_file = open("speech1.mp3", "rb")
transcript = client.audio.transcriptions.create(
model="whisper", # Replace with model deployment name
file=audio_file
)
print(transcript)
聊天
chat.completions.create（）
# from openai import AzureOpenAI
# client = AzureOpenAI()
completion = client.chat.completions.create(
model="gpt-4o", # Replace with your model dpeloyment name.
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "When was Microsoft founded?"}
]
)
#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2)
chat.completions.create（） - 串流
# from openai import AzureOpenAI
# client = AzureOpenAI()
completion = client.chat.completions.create(
model="gpt-4o", # Replace with your model dpeloyment name.
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "When was Microsoft founded?"}
],
stream=True
)
for chunk in completion:
if chunk.choices and chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end='',)
chat.completions.create（） - 影像輸入
completion = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image_url",
"image_url": {
"url": "https://raw.githubusercontent.com/MicrosoftDocs/azure-ai-docs/main/articles/ai-services/openai/media/how-to/generated-seattle.png",
}
},
],
}
],
max_tokens=300,
)
print(completion.model_dump_json(indent=2))
Embeddings
embeddings.create（）
# from openai import AzureOpenAI
# client = AzureOpenAI()
embedding = client.embeddings.create(
model="text-embedding-3-large", # Replace with your model deployment name
input="Attenion is all you need",
encoding_format="float"
)
print(embedding)
微調
Batch
影像
images.generate（）
# from openai import AzureOpenAI
# client = AzureOpenAI()
generate_image = client.images.generate(
model="dall-e-3", #replace with your model deployment name
prompt="A rabbit eating pancakes",
n=1,
size="1024x1024",
quality = "hd",
response_format = "url",
style = "vivid"
)
print(generate_image.model_dump_json(indent=2))
完成 (舊版)
completions.create（）
# from openai import AzureOpenAI
# client = AzureOpenAI()
legacy_completion = client.completions.create(
model="gpt-35-turbo-instruct", # Replace with model deployment name
prompt="Hello World!",
max_tokens=100,
temperature=0
)
print(legacy_completion.model_dump_json(indent=2))
錯誤處理
# from openai import AzureOpenAI
# client = AzureOpenAI()
import openai
try:
client.fine_tuning.jobs.create(
model="gpt-4o",
training_file="file-test",
)
except openai.APIConnectionError as e:
print("The server could not be reached")
print(e.__cause__) # an underlying Exception, likely raised within httpx.
except openai.RateLimitError as e:
print("A 429 status code was received; we should back off a bit.")
except openai.APIStatusError as e:
print("Another non-200-range status code was received")
print(e.status_code)
print(e.response)
錯誤碼
| 狀態碼 | 錯誤類型 |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
| N/A | APIConnectionError |
要求標識碼
若要擷取要求的標識碼，您可以使用 _request_id 對應至 x-request-id 響應標頭的屬性。
print(completion._request_id)
print(legacy_completion._request_id)
重試
根據預設，下列錯誤會使用短暫的指數輪詢自動淘汰兩次：
- 線上錯誤
- 408 要求逾時
- 429 速率限制
>=500 內部錯誤
使用 max_retries 來設定/停用重試行為：
# For all requests
from openai import AzureOpenAI
client = AzureOpenAI(
max_retries=0
)
# max retires for specific requests
client.with_options(max_retries=5).chat.completions.create(
messages=[
{
"role": "user",
"content": "When was Microsoft founded?",
}
],
model="gpt-4o",
)
下一步
- 若要查看目前支援哪些模型，請參閱 Azure OpenAI 模型頁面