以下为本文档的中文说明

azure-ai-openai-dotnet 是微软 Azure OpenAI 服务的 .NET SDK 专用开发技能。Azure OpenAI Service 将 OpenAI 的先进大语言模型（包括 GPT-4、GPT-4 Turbo、GPT-4o、GPT-4o mini 等）通过微软 Azure 云平台提供给企业级客户，同时提供了企业所需的安全性、合规性和可靠性保障。该技能指导 .NET 开发者充分利用这一服务构建智能应用。使用场景包括：在 C# / .NET 应用程序中集成 Azure OpenAI 的聊天补全功能构建 AI 对话助手、利用 Azure OpenAI 的文本生成、文本摘要、语言翻译和情感分析等能力实现各种 NLP 任务、结合企业私有数据构建 RAG（检索增强生成）应用以提供基于业务知识的智能问答。核心特点包括：涵盖 Azure OpenAI 官方 .NET 客户端库（Azure.AI.OpenAI NuGet 包）的初始化配置、依赖注入注册和最佳使用方式；提供完整的同步和异步 API 调用代码示例；支持调用聊天补全（Chat Completion）API 使用系统和用户提示、文本嵌入（Embeddings）API 实现语义搜索、图像生成（DALL-E 3）API 创建视觉内容等多种模型能力；包含 Token 消耗的精确计算方法和大致的 API 调用成本估算公式；提供流式处理（Streaming）响应的标准实现模式，实现打字机效果的实时文本输出；支持 Azure AD（Microsoft Entra ID）托管身份认证和传统的 API Key 认证两种方式；包含内容过滤（Content Filtering）配置和负责任的 AI 使用指南。

Azure.AI.OpenAI (.NET)

Client library for Azure OpenAI Service providing access to OpenAI models including GPT-4, GPT-4o, embeddings, DALL-E, and Whisper.

Installation

dotnet add package Azure.AI.OpenAI

# For OpenAI (non-Azure) compatibility
dotnet add package OpenAI

Current Version: 2.1.0 (stable)

Environment Variables

AZURE_OPENAI_ENDPOINT=https://<resource-name>.openai.azure.com
AZURE_OPENAI_API_KEY=<api-key>                    # For key-based auth
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini          # Your deployment name

Client Hierarchy

AzureOpenAIClient (top-level)
├── GetChatClient(deploymentName)      → ChatClient
├── GetEmbeddingClient(deploymentName) → EmbeddingClient
├── GetImageClient(deploymentName)     → ImageClient
├── GetAudioClient(deploymentName)     → AudioClient
└── GetAssistantClient()               → AssistantClient

Authentication

API Key Authentication

using Azure;
using Azure.AI.OpenAI;

AzureOpenAIClient client = new(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")!));

Microsoft Entra ID (Recommended for Production)

using Azure.Identity;
using Azure.AI.OpenAI;

AzureOpenAIClient client = new(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
    new DefaultAzureCredential());

Using OpenAI SDK Directly with Azure

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default");

ChatClient client = new(
    model: "gpt-4o-mini",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE.openai.azure.com/openai/v1")
    });

Chat Completions

Basic Chat

using Azure.AI.OpenAI;
using OpenAI.Chat;

AzureOpenAIClient azureClient = new(
    new Uri(endpoint),
    new DefaultAzureCredential());

ChatClient chatClient = azureClient.GetChatClient("gpt-4o-mini");

ChatCompletion completion = chatClient.CompleteChat(
[
    new SystemChatMessage("You are a helpful assistant."),
    new UserChatMessage("What is Azure OpenAI?")
]);

Console.WriteLine(completion.Content[0].Text);

Async Chat

ChatCompletion completion = await chatClient.CompleteChatAsync(
[
    new SystemChatMessage("You are a helpful assistant."),
    new UserChatMessage("Explain cloud computing in simple terms.")
]);

Console.WriteLine($"Response: {completion.Content[0].Text}");
Console.WriteLine($"Tokens used: {completion.Usage.TotalTokenCount}");

Streaming Chat

await foreach (StreamingChatCompletionUpdate update 
    in chatClient.CompleteChatStreamingAsync(messages))
{
    if (update.ContentUpdate.Count > 0)
    {
        Console.Write(update.ContentUpdate[0].Text);
    }
}

Chat with Options

ChatCompletionOptions options = new()
{
    MaxOutputTokenCount = 1000,
    Temperature = 0.7f,
    TopP = 0.95f,
    FrequencyPenalty = 0,
    PresencePenalty = 0
};

ChatCompletion completion = await chatClient.CompleteChatAsync(messages, options);

