Microsoft.Extensions.AI 9.4.0 中ChatClient自定义终结点路径问题解析

在使用Microsoft.Extensions.AI 9.4.0预览版时，开发者可能会遇到ChatClient无法正确设置自定义终结点路径的问题。本文将深入分析该问题的本质，并提供解决方案。

问题现象

当开发者尝试为Azure OpenAI服务配置自定义终结点时，按照常规方式设置Endpoint属性后，请求会被发送到错误的路径格式：

https://{resourceName}.openai.azure.com/chat/completions

而实际上Azure OpenAI服务期望的路径格式应该是：

https://{resourceName}.openai.azure.com/openai/deployments/{deploymentId}/chat/completions?api-version=2025-03-01-preview

问题根源

通过分析ChatClient的源代码可以发现，CreateCreateChatCompletionRequest方法中硬编码了"/chat/completions"路径，而没有考虑Azure OpenAI服务特定的路径结构要求。这导致开发者无法通过简单的Endpoint设置来满足Azure OpenAI服务的API路径要求。

解决方案

目前有效的解决方案是在设置Endpoint时，直接包含完整的路径结构：

services.AddChatClient(
    model.Key,
    new ChatClient(
        model.Value!.DeploymentId, 
        new ApiKeyCredential(model.Value!.ApiKey!), 
        new OpenAIClientOptions {
            Endpoint = new Uri($"https://{model.Value!.ResourceName}.openai.azure.com/openai/deployments/{model.Value!.DeploymentId}?api-version=2025-03-01-preview")
        }).AsIChatClient());

技术建议

1. 路径结构理解：Azure OpenAI服务的API路径有其特定结构，必须包含部署ID和API版本参数。

2. 调试技巧：当遇到404错误时，建议检查实际发送的请求URL，确保其符合服务端期望的格式。

3. 版本兼容性：从旧版本迁移时，需要注意API路径结构可能发生了变化，需要相应调整配置方式。

4. 错误处理：建议在代码中添加详细的错误日志记录，包括完整的请求URL，以便快速定位问题。

总结

这个问题反映了API客户端库在抽象不同服务提供商时的挑战。开发者需要了解底层服务的具体API规范，并在配置时提供完整的路径信息。虽然当前版本需要手动构造完整路径，但未来版本可能会提供更友好的配置方式。

对于生产环境使用，建议密切关注官方文档更新，并在升级版本时进行充分的测试验证。