通过

在 Azure AI 搜索中创建知识代理

注释

此功能目前处于公开预览状态。 此预览版未随附服务级别协议，建议不要用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

在 Azure AI 搜索中，知识代理 是一种顶级资源，表示与聊天完成模型的连接，用于代理式检索工作流。 知识代理被检索方法用于由 LLM 驱动的信息检索管道中。

知识代理指定：

  • 指向可搜索内容的知识来源（一个或多个）
  • 一个聊天补全模型，可为查询规划和答案制定提供推理能力
  • 用于性能优化的属性（限制查询处理时间）

创建知识代理后，可以随时更新其属性。 如果知识代理正在使用，更新将对下一个作业生效。

重要

2025-08-01-preview 引入了针对现有知识智能体的重大更改。 此预览版需要一个或多个 knowledgeSource 定义。 建议尽快将现有代码迁移到新的 API。

先决条件

若要遵循本指南中的步骤，我们建议将 Visual Studio Code 与 REST 客户端 配合使用，以便向 Azure AI 搜索或 Python 扩展 和 Jupyter 包发送预览版 REST API 调用。

部署用于代理检索的模型

确保你拥有 Azure AI 搜索可以访问的受支持模型。 以下说明假设使用 Azure AI Foundry 模型作为提供程序。

  1. 登录到 Azure AI Foundry 门户。

  2. 使用这些说明部署支持的模型。

  3. 验证搜索服务托管标识是否对 Azure OpenAI 资源具有 认知服务用户 权限。

    如果在本地进行测试，则还需要 认知服务用户 权限。

支持的模型

使用 Azure OpenAI 或等效的开源模型：

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-nano
  • gpt-4.1-mini
  • gpt-5
  • gpt-5-nano
  • gpt-5-mini

配置访问权限

Azure AI 搜索需要访问聊天完成模型。 可以使用基于密钥的身份验证或基于角色的身份验证（建议）。

如果使用基于角色的身份验证，请在 Azure OpenAI 资源上将 认知服务用户 角色分配给搜索服务托管标识。

在 Azure 中，必须具有模型提供程序的 所有者 或 用户访问管理员 权限才能分配角色。

  1. 将 Azure AI 搜索配置为使用托管标识。

  2. 在模型提供程序（如 Foundry Model）上，创建一个角色分配，该分配为搜索服务托管标识授予“认知服务用户”权限。 如果在本地进行测试，请将自己分配到相同的角色。

  3. 对于本地测试，请按照快速入门：无需密钥连接中的步骤获取个人访问令牌，并确保已登录到特定的订阅和租户。 将个人标识令牌粘贴到变量中 @accessToken 。 使用个人标识进行连接的请求应类似于以下示例：

    @search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# List Indexes
GET https://{{search-url}}/indexes?api-version=2025-08-01-preview
Authorization: Bearer {{accessToken}}

重要

如果使用基于角色的身份验证，请务必删除对请求中 API 密钥的所有引用。 在指定这两种方法的请求中，使用 API 密钥而不是角色。

检查现有知识代理

以下请求按名称列出知识代理人。 在知识代理集合中，所有知识代理必须唯一命名。 了解现有知识代理以供重复使用或命名新代理会很有帮助。

# List existing knowledge agents on the search service
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    agents = {agent.name: agent for agent in index_client.list_agents(api_version=search_api_version)}
    print(f"\nKnowledge agents on search service '{search_endpoint}':")

    if agents:
        print(f"Found {len(agents)} knowledge agent(s):")
        for i, (name, agent) in enumerate(sorted(agents.items()), 1):
            print(f"{i}. Name: {name}")
            if agent.knowledge_sources:
                ks_names = [ks.name for ks in agent.knowledge_sources]
                print(f"   Knowledge Sources: {', '.join(ks_names)}")
            print()
    else:
        print("No knowledge agents found.")

except Exception as e:
    print(f"Error listing knowledge agents: {str(e)}")

还可以按名称返回单个代理以查看其 JSON 定义。