Multi-turn Conversation

List<ChatMessage> messages = new()
{
    new SystemChatMessage("You are a helpful assistant."),
    new UserChatMessage("Hi, can you help me?"),
    new AssistantChatMessage("Of course! What do you need help with?"),
    new UserChatMessage("What's the capital of France?")
};

ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
messages.Add(new AssistantChatMessage(completion.Content[0].Text));

Structured Outputs (JSON Schema)

using System.Text.Json;

ChatCompletionOptions options = new()
{
    ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
        jsonSchemaFormatName: "math_reasoning",
 
       jsonSchema: BinaryData.FromBytes("""
            {
                "type": "object",
                "properties": {
                    "steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "explanation": { "type": "string" },
                                "output": { "type": "string" }
                            },
                            "required": ["explanation", "output"],
                            "additionalProperties": false
                        }
                    },
                    "final_answer": { "type": "string" }
                },
                "required": ["steps", "final_answer"],
                "additionalProperties": false
            }
            """u8.ToArray()),
        jsonSchemaIsStrict: true)
};

ChatCompletion completion = await chatClient.CompleteChatAsync(
    [new UserChatMessage("How can I solve 8x + 7 = -23?")],
    options);

using JsonDocument json = JsonDocument.Parse(completion.Content[0].Text);
Console.WriteLine($"Answer: {json.RootElement.GetProperty("final_answer")}");

Reasoning Models (o1, o4-mini)

ChatCompletionOptions options = new()
{
    ReasoningEffortLevel = ChatReasoningEffortLevel.Low,
    MaxOutputTokenCount = 100000
};

ChatCompletion completion = await chatClient.CompleteChatAsync(
[
    new DeveloperChatMessage("You are a helpful assistant"),
    new UserChatMessage("Explain the theory of relativity")
], options);

Azure AI Search Integration (RAG)

using Azure.AI.OpenAI.Chat;

#pragma warning disable AOAI001

ChatCompletionOptions options = new();
options.AddDataSource(new AzureSearchChatDataSource()
{
    Endpoint = new Uri(searchEndpoint),
    IndexName = searchIndex,
    Authentication = DataSourceAuthentication.FromApiKey(searchKey)
});

ChatCompletion completion = await chatClient.CompleteChatAsync(
    [new UserChatMessage("What health plans are available?")],
    options);

ChatMessageContext context = completion.GetMessageContext();
if (context?.Intent is not null)
{
    Console.WriteLine($"Intent: {context.Intent}");
}
foreach (ChatCitation citation in context?.Citations ?? [])
{
    Console.WriteLine($"Citation: {citation.Content}");
}

Embeddings

using OpenAI.Embeddings;

EmbeddingClient embeddingClient = azureClient.GetEmbeddingClient("text-embedding-ada-002");

OpenAIEmbedding embedding = await embeddingClient.GenerateEmbeddingAsync("Hello, world!");
ReadOnlyMemory<float> vector = embedding.ToFloats();

Console.WriteLine($"Embedding dimensions: {vector.Length}");

Batch Embeddings

List<string> inputs = new()
{
    "First document text",
    "Second document text",
    "Third document text"
};

OpenAIEmbeddingCollection embeddings = await embeddingClient.GenerateEmbeddingsAsync(inputs);

foreach (OpenAIEmbedding emb in embeddings)
{
    Console.WriteLine($"Index {emb.Index}: {emb.ToFloats().Length} dimensions");
}

Image Generation (DALL-E)

using OpenAI.Images;

ImageClient imageClient = azureClient.GetImageClient("dall-e-3");

GeneratedImage image = await imageClient.GenerateImageAsync(
    "A futuristic city skyline at sunset",
    new ImageGenerationOptions
    {
        Size = GeneratedImageSize.W1024xH1024,
        Quality = GeneratedImageQuality.High,
        Style = GeneratedImageStyle.Vivid
    });

Console.WriteLine($"Image URL: {image.ImageUri}");

Audio (Whisper)

Transcription

using OpenAI.Audio;

AudioClient audioClient = azureClient.GetAudioClient("whisper");

AudioTranscription transcription = await audioClient.TranscribeAudioAsync(
    "audio.mp3",
    new AudioTranscriptionOptions
    {
        ResponseFormat = AudioTranscriptionFormat.Verbose,
        Language = "en"
    });

Console.WriteLine(transcription.Text);

Text-to-Speech

BinaryData speech = await audioClient.GenerateSpeechAsync(
    "Hello, welcome to Azure OpenAI!",
  
  GeneratedSpeechVoice.Alloy,
    new SpeechGenerationOptions
    {
        SpeedRatio = 1.0f,
        ResponseFormat = GeneratedSpeechFormat.Mp3
    });

