# Azure.AI.OpenAI (.NET) Azure OpenAI 服务的客户端库，提供对 OpenAI 模型的访问，包括 GPT-4、GPT-4o、嵌入、DALL-E 和 Whisper。 ## 安装 dotnet 添加包 Azure.AI.OpenAI # 用于 OpenAI（非 Azure）兼容性 dotnet 添加包 OpenAI **当前版本**：2.1.0（稳定） ## 环境变量 AZURE_OPENAI_ENDPOINT=https://<资源名称>.openai.azure.com AZURE_OPENAI_API_KEY= # 用于基于密钥的身份验证 AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini # 您的部署名称 ## 客户端层次结构 AzureOpenAIClient（顶级） ├── GetChatClient(部署名称) → ChatClient ├── GetEmbeddingClient(部署名称) → EmbeddingClient ├── GetImageClient(部署名称) → ImageClient ├── GetAudioClient(部署名称) → AudioClient └── GetAssistantClient() → AssistantClient ## 身份验证 ### API 密钥认证使用 Azure；使用 Azure.AI.OpenAI； AzureOpenAIClient 客户端 = 新( 新的 Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!), 新的 AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")!)); ### Microsoft Entra ID（推荐用于生产）使用 Azure.Identity；使用 Azure.AI.OpenAI； AzureOpenAIClient 客户端 = 新( 新的 Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!), 新的 DefaultAzureCredential()); ### 直接将 OpenAI SDK 与 Azure 结合使用使用 Azure.Identity；使用 OpenAI；使用 OpenAI.Chat；使用 System.ClientModel.Primitives； #pragma 警告禁用 OPENAI001 BearerTokenPolicy 令牌策略 = new( 新的 DefaultAzureCredential(), “https://cognitiveservices.azure.com/.default”）； ChatClient 客户端 = 新( 型号：“gpt-4o-mini”，身份验证策略：令牌策略，选项：新的 OpenAIClientOptions() { 端点 = 新 Uri("https://YOUR-RESOURCE.openai.azure.com/openai/v1") }); ## 聊天完成 ### 基本聊天使用 Azure.AI.OpenAI；使用 OpenAI.Chat； AzureOpenAIClient azureClient = 新( 新的Uri（端点），新的 DefaultAzureCredential()); ChatClient chatClient = azureClient.GetChatClient("gpt-4o-mini"); ChatCompletion 完成 = chatClient.CompleteChat( [ new SystemChatMessage("你是一个有用的助手。"), new UserChatMessage("什么是 Azure OpenAI？") ]); Console.WriteLine(completion.Content[0].Text); ### 异步聊天 ChatCompletion 完成 = 等待 chatClient.CompleteChatAsync( [ new SystemChatMessage("你是一个有用的助手。"), new UserChatMessage("用简单的术语解释一下云计算。") ]); Console.WriteLine($"响应：{completion.Content[0].Text}"); Console.WriteLine($"使用的令牌：{completion.Usage.TotalTokenCount}"); ### 流媒体聊天等待 foreach (StreamingChatCompletionUpdate 更新在 chatClient.CompleteChatStreamingAsync(messages) 中 { if (更新.ContentUpdate.Count > 0) { Console.Write(update.ContentUpdate[0].Text); } } ### 与选项聊天 ChatCompletionOptions 选项 = new() { 最大输出令牌计数 = 1000, 温度=0.7f，顶P = 0.95f，频率惩罚 = 0, 存在惩罚 = 0 }; ChatCompletion 完成 =等待 chatClient.CompleteChatAsync(消息, 选项); ### 多轮对话列表 messages = new() { new SystemChatMessage("你是一个有用的助手。"), new UserChatMessage("嗨，你能帮我吗？"), new AssistantChatMessage("当然！您需要什么帮助？"), new UserChatMessage("法国的首都是哪里？") }; ChatCompletion 完成 =等待 chatClient.CompleteChatAsync(messages); messages.Add(new AssistantChatMessage(completion.Content[0].Text)); ## 结构化输出（JSON 模式）使用 System.Text.Json； ChatCompletionOptions 选项 = new() { ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat( jsonSchemaFormatName: "math_reasoning", jsonSchema: BinaryData.FromBytes(""" { “类型”：“对象”， “属性”：{ “步骤”：{ “类型”：“数组”， “项目”：{ “类型”：“对象”， “属性”：{ “解释”：{“类型”：“字符串”}， “输出”：{“类型”：“字符串”} }, “必需”：[“解释”，“输出”]， “附加属性”： false } }, “final_answer”：{“类型”：“字符串”} }, “必需”：[“步骤”，“final_answer”]， “附加属性”： false } """u8.ToArray()), jsonSchemaIsStrict：真） }; ChatCompletion 完成 = 等待 chatClient.CompleteChatAsync( [new UserChatMessage("如何解 8x + 7 = -23？")], 选项）；使用 JsonDocument json = JsonDocument.Parse(completion.Content[0].Text); Console.WriteLine($"答案：{json.RootElement.GetProperty("final_answer")}"); ## 推理模型（o1、o4-mini） ChatCompletionOptions 选项 = new() { ReasoningEffortLevel = ChatReasoningEffortLevel.Low, 最大输出令牌计数 = 100000 }; ChatCompletion 完成 = 等待 chatClient.CompleteChatAsync( [ new DeveloperChatMessage("你是一个有用的助手"), new UserChatMessage("解释相对论") ]，选项）； ## Azure AI 搜索集成 (RAG) 使用 Azure.AI.OpenAI.Chat； #pragma 警告禁用 AOAI001 ChatCompletionOptions 选项 = new(); options.AddDataSource(new AzureSearchChatDataSource() { 端点 = 新的 Uri(searchEndpoint), 索引名称 = 搜索索引, 身份验证 = DataSourceAuthentication.FromApiKey(searchKey) }); ChatCompletion 完成 = 等待 chatClient.CompleteChatAsync( [new UserChatMessage("有哪些健康计划可用？")], 选项）； ChatMessageContext 上下文=completion.GetMessageContext(); if (上下文?.意图不为空) { Console.WriteLine($"意图：{context.Intent}"); } foreach (ChatCitation 上下文中的引用？.Citations ?? []) { Console.WriteLine($"引用：{引用.Content}"); } ## 嵌入使用 OpenAI.Embeddings； EmbeddingClient embeddingClient = azureClient.GetEmbeddingClient("text-embedding-ada-002"); OpenAIEmbedding 嵌入=等待embeddingClient.GenerateEmbeddingAsync（“你好，世界！”）; ReadOnlyMemory 矢量 = embedding.ToFloats(); Console.WriteLine($"嵌入尺寸：{vector.Length}"); ### 批量嵌入列表<字符串> 输入 = new() { “第一个文档文本”， “第二个文档文本”， “第三个文档文本” }; OpenAIEmbeddingCollection 嵌入 =等待 embeddingClient.GenerateEmbeddingsAsync(inputs); foreach（嵌入中的 OpenAIEmbedding emb） { Console.WriteLine($"索引 {emb.Index}: {emb.ToFloats().Length} 尺寸"); } ## 图像生成 (DALL-E) 使用 OpenAI.Images； ImageClient imageClient = azureClient.GetImageClient("dall-e-3"); 生成的图像图像 = 等待 imageClient.GenerateImageAsync( “日落时的未来城市天际线”，新的图像生成选项 { 大小 = 生成的图像大小.W1024xH1024, 质量=GenerateImageQuality.High，样式=GenerateImageStyle.Vivid }); Console.WriteLine($"图片网址：{image.ImageUri}"); ## 音频（耳语） ### 转录使用 OpenAI.Audio； AudioClient audioClient = azureClient.GetAudioClient("whisper"); AudioTranscription 转录=等待audioClient.TranscribeAudioAsync( “音频.mp3”，新的音频转录选项 { ResponseFormat = AudioTranscriptionFormat.Verbose，语言=“en” }); Console.WriteLine(转录.Text); ### 文本转语音 BinaryData 语音 = 等待 audioClient.GenerateSpeechAsync( “您好，欢迎来到 Azure OpenAI！”, 生成的语音.合金，新的语音生成选项 { 速度比 = 1.0f，响应格式=GenerateSpeechFormat.Mp3 }); 等待 File.WriteAllBytesAsync(“output.mp3”，speech.ToArray()); ## 函数调用（工具） ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool( 函数名称：“获取当前天气”， functionDescription: "获取给定位置的当前天气", 函数参数：BinaryData.FromString(""" { “类型”：“对象”， “属性”：{ “位置”：{ “类型”：“字符串”， "description": "城市和州，例如加利福尼亚州旧金山" }, “单位”：{ “类型”：“字符串”， “枚举”：[“摄氏度”，“华氏度”] } }, “必需”：[“位置”] } “””））； ChatCompletionOptions 选项 = new() { 工具 = { 获取当前天气工具 } }; ChatCompletion 完成 = 等待 chatClient.CompleteChatAsync( [new UserChatMessage("西雅图的天气怎么样？")], 选项）； if (completion.FinishReason == ChatFinishReason.ToolCalls) { foreach（ChatToolCall 完成中的 toolCall.ToolCalls） { Console.WriteLine($"函数：{toolCall.FunctionName}"); Console.WriteLine($"参数：{toolCall.FunctionArguments}"); } } ## 按键类型参考类型 |目的 ---|--- `AzureOpenAIClient` | Azure OpenAI 的顶级客户端 `聊天客户端` |聊天完成情况 `嵌入客户端` |文本嵌入 `图像客户端` |图像生成 (DALL-E) `音频客户端` |音频转录/TTS `聊天完成` |聊天回复 `聊天完成选项` |请求配置 `StreamingChatCompletionUpdate` |流式响应块 `聊天消息` |基本消息类型 `系统聊天消息` |系统提示 `用户聊天消息` |用户输入 `助理聊天消息` |助理回应 `开发者聊天消息` |开发者留言（推理模型） `聊天工具` |功能/工具定义 `聊天工具调用` |工具调用请求 ## 最佳实践 1. **在生产中使用 Entra ID** — 避免 API 密钥；使用“默认AzureCredential” 2. **重用客户端实例** — 创建一次，跨请求共享 3. **处理速率限制** — 针对 429 错误实施指数退避 4. **长响应流** - 使用“CompleteChatStreamingAsync”获得更好的用户体验 5. **设置适当的超时** - 长时间完成可能需要延长超时 6. **使用结构化输出** - JSON模式确保一致的响应格式 7. **监控代币使用情况** — 跟踪“completion.Usage”以进行成本管理 8. **验证工具调用** — 在执行之前始终验证函数参数 ## 错误处理使用 Azure；尝试 { ChatCompletion 完成 =等待 chatClient.CompleteChatAsync(messages); } 当（ex.Status == 429）时捕获（RequestFailedException ex） { Console.WriteLine("速率有限。延迟后重试。"); 等待 Task.Delay(TimeSpan.FromSeconds(10)); } 当（ex.Status == 400）时捕获（RequestFailedException ex） { Console.WriteLine($"错误请求：{ex.Message}"); } 捕获（RequestFailedException 前） { Console.WriteLine($"Azure OpenAI 错误：{ex.Status} - {ex.Message}"); } ## 相关SDK SDK |目的|安装 ---|---|--- `Azure.AI.OpenAI` | Azure OpenAI 客户端（此 SDK） | `dotnet 添加包 Azure.AI.OpenAI` `开放人工智能` | OpenAI 兼容性 | `dotnet 添加包 OpenAI` `Azure.Identity` |认证| `dotnet 添加包 Azure.Identity` `Azure.Search.Documents` |人工智能搜索 RAG | `dotnet 添加包 Azure.Search.Documents` ## 参考链接资源 |网址 ---|--- NuGet 包 | API 参考 | 迁移指南（1.0→2.0）| 快速入门 | GitHub 来源 | ## 何时使用此技能适用于执行概述中描述的工作流程或操作。

Azure AI Openai Dotnet

包含技能