# Get knowledge agent definition for earth-knowledge-agent-2
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    agent_name = "earth-knowledge-agent-2"
    agent = index_client.get_agent(agent_name, api_version=search_api_version)

    print(f"Knowledge agent '{agent_name}':")
    print(f"Name: {agent.name}")

    if agent.description:
        print(f"Description: {agent.description}")

    if agent.models:
        print(f"\nModels ({len(agent.models)}):")
        for i, model in enumerate(agent.models, 1):
            print(f"  {i}. {type(model).__name__}")
            if hasattr(model, 'azure_open_ai_parameters'):
                params = model.azure_open_ai_parameters
                print(f"     Resource: {params.resource_url}")
                print(f"     Deployment: {params.deployment_name}")
                print(f"     Model: {params.model_name}")

    if agent.knowledge_sources:
        print(f"\nKnowledge Sources ({len(agent.knowledge_sources)}):")
        for i, ks in enumerate(agent.knowledge_sources, 1):
            print(f"  {i}. {ks.name} (threshold: {ks.reranker_threshold})")

    if agent.output_configuration:
        config = agent.output_configuration
        print(f"\nOutput: {config.modality} (activity: {config.include_activity})")

    # Full JSON definition
    print(f"\nJSON definition:")
    print(json.dumps(agent.as_dict(), indent=2))

except Exception as e:
    print(f"Error: {str(e)}")

    # Show available agents
    try:
        agents = {agent.name: agent for agent in index_client.list_agents(api_version=search_api_version)}
        print(f"\nAvailable agents: {list(agents.keys())}")
    except Exception:
        print("Could not list available agents.")

创建知识代理

知识智能体驱动智能体检索管道。 在应用程序代码中，它由其他智能体或聊天机器人调用。

它的组成包括知识来源（可搜索内容）与你在 Azure OpenAI 中部署的聊天补全模型之间的连接。 模型上的属性用于建立连接。 知识来源上的属性建立默认值，用于通知查询执行和响应。

若要创建智能体，请使用 2025-08-01-preview 数据平面 REST API 或提供同等功能的 Azure SDK 预览包。

请确保您必须有一个现有的 知识源 才能提供给代理。

from azure.search.documents.indexes.models import KnowledgeAgent, KnowledgeAgentAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeAgentOutputConfiguration, KnowledgeAgentOutputConfigurationModality
from azure.search.documents.indexes import SearchIndexClient

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url=aoai_endpoint,
    deployment_name=aoai_gpt_deployment,
    model_name=aoai_gpt_model,
)

output_cfg = KnowledgeAgentOutputConfiguration(
    modality=KnowledgeAgentOutputConfigurationModality.ANSWER_SYNTHESIS,
    include_activity=True,
)

agent = KnowledgeAgent(
    name=knowledge_agent_name,
    models=[KnowledgeAgentAzureOpenAIModel(azure_open_ai_parameters=aoai_params)],
    knowledge_sources=[
        KnowledgeSourceReference(
            name=knowledge_source_name,
            reranker_threshold=2.5,
        )
    ],
    output_configuration=output_cfg,
)

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)
index_client.create_or_update_agent(agent, api_version=search_api_version)
print(f"Knowledge agent '{knowledge_agent_name}' created or updated successfully.")

查询知识智能体

对知识代理对象调用 检索 作，确认模型连接并返回响应。 使用 2025-08-01-preview 数据平面 REST API，或者使用提供同等功能的 Azure SDK 预览包来完成此任务。

请将“where does the ocean look green?”替换为一个符合你搜索索引要求的有效查询字符串。

从说明开始。

instructions = """
A Q&A agent that can answer questions about the Earth at night.
If you don't have the answer, respond with "I don't know".
"""

messages = [
    {
        "role": "system",
        "content": instructions
    }
]

然后发送查询。

from azure.search.documents.agent import KnowledgeAgentRetrievalClient
from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, SearchIndexKnowledgeSourceParams

agent_client = KnowledgeAgentRetrievalClient(endpoint=search_endpoint, agent_name=knowledge_agent_name, credential=credential)
query_1 = """
    where does the ocean look green??
    """

messages.append({
    "role": "user",
    "content": query_1
})

req = KnowledgeAgentRetrievalRequest(
    messages=[
        KnowledgeAgentMessage(
            role=m["role"],
            content=[KnowledgeAgentMessageTextContent(text=m["content"])]
        ) for m in messages if m["role"] != "system"
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name=knowledge_source_name,
        )
    ]
)

result = agent_client.retrieve(retrieval_request=req, api_version=search_api_version)
print(f"Retrieved content from '{knowledge_source_name}' successfully.")

删除代理

如果不再需要代理，或者需要在搜索服务上重新生成代理，请使用此请求删除当前对象。

from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)
index_client.delete_agent(knowledge_agent_name)
print(f"Knowledge agent '{knowledge_agent_name}' deleted successfully.")