await File.WriteAllBytesAsync("output.mp3", speech.ToArray());

Function Calling (Tools)

ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool(
    functionName: "get_current_weather",
    functionDescription: "Get the current weather in a given location",
    functionParameters: BinaryData.FromString("""
        {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
        """));

ChatCompletionOptions options = new()
{
    Tools = { getCurrentWeatherTool }
};

ChatCompletion completion = await chatClient.CompleteChatAsync(
    [new UserChatMessage("What's the weather in Seattle?")],
    options);

if (completion.FinishReason == ChatFinishReason.ToolCalls)
{
    foreach (ChatToolCall toolCall in completion.ToolCalls)
    {
        Console.WriteLine($"Function: {toolCall.FunctionName}");
        Console.WriteLine($"Arguments: {toolCall.FunctionArguments}");
    }
}

Key Types Reference

Type Purpose
AzureOpenAIClient Top-level client for Azure OpenAI
ChatClient Chat completions
EmbeddingClient Text embeddings
ImageClient Image generation (DALL-E)
AudioClient Audio transcription/TTS
ChatCompletion Chat response
ChatCompletionOptions Request configuration
StreamingChatCompletionUpdate Streaming response chunk
ChatMessage Base message type
SystemChatMessage System prompt
UserChatMessage User input
AssistantChatMessage Assistant response
DeveloperChatMessage Developer message (reasoning models)
ChatTool Function/tool definition
ChatToolCall Tool invocation request

Best Practices

  1. Use Entra ID in production — Avoid API keys; use DefaultAzureCredential
  2. Reuse client instances — Create once, share across requests
  3. Handle rate limits — Implement exponential backoff for 429 errors
  4. Stream for long responses — Use CompleteChatStreamingAsync for better UX
  5. Set appropriate timeouts — Long completions may need extended timeouts
  6. Use structured outputs — JSON schema ensures consistent response format
  7. Monitor token usage — Track completion.Usage for cost management
  8. Validate tool calls — Always validate function arguments before execution

Error Handling

using Azure;

try
{
    ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Rate limited. Retry after delay.");
    await Task.Delay(TimeSpan.FromSeconds(10));
}
catch (RequestFailedException ex) when (ex.Status == 400)
{
    Console.WriteLine($"Bad request: {ex.Message}");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Azure OpenAI error: {ex.Status} - {ex.Message}");
}

Related SDKs

SDK Purpose Install
Azure.AI.OpenAI Azure OpenAI client (this SDK) dotnet add package Azure.AI.OpenAI
OpenAI OpenAI compatibility dotnet add package OpenAI
Azure.Identity Authentication dotnet add package Azure.Identity
Azure.Search.Documents AI Search for RAG dotnet add package Azure.Search.Documents

Reference Links

Resource URL
NuGet Package https://www.nuget.org/packages/Azure.AI.OpenAI
API Reference https://learn.microsoft.com/dotnet/api/azure.ai.openai
Migration Guide (1.0→2.0) https://learn.microsoft.com/azure/ai-services/openai/how-to/dotnet-migration
Quicksta
rt https://learn.microsoft.com/azure/ai-services/openai/quickstart
GitHub Source https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/openai/Azure.AI.OpenAI

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
# azure # 人工智能 # flask
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

写Agent还要重复封装工具？一套MCP多服务方案，3个能力让AI自动查地图、读写文件、操控浏览器

avatar AI Agent技术社区

75 个 Agent 怎么协作？我的五层演化之路

有人问我："你养了 75 个 AI Agent（截至 7 月中旬，含活跃和实验性角色），它们之间到底是怎么互动的？A 做完的事情 B 怎么接手？这个问题特别好。因为我一开始也没想清楚。我最初的想法很简单：给每个 Agent 配好角色和 Skill，它们就能自己配合了。后来发现远远不够——Agent A 写了个文件，Agent B 死活读不到；Agent B 做完了一步，Agent C 不知道 B

avatar AI Agent技术社区

AI Agent 可观测性：破解多步推理黑盒的技术实践

核心价值：可观测性不仅是“调试工具”，更是构建可靠、可信、可控 AI Agent 系统的基石。技术趋势：标准化（OpenTelemetry for LLMs）、自动化（AI 监控 AI）、实时化（流式处理）。行动建议：从 Day 1 开始设计可观测性，采用“日志-指标-追踪”三位一体方案，并逐步向可解释性深化。

avatar AI Agent技术社区