ASP.NET Extensions 中 Azure OpenAI 客户端路径配置问题解析

在 ASP.NET Extensions 项目的 Microsoft.Extensions.AI 组件中，开发者在使用最新预览版的 ChatClient 时遇到了 Azure OpenAI 服务端点路径配置的问题。本文将深入分析该问题的技术背景、原因及解决方案。

问题背景

当开发者尝试从旧版 AzureOpenAIClient 迁移到新版 ChatClient 时，发现无法正确设置自定义端点路径。具体表现为：

1. 使用旧版实现时，请求被正确发送到格式为 https://{resource}.openai.azure.com/openai/deployments/{deploymentId}/chat/completions?api-version=2025-03-01-preview 的端点
2. 迁移到新版后，请求被发送到简化的 https://{resource}.openai.azure.com/chat/completions 路径，导致 404 错误

技术分析

问题的核心在于新版 ChatClient 的内部实现中，路径构建逻辑发生了变化。查看源代码可以发现：

internal virtual PipelineMessage CreateCreateChatCompletionRequest(BinaryContent content, RequestOptions options)
{
    // 简化的路径构建逻辑
    uri.AppendPath("/chat/completions", false);
}

这种实现方式固定添加了 /chat/completions 路径段，而没有考虑 Azure OpenAI 服务特有的路径结构要求。

解决方案

目前有两种可行的解决方案：

方案一：完整路径配置

在 OpenAIClientOptions 中直接配置完整的端点路径，包括所有必需的路径段和查询参数：

new ChatClient(
    deploymentId,
    new ApiKeyCredential(apiKey),
    new OpenAIClientOptions {
        Endpoint = new Uri($"https://{resourceName}.openai.azure.com/openai/deployments/{deploymentId}?api-version=2025-03-01-preview")
    })

方案二：使用 AzureOpenAIClient

直接使用 AzureOpenAIClient 并调用其 GetChatClient 方法获取聊天客户端：

var client = new AzureOpenAIClient(
    new Uri($"https://{resourceName}.openai.azure.com/"),
    new ApiKeyCredential(apiKey));
    
var chatClient = client.GetChatClient(deploymentId);

最佳实践建议

1. 版本兼容性：在升级到新版本前，务必检查变更日志和迁移指南
2. 错误处理：增强错误处理逻辑，捕获并记录完整的请求URL，便于调试
3. 配置验证：实现配置验证机制，确保端点URL符合预期格式
4. 抽象层：考虑创建包装类，隔离直接依赖，便于未来升级

总结

这个问题反映了API客户端设计中端点配置灵活性的重要性。开发者在使用新版 ChatClient 时需要注意其路径构建逻辑的变化，并根据实际服务要求调整配置方式。对于Azure OpenAI服务，目前推荐使用完整路径配置或直接使用 AzureOpenAIClient 来确保兼容性。