azure-ai-projects-py

Azure AI Projects Python SDK

适用场景

用于 Microsoft Foundry 项目连接、模型部署、版本化 Agent、评估数据集和云端评估工作流。请先确认已安装的 SDK 代际；不要将经典 thread/run 用法套用到 v2 项目客户端。

设置与版本边界

请使用隔离环境，以及应用锁定并审核过的兼容 azure-ai-projects、azure-identity 和 openai 版本。历史支持文件来自 Microsoft 的固定版本仓库；请参阅 UPSTREAM-NOTICE.md 和 UPSTREAM-LICENSE.txt。本地修正记录在这些文件中。

将 AZURE_AI_PROJECT_ENDPOINT 设置为准确且已授权的 HTTPS 项目 URL，并将 AZURE_AI_MODEL_DEPLOYMENT_NAME 设置为实际部署名称，而非臆测的模型别名。使用预期的租户/身份，并遵循最小权限原则；检查凭据链时不要打印凭据。对于仅列出资源的任务，不要获取连接机密。

经核验的 2.0.0b4 源码快照使用版本化 Agent、OpenAI conversations/responses，以及用于评估器/记忆/计划的 beta 命名空间。经典 Agent 属于 azure-ai-agents。后续版本可能有所不同；请查阅已安装的 SDK 和 Microsoft 迁移指南。

示例：创建一个明确请求的版本化 Agent

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

with DefaultAzureCredential() as credential:
    with AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project:
        agent = project.agents.create_version(
            agent_name="requested-agent",
            definition=PromptAgentDefinition(
                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
                instructions="Answer the user’s question using authorized information.",
            ),
        )
        with project.get_openai_client(timeout=60, max_retries=0) as openai:
            response = openai.responses.create(
                input="Hello",
                extra_body={"agent_reference": {"type": "agent_reference", "name": agent.name, "version": agent.version}},
            )
            # Inspect authorized output; do not log private traces or credentials.

安全工作流

1. 确认准确的租户/项目、已安装版本、请求的资源和数据分类。
2. 选择模型前先读取部署/连接元数据；不要自动选择第一个看似匹配的部署。
3. 仅启用所需工具。模型工具调用只是提议：执行前请验证参数、授权、目标位置和影响。云端必须能够访问远程 MCP 端点；localhost 并非用户的计算机。
4. 仅上传选定且获准的文件。文件夹扩展名筛选器无法排除机密，也无法强制执行访问权限。持久化记忆需要按租户/用户隔离，并制定保留和删除规则。
5. 限制请求超时、轮询次数、并发数、行数和开支。如果资源创建超时，请先核实其结果，再重试。仅删除由任务创建且明确用于清理的资源。

批量评估辅助工具

scripts/run_batch_evaluation.py 会上传选定的完整 JSONL 文件、创建评估和运行任务，并可能产生云端/模型费用。--allow-paid 是执行前的选择加入标记，表示用户已授权使用此确切文件、端点、评估器、部署和预算。它不是费用估算，也不是开支强制控制机制。

python scripts/run_batch_evaluation.py --data approved.jsonl --evaluators coherence --deployment approved-deployment --max-rows 100 --max-bytes 1048576 --timeout-seconds 600 --allow-paid --output new-private-results.json

输入行必须具有一致的架构；Agent 模式使用示例输出，不会修改源记录。未知评估器或缺少映射字段会在上传前导致失败。轮询超时不会取消远程执行：请检查打印出的评估/运行 ID，并在需要时通过已安装服务文档规定的 API 取消任务。本地输出仅在文件不存在时新建，权限为 0600。评估器名称/架构取决于服务版本；进行实时运行前请检查注册表。

参考资料

• Agent 操作和工具边界
• 评估、内置评估器、自定义评估器
• 连接、部署、数据集/索引
• 异步模式、已核验的 API 快照

限制

没有任何本地检查能证明 Azure 服务当前可用、模型质量、法律合规性或自主安全地使用工具。评估分数是抽样得出的、针对特定版本的判断；请报告失败项、缺失分数、样本数量和评审配置。关键词检查只是格式检查，不代表获得合规认证。必须解析 JSON 输出并验证其架构。审阅文档时不要运行云端评估。