Azure AI Projects SDK 认证方式变更详解：从连接字符串到端点URL

背景介绍

Azure AI Projects SDK 近期经历了从1.0.0-beta.5到1.0.0-beta.7版本的重大变更，其中最显著的变化是认证方式的调整。这一变更影响了所有使用该SDK进行AI项目开发的开发者，特别是那些需要从客户端直接连接Azure AI Agent Service的应用场景。

认证方式的历史演变

在早期版本中，开发者使用连接字符串进行认证，格式如下：

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

对应的代码实现为：

const projectClient = AIProjectClient.fromConnectionString(connectionString, new DefaultAzureCredential());

而在新版本中，认证方式改为使用完整的端点URL：

const endpoint = "https://eastus.api.azureml.ms/agents/v1.0/subscriptions/12345678-abcd-1234-9fc6-62780b3d3e05/resourceGroups/my-resource-group/providers/Microsoft.MachineLearningServices/workspaces/my-project-name";
const projectClient = AIProjectClient.fromEndpoint(endpoint, DefaultAzureCredential());

新认证方式详解

端点URL的构造方法

端点URL的结构遵循特定模式，开发者需要了解如何从已知参数构建：

https://<region>.api.azureml.ms/agents/v1.0/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<project-name>

其中关键参数包括：

• region：部署区域，如eastus、swedencentral等
• subscription-id：Azure订阅ID
• resource-group-name：资源组名称
• project-name：项目/工作区名称

客户端认证实践

对于Node.js后端应用，推荐使用DefaultAzureCredential：

const endpoint = "构造的端点URL";
const projectClient = new AIProjectClient(endpoint, new DefaultAzureCredential());

对于浏览器端应用，需要使用InteractiveBrowserCredential：

const clientId = "应用注册的客户端ID";
const tenantId = "租户ID";
const agentsEndpoint = "构造的端点URL";

const options = {
  clientId,
  authorityHost: `https://login.microsoftonline.com/${tenantId}`,
  redirectUri: window.location.origin + "/aiproject-auth-callback.html",
};

const credential = new InteractiveBrowserCredential(options);
const agentsClient = new AgentsClient(agentsEndpoint, credential);

常见问题解决方案

1. 端点URL不工作的问题

开发者反馈多种端点格式尝试失败后，经验证有效的格式包括：

https://ai.azure.com/api/<region>/agents/v1.0/subscriptions/<sub-id>/resourcegroups/<rg-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>

2. 前端打包问题

使用azure-ai-projects包在前端项目中会导致打包体积显著增加（约7MB），并可能产生兼容性警告。替代方案是直接使用azure-ai-agents包，可将体积控制在350KB左右。

3. 流式处理与轮询

新版SDK支持两种处理方式：

• 轮询方式：通过定期检查运行状态
• 流式处理：更高效的实时通信方式（但当前版本可能存在反序列化问题）

最佳实践建议

1. 明确项目类型：区分AI Foundry项目与基于Hub的项目，它们使用不同的端点结构

2. 环境变量管理：统一使用AZURE_AI_PROJECT_ENDPOINT_STRING环境变量存储端点URL

3. 包选择策略：

   • 后端服务：使用azure-ai-projects
   • 前端应用：优先考虑azure-ai-agents

4. 错误处理：实现完善的错误捕获和重试机制，特别是对于网络不稳定的客户端场景

未来展望

随着Azure AI服务的持续演进，开发者应关注：

• 官方文档的定期更新
• SDK版本的兼容性说明
• 新功能的发布公告
• 社区反馈的常见问题解决方案

通过理解这些认证变更和技术细节，开发者可以更顺畅地在各种应用场景中集成Azure AI Projects服务，构建强大的AI驱动型应用。