 实战指南：在 Agentic Awesome Skills 中构建 .NET 智能应用)
Azure.AI.OpenAI (.NET) 实战指南在 Agentic Awesome Skills 中构建 .NET 智能应用【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills本文是 Agentic Awesome SkillsAAS技能库中 azure-ai-openai-dotnet 技能的完整技术指南。它围绕 Azure OpenAI Service 的 .NET 官方客户端库系统讲解如何完成 SDK 安装、环境变量配置、认证方式选型、聊天补全、结构化输出、RAG 检索增强、嵌入、图像生成、语音合成与函数调用等能力。读完本文你将掌握用Azure.AI.OpenAI2.x 从零搭建 .NET 智能应用的完整链路并理解 AAS 中该技能被标记为risk: critical的原因及其适用边界。技能定位AAS 目录中的 .NET Azure OpenAI 能力单元在 AAS 插件 agentic-awesome-skills-claude 的技能目录中本技能以SKILL.md的形式被组织为独立能力单元其 frontmatter 元数据如下name: azure-ai-openai-dotnet description: Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. risk: critical source: community date_added: 2026-02-27risk: critical表示该技能涉及云资源调用、密钥管理与生产级代码路径Agent 使用前必须严格校验输入与权限边界source: community表明它来自社区贡献质量遵循 AAS 的社区规范date_added记录技能入库时间便于追溯版本演进。AAS 将技能按语言与平台横向铺开与本文同目录下还存在 azure-ai-projects-dotnet面向 Azure AI Foundry 项目级操作的高级 SDK等姊妹技能本文聚焦最底层、最通用的Azure.AI.OpenAI客户端。安装与版本说明技能文档指定的安装方式为 NuGet 包管理dotnet add package Azure.AI.OpenAI # For OpenAI (non-Azure) compatibility dotnet add package OpenAI要点主包Azure.AI.OpenAI面向 Azure OpenAI Service 的官方客户端文档记录当前稳定版本为2.1.0兼容包OpenAI当你的代码需要同时兼容 OpenAI 官方端点非 Azure 环境时使用。事实上Azure.AI.OpenAI2.x 构建在OpenAISDK 之上二者共享OpenAI.Chat、OpenAI.Embeddings、OpenAI.Images、OpenAI.Audio等命名空间这也是后续代码中类型同时来自两个程序集的原因。环境变量与连接配置在编写任何代码之前先建立统一的连接配置。技能文档给出了三组环境变量AZURE_OPENAI_ENDPOINThttps://resource-name.openai.azure.com AZURE_OPENAI_API_KEYapi-key # For key-based auth AZURE_OPENAI_DEPLOYMENT_NAMEgpt-4o-mini # Your deployment name其中变量作用说明AZURE_OPENAI_ENDPOINT服务端点形如https://资源名.openai.azure.com在 Azure 门户的Keys and Endpoint页获取AZURE_OPENAI_API_KEY密钥认证凭证仅用于密钥认证路径生产环境推荐改用 Entra ID见下文AZURE_OPENAI_DEPLOYMENT_NAME部署名对应你在 Azure OpenAI Studio 中创建的模型部署名称例如gpt-4o-mini提示在 .NET 中可通过Environment.GetEnvironmentVariable(...)读取在 AAS/Agent 场景下更建议结合密钥管理方案注入环境变量避免把密钥写入代码仓库。客户端层级架构一个顶层客户端五个子客户端AzureOpenAIClient采用工厂 子客户端的层级设计技能文档用如下结构图概括AzureOpenAIClient (top-level) ├── GetChatClient(deploymentName) → ChatClient ├── GetEmbeddingClient(deploymentName) → EmbeddingClient ├── GetImageClient(deploymentName) → ImageClient ├── GetAudioClient(deploymentName) → AudioClient └── GetAssistantClient() → AssistantClient顶层AzureOpenAIClient负责认证与端点配置所有子客户端都由它派生共享同一套凭证每个子客户端对应一种模型能力ChatClient对话补全、EmbeddingClient文本嵌入、ImageClient图像生成、AudioClient语音转写/合成、AssistantClientAssistants API子客户端通过部署名deployment name定位具体模型例如GetChatClient(gpt-4o-mini)。这一层级结构直接决定了复用客户端实例的最佳实践顶层客户端创建一次即可反复派生子客户端避免重复认证握手。三种认证方式技能文档覆盖了从开发到生产的完整认证路径。1. API Key 认证快速开始using Azure; using Azure.AI.OpenAI; AzureOpenAIClient client new( new Uri(Environment.GetEnvironmentVariable(AZURE_OPENAI_ENDPOINT)!), new AzureKeyCredential(Environment.GetEnvironmentVariable(AZURE_OPENAI_API_KEY)!));AzureKeyCredential来自Azure.Core通过using Azure;引入适合本地开发与快速原型验证。2. Microsoft Entra ID生产推荐using Azure.Identity; using Azure.AI.OpenAI; AzureOpenAIClient client new( new Uri(Environment.GetEnvironmentVariable(AZURE_OPENAI_ENDPOINT)!), new DefaultAzureCredential());DefaultAzureCredential会按顺序尝试多种身份源环境变量、Azure CLI 登录、托管身份、Visual Studio 凭据等在本地开发与云端部署之间无缝切换无需修改代码。技能文档明确将 Entra ID 列为生产环境首选因为它避免了静态密钥的泄露与轮换成本。3. 使用 OpenAI SDK 直连 Azure 端点当你想用原生OpenAI命名空间的ChatClient例如为多环境切换代码路径时可以通过自定义认证策略接入 Azureusing 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) });关键点BearerTokenPolicy携带 Entra ID 令牌作用域为https://cognitiveservices.azure.com/.defaultOpenAIClientOptions.Endpoint必须指向 Azure 的/openai/v1兼容路径#pragma warning disable OPENAI001用于抑制 SDK 对自定义认证策略场景的兼容性警告。聊天补全五种典型调用形态ChatClient是使用频率最高的子客户端技能文档给出了五种典型场景。基础对话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);注意CompleteChat接受IEnumerableChatMessage这里直接以内联集合表达式传入SystemChatMessage与UserChatMessage。异步对话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});异步版本返回ChatCompletion其中Usage.TotalTokenCount可用于 Token 用量监控对应最佳实践第 7 条。流式输出await foreach (StreamingChatCompletionUpdate update in chatClient.CompleteChatStreamingAsync(messages)) { if (update.ContentUpdate.Count 0) { Console.Write(update.ContentUpdate[0].Text); } }CompleteChatStreamingAsync返回IAsyncEnumerableStreamingChatCompletionUpdate逐块推送增量文本适合长回答场景以改善交互体验对应最佳实践第 4 条。带采样参数配置ChatCompletionOptions options new() { MaxOutputTokenCount 1000, Temperature 0.7f, TopP 0.95f, FrequencyPenalty 0, PresencePenalty 0 }; ChatCompletion completion await chatClient.CompleteChatAsync(messages, options);参数类型作用MaxOutputTokenCountint输出 Token 上限控制回答长度Temperaturefloat采样温度值越高随机性越强TopPfloat核采样概率阈值与 Temperature 二选一调节即可FrequencyPenaltyfloat频率惩罚抑制重复表述PresencePenaltyfloat存在惩罚鼓励引入新话题多轮对话ListChatMessage 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(Whats the capital of France?) }; ChatCompletion completion await chatClient.CompleteChatAsync(messages); messages.Add(new AssistantChatMessage(completion.Content[0].Text));多轮对话的本质是把历史消息含系统、用户、助手消息整体重新发送每次请求后把新的助手回复追加回messages形成上下文延续。结构化输出JSON Schema 约束为了让模型输出严格符合程序可解析的结构ChatResponseFormat.CreateJsonSchemaFormat支持以 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)});实操要点jsonSchemaFormatName为该格式命名jsonSchema使用BinaryData.FromBytes(...u8.ToArray())传入 UTF-8 编码的 Schema 文本C# 11 原始字符串字面量 u8后缀jsonSchemaIsStrict: true开启严格模式——Schema 中必须显式声明additionalProperties: false并列出所有required字段解析时用JsonDocument读取结构化字段从而避免手工正则解析模型输出。推理模型o1 / o4-mini针对 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);ReasoningEffortLevel控制推理投入Low/Medium/High值越高推理链越长、耗时与 Token 成本越高MaxOutputTokenCount需要为推理模型的思考过程预留较大空间示例中给出 100000推理模型通常使用DeveloperChatMessage作为系统级指令载体替代传统的SystemChatMessage。接入 Azure AI Search 实现 RAG技能文档演示了如何通过AddDataSource将 Azure AI Search 索引挂载为知识源让模型基于检索到的文档作答并返回引用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}); }关键类型类型作用AzureSearchChatDataSource声明 Azure AI Search 数据源端点、索引名、认证DataSourceAuthentication.FromApiKey以 API Key 认证搜索服务ChatMessageContext从补全结果中提取的消息上下文ChatCitation模型作答时引用的文档片段可溯源校验GetMessageContext()返回的Intent与Citations让 RAG 结果可解释、可审计——这在企业合规场景中是关键能力。#pragma warning disable AOAI001用于抑制对 Azure 扩展 API 的警告。嵌入单条与批量EmbeddingClient用于将文本转为向量是语义检索与向量库写入的前置步骤。单条嵌入using OpenAI.Embeddings; EmbeddingClient embeddingClient azureClient.GetEmbeddingClient(text-embedding-ada-002); OpenAIEmbedding embedding await embeddingClient.GenerateEmbeddingAsync(Hello, world!); ReadOnlyMemoryfloat vector embedding.ToFloats(); Console.WriteLine($Embedding dimensions: {vector.Length});批量嵌入Liststring 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); }embedding.ToFloats()将嵌入结果转为ReadOnlyMemoryfloat可直接用于余弦相似度计算或写入向量数据库批量接口返回OpenAIEmbeddingCollection每个元素的Index与输入列表顺序对应。图像生成DALL-Eusing 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});ImageGenerationOptions支持配置Size输出尺寸如W1024xH1024Quality生成质量High/StandardStyle风格倾向Vivid/Natural。GeneratedImage.ImageUri返回生成的图片地址可进一步下载或持久化。音频转写与语音合成AudioClient同时覆盖语音转文本Whisper与文本转语音TTS两条链路。语音转写Whisperusing 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);ResponseFormat.Verbose返回包含置信度、分段时间戳等丰富信息的转写结果Language可显式指定音频语言以提升准确率。文本转语音TTSBinaryData 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());支持预设音色如AlloySpeedRatio控制语速ResponseFormat.Mp3指定输出编码返回的BinaryData可直接落盘为音频文件。函数调用Tools函数调用让模型能够决定何时调用哪个工具是实现 Agent 化应用的核心机制。技能文档以天气查询为例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(Whats 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}); } }完整调用流程定义工具ChatTool.CreateFunctionTool传入函数名、描述与 JSON Schema 参数定义含required、enum等约束注册工具将ChatTool加入ChatCompletionOptions.Tools集合接收调用请求当completion.FinishReason ChatFinishReason.ToolCalls时从completion.ToolCalls读取模型要求调用的函数名与参数执行并回传本地执行函数后把工具结果以新的消息回合回传给模型模型据此生成最终答复。安全提醒从模型收到的FunctionArguments是字符串 JSON必须校验后再执行对应最佳实践第 8 条防止注入恶意参数。关键类型速查表类型用途AzureOpenAIClient顶层客户端Azure OpenAI 的入口ChatClient聊天补全EmbeddingClient文本嵌入ImageClient图像生成DALL-EAudioClient音频转写 / TTSChatCompletion聊天响应对象ChatCompletionOptions请求配置采样参数、工具、数据源等StreamingChatCompletionUpdate流式响应分块ChatMessage消息基类型SystemChatMessage系统提示词UserChatMessage用户输入AssistantChatMessage助手回复DeveloperChatMessage开发者消息推理模型ChatTool函数 / 工具定义ChatToolCall工具调用请求最佳实践清单技能文档总结了 8 条生产级实践生产环境使用 Entra ID—— 避免 API Key改用DefaultAzureCredential复用客户端实例—— 顶层客户端创建一次跨请求共享天然契合上文的客户端层级设计处理限流—— 对 429 响应实现指数退避重试长回答用流式——CompleteChatStreamingAsync提升用户体验设置合理超时—— 长补全任务需要延长超时时间使用结构化输出—— JSON Schema 保证响应格式一致便于程序消费监控 Token 用量—— 跟踪completion.Usage控制成本校验工具调用—— 执行前必须校验函数参数。错误处理模式SDK 将服务端错误统一包装为RequestFailedException可按 HTTP 状态码分治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}); }状态码速查状态码含义处理建议429触发限流退避后重试可结合指数退避400请求参数错误检查消息结构、Schema、部署名其他服务端错误记录状态码与消息排查配额/网络相关 SDK 生态与扩展方向SDK用途安装命令Azure.AI.OpenAIAzure OpenAI 客户端本文主体dotnet add package Azure.AI.OpenAIOpenAIOpenAI 兼容客户端dotnet add package OpenAIAzure.Identity认证Entra IDdotnet add package Azure.IdentityAzure.Search.DocumentsAI Search 客户端用于 RAGdotnet add package Azure.Search.Documents在此基础上可进一步扩展项目级编排进阶场景可参考 AAS 中的 azure-ai-projects-dotnet 技能它面向 Azure AI Foundry 项目覆盖 agents、connections、datasets、deployments、evaluations、indexes 等高层操作可与本文的底层客户端组合使用官方参考资料本文所用 API 的 NuGet 包页面、Microsoft Learn API 参考、1.0→2.0 迁移指南以及 Quickstart 均可通过官方文档渠道获取具体版本行为以你安装的 SDK 版本为准文档记录 2.1.0 为当前稳定版。适用边界与注意事项作为 AAS 技能本文所述内容的使用边界如下仅在任务明确匹配上述能力范围时使用聊天、嵌入、图像、音频、助手、RAG 等输出结果不能替代环境特定环境的验证、测试或专家评审——尤其是涉及生产部署、合规与安全审查的场景当所需输入、权限、安全边界或成功标准缺失时应暂停并请求澄清而不是猜测默认值继续执行认证凭证API Key 或 Entra ID 权限属于高敏感信息在 Agent 工作流中应遵循最小权限原则与密钥管理规范。结合技能文档与 AAS 目录结构可以推断本技能适合作为 Agent 在处理 .NET 项目 Azure OpenAI 集成 类任务时的能力说明书Agent 可按本文的代码骨架快速生成可运行的集成代码再交由开发者针对具体环境验证。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Azure.AI.OpenAI (.NET) 实战指南在 Agentic Awesome Skills 中构建 .NET 智能应用【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills本文是 Agentic Awesome SkillsAAS技能库中 azure-ai-openai-dotnet 技能的完整技术指南。它围绕 Azure OpenAI Service 的 .NET 官方客户端库系统讲解如何完成 SDK 安装、环境变量配置、认证方式选型、聊天补全、结构化输出、RAG 检索增强、嵌入、图像生成、语音合成与函数调用等能力。读完本文你将掌握用Azure.AI.OpenAI2.x 从零搭建 .NET 智能应用的完整链路并理解 AAS 中该技能被标记为risk: critical的原因及其适用边界。技能定位AAS 目录中的 .NET Azure OpenAI 能力单元在 AAS 插件 agentic-awesome-skills-claude 的技能目录中本技能以SKILL.md的形式被组织为独立能力单元其 frontmatter 元数据如下name: azure-ai-openai-dotnet description: Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. risk: critical source: community date_added: 2026-02-27risk: critical表示该技能涉及云资源调用、密钥管理与生产级代码路径Agent 使用前必须严格校验输入与权限边界source: community表明它来自社区贡献质量遵循 AAS 的社区规范date_added记录技能入库时间便于追溯版本演进。AAS 将技能按语言与平台横向铺开与本文同目录下还存在 azure-ai-projects-dotnet面向 Azure AI Foundry 项目级操作的高级 SDK等姊妹技能本文聚焦最底层、最通用的Azure.AI.OpenAI客户端。安装与版本说明技能文档指定的安装方式为 NuGet 包管理dotnet add package Azure.AI.OpenAI # For OpenAI (non-Azure) compatibility dotnet add package OpenAI要点主包Azure.AI.OpenAI面向 Azure OpenAI Service 的官方客户端文档记录当前稳定版本为2.1.0兼容包OpenAI当你的代码需要同时兼容 OpenAI 官方端点非 Azure 环境时使用。事实上Azure.AI.OpenAI2.x 构建在OpenAISDK 之上二者共享OpenAI.Chat、OpenAI.Embeddings、OpenAI.Images、OpenAI.Audio等命名空间这也是后续代码中类型同时来自两个程序集的原因。环境变量与连接配置在编写任何代码之前先建立统一的连接配置。技能文档给出了三组环境变量AZURE_OPENAI_ENDPOINThttps://resource-name.openai.azure.com AZURE_OPENAI_API_KEYapi-key # For key-based auth AZURE_OPENAI_DEPLOYMENT_NAMEgpt-4o-mini # Your deployment name其中变量作用说明AZURE_OPENAI_ENDPOINT服务端点形如https://资源名.openai.azure.com在 Azure 门户的Keys and Endpoint页获取AZURE_OPENAI_API_KEY密钥认证凭证仅用于密钥认证路径生产环境推荐改用 Entra ID见下文AZURE_OPENAI_DEPLOYMENT_NAME部署名对应你在 Azure OpenAI Studio 中创建的模型部署名称例如gpt-4o-mini提示在 .NET 中可通过Environment.GetEnvironmentVariable(...)读取在 AAS/Agent 场景下更建议结合密钥管理方案注入环境变量避免把密钥写入代码仓库。客户端层级架构一个顶层客户端五个子客户端AzureOpenAIClient采用工厂 子客户端的层级设计技能文档用如下结构图概括AzureOpenAIClient (top-level) ├── GetChatClient(deploymentName) → ChatClient ├── GetEmbeddingClient(deploymentName) → EmbeddingClient ├── GetImageClient(deploymentName) → ImageClient ├── GetAudioClient(deploymentName) → AudioClient └── GetAssistantClient() → AssistantClient顶层AzureOpenAIClient负责认证与端点配置所有子客户端都由它派生共享同一套凭证每个子客户端对应一种模型能力ChatClient对话补全、EmbeddingClient文本嵌入、ImageClient图像生成、AudioClient语音转写/合成、AssistantClientAssistants API子客户端通过部署名deployment name定位具体模型例如GetChatClient(gpt-4o-mini)。这一层级结构直接决定了复用客户端实例的最佳实践顶层客户端创建一次即可反复派生子客户端避免重复认证握手。三种认证方式技能文档覆盖了从开发到生产的完整认证路径。1. API Key 认证快速开始using Azure; using Azure.AI.OpenAI; AzureOpenAIClient client new( new Uri(Environment.GetEnvironmentVariable(AZURE_OPENAI_ENDPOINT)!), new AzureKeyCredential(Environment.GetEnvironmentVariable(AZURE_OPENAI_API_KEY)!));AzureKeyCredential来自Azure.Core通过using Azure;引入适合本地开发与快速原型验证。2. Microsoft Entra ID生产推荐using Azure.Identity; using Azure.AI.OpenAI; AzureOpenAIClient client new( new Uri(Environment.GetEnvironmentVariable(AZURE_OPENAI_ENDPOINT)!), new DefaultAzureCredential());DefaultAzureCredential会按顺序尝试多种身份源环境变量、Azure CLI 登录、托管身份、Visual Studio 凭据等在本地开发与云端部署之间无缝切换无需修改代码。技能文档明确将 Entra ID 列为生产环境首选因为它避免了静态密钥的泄露与轮换成本。3. 使用 OpenAI SDK 直连 Azure 端点当你想用原生OpenAI命名空间的ChatClient例如为多环境切换代码路径时可以通过自定义认证策略接入 Azureusing 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) });关键点BearerTokenPolicy携带 Entra ID 令牌作用域为https://cognitiveservices.azure.com/.defaultOpenAIClientOptions.Endpoint必须指向 Azure 的/openai/v1兼容路径#pragma warning disable OPENAI001用于抑制 SDK 对自定义认证策略场景的兼容性警告。聊天补全五种典型调用形态ChatClient是使用频率最高的子客户端技能文档给出了五种典型场景。基础对话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);注意CompleteChat接受IEnumerableChatMessage这里直接以内联集合表达式传入SystemChatMessage与UserChatMessage。异步对话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});异步版本返回ChatCompletion其中Usage.TotalTokenCount可用于 Token 用量监控对应最佳实践第 7 条。流式输出await foreach (StreamingChatCompletionUpdate update in chatClient.CompleteChatStreamingAsync(messages)) { if (update.ContentUpdate.Count 0) { Console.Write(update.ContentUpdate[0].Text); } }CompleteChatStreamingAsync返回IAsyncEnumerableStreamingChatCompletionUpdate逐块推送增量文本适合长回答场景以改善交互体验对应最佳实践第 4 条。带采样参数配置ChatCompletionOptions options new() { MaxOutputTokenCount 1000, Temperature 0.7f, TopP 0.95f, FrequencyPenalty 0, PresencePenalty 0 }; ChatCompletion completion await chatClient.CompleteChatAsync(messages, options);参数类型作用MaxOutputTokenCountint输出 Token 上限控制回答长度Temperaturefloat采样温度值越高随机性越强TopPfloat核采样概率阈值与 Temperature 二选一调节即可FrequencyPenaltyfloat频率惩罚抑制重复表述PresencePenaltyfloat存在惩罚鼓励引入新话题多轮对话ListChatMessage 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(Whats the capital of France?) }; ChatCompletion completion await chatClient.CompleteChatAsync(messages); messages.Add(new AssistantChatMessage(completion.Content[0].Text));多轮对话的本质是把历史消息含系统、用户、助手消息整体重新发送每次请求后把新的助手回复追加回messages形成上下文延续。结构化输出JSON Schema 约束为了让模型输出严格符合程序可解析的结构ChatResponseFormat.CreateJsonSchemaFormat支持以 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)});实操要点jsonSchemaFormatName为该格式命名jsonSchema使用BinaryData.FromBytes(...u8.ToArray())传入 UTF-8 编码的 Schema 文本C# 11 原始字符串字面量 u8后缀jsonSchemaIsStrict: true开启严格模式——Schema 中必须显式声明additionalProperties: false并列出所有required字段解析时用JsonDocument读取结构化字段从而避免手工正则解析模型输出。推理模型o1 / o4-mini针对 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);ReasoningEffortLevel控制推理投入Low/Medium/High值越高推理链越长、耗时与 Token 成本越高MaxOutputTokenCount需要为推理模型的思考过程预留较大空间示例中给出 100000推理模型通常使用DeveloperChatMessage作为系统级指令载体替代传统的SystemChatMessage。接入 Azure AI Search 实现 RAG技能文档演示了如何通过AddDataSource将 Azure AI Search 索引挂载为知识源让模型基于检索到的文档作答并返回引用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}); }关键类型类型作用AzureSearchChatDataSource声明 Azure AI Search 数据源端点、索引名、认证DataSourceAuthentication.FromApiKey以 API Key 认证搜索服务ChatMessageContext从补全结果中提取的消息上下文ChatCitation模型作答时引用的文档片段可溯源校验GetMessageContext()返回的Intent与Citations让 RAG 结果可解释、可审计——这在企业合规场景中是关键能力。#pragma warning disable AOAI001用于抑制对 Azure 扩展 API 的警告。嵌入单条与批量EmbeddingClient用于将文本转为向量是语义检索与向量库写入的前置步骤。单条嵌入using OpenAI.Embeddings; EmbeddingClient embeddingClient azureClient.GetEmbeddingClient(text-embedding-ada-002); OpenAIEmbedding embedding await embeddingClient.GenerateEmbeddingAsync(Hello, world!); ReadOnlyMemoryfloat vector embedding.ToFloats(); Console.WriteLine($Embedding dimensions: {vector.Length});批量嵌入Liststring 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); }embedding.ToFloats()将嵌入结果转为ReadOnlyMemoryfloat可直接用于余弦相似度计算或写入向量数据库批量接口返回OpenAIEmbeddingCollection每个元素的Index与输入列表顺序对应。图像生成DALL-Eusing 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});ImageGenerationOptions支持配置Size输出尺寸如W1024xH1024Quality生成质量High/StandardStyle风格倾向Vivid/Natural。GeneratedImage.ImageUri返回生成的图片地址可进一步下载或持久化。音频转写与语音合成AudioClient同时覆盖语音转文本Whisper与文本转语音TTS两条链路。语音转写Whisperusing 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);ResponseFormat.Verbose返回包含置信度、分段时间戳等丰富信息的转写结果Language可显式指定音频语言以提升准确率。文本转语音TTSBinaryData 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());支持预设音色如AlloySpeedRatio控制语速ResponseFormat.Mp3指定输出编码返回的BinaryData可直接落盘为音频文件。函数调用Tools函数调用让模型能够决定何时调用哪个工具是实现 Agent 化应用的核心机制。技能文档以天气查询为例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(Whats 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}); } }完整调用流程定义工具ChatTool.CreateFunctionTool传入函数名、描述与 JSON Schema 参数定义含required、enum等约束注册工具将ChatTool加入ChatCompletionOptions.Tools集合接收调用请求当completion.FinishReason ChatFinishReason.ToolCalls时从completion.ToolCalls读取模型要求调用的函数名与参数执行并回传本地执行函数后把工具结果以新的消息回合回传给模型模型据此生成最终答复。安全提醒从模型收到的FunctionArguments是字符串 JSON必须校验后再执行对应最佳实践第 8 条防止注入恶意参数。关键类型速查表类型用途AzureOpenAIClient顶层客户端Azure OpenAI 的入口ChatClient聊天补全EmbeddingClient文本嵌入ImageClient图像生成DALL-EAudioClient音频转写 / TTSChatCompletion聊天响应对象ChatCompletionOptions请求配置采样参数、工具、数据源等StreamingChatCompletionUpdate流式响应分块ChatMessage消息基类型SystemChatMessage系统提示词UserChatMessage用户输入AssistantChatMessage助手回复DeveloperChatMessage开发者消息推理模型ChatTool函数 / 工具定义ChatToolCall工具调用请求最佳实践清单技能文档总结了 8 条生产级实践生产环境使用 Entra ID—— 避免 API Key改用DefaultAzureCredential复用客户端实例—— 顶层客户端创建一次跨请求共享天然契合上文的客户端层级设计处理限流—— 对 429 响应实现指数退避重试长回答用流式——CompleteChatStreamingAsync提升用户体验设置合理超时—— 长补全任务需要延长超时时间使用结构化输出—— JSON Schema 保证响应格式一致便于程序消费监控 Token 用量—— 跟踪completion.Usage控制成本校验工具调用—— 执行前必须校验函数参数。错误处理模式SDK 将服务端错误统一包装为RequestFailedException可按 HTTP 状态码分治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}); }状态码速查状态码含义处理建议429触发限流退避后重试可结合指数退避400请求参数错误检查消息结构、Schema、部署名其他服务端错误记录状态码与消息排查配额/网络相关 SDK 生态与扩展方向SDK用途安装命令Azure.AI.OpenAIAzure OpenAI 客户端本文主体dotnet add package Azure.AI.OpenAIOpenAIOpenAI 兼容客户端dotnet add package OpenAIAzure.Identity认证Entra IDdotnet add package Azure.IdentityAzure.Search.DocumentsAI Search 客户端用于 RAGdotnet add package Azure.Search.Documents在此基础上可进一步扩展项目级编排进阶场景可参考 AAS 中的 azure-ai-projects-dotnet 技能它面向 Azure AI Foundry 项目覆盖 agents、connections、datasets、deployments、evaluations、indexes 等高层操作可与本文的底层客户端组合使用官方参考资料本文所用 API 的 NuGet 包页面、Microsoft Learn API 参考、1.0→2.0 迁移指南以及 Quickstart 均可通过官方文档渠道获取具体版本行为以你安装的 SDK 版本为准文档记录 2.1.0 为当前稳定版。适用边界与注意事项作为 AAS 技能本文所述内容的使用边界如下仅在任务明确匹配上述能力范围时使用聊天、嵌入、图像、音频、助手、RAG 等输出结果不能替代环境特定环境的验证、测试或专家评审——尤其是涉及生产部署、合规与安全审查的场景当所需输入、权限、安全边界或成功标准缺失时应暂停并请求澄清而不是猜测默认值继续执行认证凭证API Key 或 Entra ID 权限属于高敏感信息在 Agent 工作流中应遵循最小权限原则与密钥管理规范。结合技能文档与 AAS 目录结构可以推断本技能适合作为 Agent 在处理 .NET 项目 Azure OpenAI 集成 类任务时的能力说明书Agent 可按本文的代码骨架快速生成可运行的集成代码再交由开发者针对具体环境验证。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
