功能主机

功能主机是在 Azure AI Foundry 帐户和 Foundry 项目范围内定义的子资源。 它们指定 Azure AI Foundry 代理服务应存储和处理代理数据的位置，包括：

• 对话历史记录（线程）
• 文件上传
• 矢量存储

为何使用功能主机？

功能主机允许 你自带 Azure 资源 ，而不是使用默认Microsoft托管的平台资源。 这为你提供了：

• 数据主权 - 保留 Azure 订阅中的所有代理数据。
• 安全控制 - 使用自己的存储帐户、数据库和搜索服务。
• 合规性 - 满足特定的法规或组织要求。

功能主机的工作原理是什么？

不需要创建功能主机。 但是，如果确实希望代理使用自己的资源，则必须在帐户和项目上创建功能主机。

默认行为（Microsoft 托管资源）

如果未创建帐户级和项目级功能主机，Azure AI Foundry 代理服务会自动使用Microsoft托管的 Azure 资源：

• 线程存储（会话历史记录、代理定义）
• 文件存储（上传的文档）
• 矢量搜索（嵌入和检索）

自带资源

在帐户级别和项目级别创建功能主机时，将使用订阅中自己的 Azure 资源存储和处理所有代理数据。 此配置称为 标准代理设置。

所有 Foundry 工作区资源应与 VNet 位于同一区域，包括 CosmosDB、存储帐户、AI 搜索、Foundry 帐户、项目和托管标识。

配置层次结构

功能主机遵循层次结构，其中具体配置优先于广泛配置。

1. 服务默认值 （Microsoft托管的搜索和存储）- 在未配置功能主机时使用。
2. 帐户级功能主机 - 为帐户下的所有项目提供共享默认值。
3. 项目级能力托管 - 用于替代该特定项目的帐户级别和服务默认设置。

了解功能主机约束

创建功能主机时，请注意以下重要约束以避免冲突：

• 每个范围一个功能主机：每个帐户和每个项目只能有一个活动功能主机。 尝试在同一范围创建具有不同名称的第二个功能主机将导致 409 冲突。

• 不支持配置更新：如果需要更改配置，则必须删除现有功能主机并重新创建它。

建议的设置

必需的属性

在帐户或项目级别，功能主机必须配置以下三个属性：

可选属性

帐户功能主机

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

项目功能主机

此配置将替代服务默认值和任何帐户级设置。 此项目中的所有代理都将使用指定的资源：

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmos-db-connection"],
    "vectorStoreConnections": ["my-ai-search-connection"],
    "storageConnections": ["my-storage-account-connection"],
    "aiServicesConnections": ["my-azure-openai-connection"]  // Optional
  }
}

可选：账户级默认设置与项目级覆盖配置

在应用于所有项目的帐户级别设置共享默认值：

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",

    // Optional: define shared BYO resources for every project. All foundry projects under this account will uses these Azure resources  
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

删除功能主机

删除帐户级功能主机

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

删除项目级功能主机

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

故障排除

如果在创建功能主机时遇到问题，本部分提供了最常见的问题和错误的解决方案。

HTTP 409 冲突错误

问题：每个范围有多个功能主机

症状： 尝试创建功能主机时收到 409 冲突错误，即使你认为范围为空。

错误消息：

{
  "error": {
    "code": "Conflict",
    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
  }
}

根源： 每个帐户和每个项目只能有一个活动功能主机。 尝试在同一范围内创建具有不同名称的功能主机。

解决方案：

1. 检查现有功能主机 - 查询范围以查看已存在的内容
2. 使用一致的命名 - 确保对同一范围的所有请求使用相同的名称
3. 查看要求 - 确定现有功能主机是否满足需求

验证步骤：

# For account-level capability hosts
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01

# For project-level capability hosts  
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01

问题：正在进行的并发作

症状： 收到 409 冲突错误，指示另一个作当前正在运行。

错误消息：

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

根源： 尝试创建功能主机，而另一个作（更新、删除、修改）正在进行在同一范围内。

解决方案：

1. 等待当前作完成 - 检查正在进行的作的状态
2. 监视作进度 - 使用作 API 跟踪完成
3. 实现重试逻辑 - 为临时冲突添加指数退避

作监视：

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

冲突预防的最佳做法

1.预请求验证

在进行更改之前，请始终验证当前状态：

• 查询目标范围内的现有功能主机
• 检查是否有正在进行的作
• 了解当前配置

2. 使用指数退避实现重试逻辑

try 
{
    var response = await CreateCapabilityHostAsync(request);
    return response;
}
catch (HttpRequestException ex) when (ex.Message.Contains("409"))
{
    if (ex.Message.Contains("existing Capability Host with name"))
    {
        // Handle name conflict - check if existing resource is acceptable
        var existing = await GetExistingCapabilityHostAsync();
        if (IsAcceptable(existing))
        {
            return existing; // Use existing resource
        }
        else
        {
            throw new InvalidOperationException("Scope already has a capability host with different name");
        }
    }
    else if (ex.Message.Contains("currently in non creating"))
    {
        // Handle concurrent operation - implement retry with backoff
        await Task.Delay(TimeSpan.FromSeconds(30));
        return await CreateCapabilityHostAsync(request); // Retry once
    }
}

3. 了解幂等行为

系统支持幂等创建请求：

• 同名 + 相同的配置 →返回现有资源 （200 正常）
• 同名 + 不同的配置 →返回 400 错误的请求
• 不同名称 →返回 409 冲突

4.配置更改工作流

由于不支持更新，因此请遵循以下顺序进行配置更改：

1. 删除现有功能主机
2. 等待删除完成
3. 使用所需配置创建新功能主机

后续步骤

• 详细了解 标准代理设置
• 代理服务入门