azure-ai-projects-java

Azure AI Projects SDK for Java

用于 Azure AI Foundry 项目管理的高级 SDK，可访问连接、数据集、索引和评估。

版本与数据边界

本指南介绍的是历史 Beta 版 SDK。使用客户端构建器／模型签名前，请检查所选构件的确切 API；固定兼容的身份验证／核心依赖项，并编译一个最小测试。在获准的测试项目中使用合成数据。数据集上传、索引变更、评估提供方费用和计划任务是彼此独立的操作；执行前请检查目标位置、保留期限和成本。切勿记录连接凭据。

安装

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-projects</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

环境变量

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>

身份验证

import com.azure.ai.projects.AIProjectClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;

AIProjectClientBuilder builder = new AIProjectClientBuilder()
    .endpoint(System.getenv("PROJECT_ENDPOINT"))
    .credential(new DefaultAzureCredentialBuilder().build());

客户端层级

SDK 为不同操作提供多个子客户端：

客户端	用途
ConnectionsClient	列出已连接的 Azure 资源
DatasetsClient	上传文档并管理数据集
DeploymentsClient	列出 AI 模型部署
IndexesClient	创建和管理搜索索引
EvaluationsClient	运行 AI 模型评估
EvaluatorsClient	管理评估器配置
SchedulesClient	管理计划操作

// Build sub-clients from builder
ConnectionsClient connectionsClient = builder.buildConnectionsClient();
DatasetsClient datasetsClient = builder.buildDatasetsClient();
DeploymentsClient deploymentsClient = builder.buildDeploymentsClient();
IndexesClient indexesClient = builder.buildIndexesClient();
EvaluationsClient evaluationsClient = builder.buildEvaluationsClient();

核心操作

列出连接

import com.azure.ai.projects.models.Connection;
import com.azure.core.http.rest.PagedIterable;

PagedIterable<Connection> connections = connectionsClient.listConnections();
for (Connection connection : connections) {
    System.out.println("Name: " + connection.getName());
    System.out.println("Type: " + connection.getType());
    System.out.println("Credential Type: " + connection.getCredentials().getType());
}

列出索引

indexesClient.listLatest().forEach(index -> {
    System.out.println("Index name: " + index.getName());
    System.out.println("Version: " + index.getVersion());
    System.out.println("Description: " + index.getDescription());
});

创建或更新索引

import com.azure.ai.projects.models.AzureAISearchIndex;
import com.azure.ai.projects.models.Index;

String indexName = "my-index";
String indexVersion = "1.0";
String searchConnectionName = System.getenv("AI_SEARCH_CONNECTION_NAME");
String searchIndexName = System.getenv("AI_SEARCH_INDEX_NAME");

Index index = indexesClient.createOrUpdate(
    indexName,
    indexVersion,
    new AzureAISearchIndex()
        .setConnectionName(searchConnectionName)
        .setIndexName(searchIndexName)
);

System.out.println("Created index: " + index.getName());

评估集成

不要假定 EvaluationsClient 是 OpenAI EvalService，或它提供 getOpenAIClient()。请查阅所安装的确切 Beta 版 SDK 参考，并为该 API 构建文档中说明的评估客户端。这些是不同的 SDK 接口，需要兼容的依赖项、终结点和授权。

最佳实践

1. 在生产环境中使用 DefaultAzureCredential 进行身份验证
2. 复用客户端构建器，以高效创建多个子客户端
3. 列出资源时处理分页，使用 PagedIterable
4. 使用环境变量 配置连接名称和设置
5. 访问凭据前检查连接类型

错误处理

import com.azure.core.exception.HttpResponseException;
import com.azure.core.exception.ResourceNotFoundException;

try {
    Index index = indexesClient.get(indexName, version);
} catch (ResourceNotFoundException e) {
    System.err.println("Index not found: " + indexName);
} catch (HttpResponseException e) {
    System.err.println("Error: " + e.getResponse().getStatusCode());
}

参考链接

资源	URL
产品文档	https://learn.microsoft.com/azure/ai-studio/
API 参考	https://learn.microsoft.com/rest/api/aifoundry/aiprojects/
GitHub 源代码	https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-projects
示例	https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-projects/src/samples

适用场景

当任务与概览中描述的工作流或操作明确匹配时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需输入、权限、安全边界或成功标准，请暂停并请求澄清。