autogen_ext.tools.azure#

class AzureAISearchTool(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], description: str | None = None, api_version: str = DEFAULT_API_VERSION, query_type: Literal['simple', 'full', 'semantic', 'vector'] = 'simple', search_fields: List[str] | None = None, select_fields: List[str] | None = None, vector_fields: List[str] | None = None, top: int | None = None, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300, embedding_provider: str | None = None, embedding_model: str | None = None, openai_api_key: str | None = None, openai_api_version: str | None = None, openai_endpoint: str | None = None)[source]#

基类：EmbeddingProviderMixin，BaseAzureAISearchTool

用于查询 Azure 搜索索引的 Azure AI 搜索工具。

此工具提供了一个简化的接口，用于使用各种搜索方法查询 Azure AI 搜索索引。建议使用工厂方法创建针对特定搜索类型定制的实例。

全文搜索：用于传统关键词搜索、Lucene 查询或语义重新排序的结果。– 使用 AzureAISearchTool.create_full_text_search() – 支持 query_type：“simple”（关键词）、“full”（Lucene）、“semantic”。
向量搜索：用于基于向量嵌入的纯相似性搜索。– 使用 AzureAISearchTool.create_vector_search()
混合搜索：用于结合向量搜索和全文或语义搜索，以兼顾两者的优点。– 使用 AzureAISearchTool.create_hybrid_search() – 文本组件可以是“simple”、“full”或“semantic”，通过 query_type 参数指定。

每个工厂方法都会为所选的搜索策略配置工具的适当默认值和验证。

警告

如果设置 query_type=”semantic”，则还必须提供有效的 semantic_config_name。此配置必须事先在 Azure AI 搜索索引中设置。

component_provider_override: ClassVar[str | None] = 'autogen_ext.tools.azure.AzureAISearchTool'#: 覆盖组件的提供者字符串。这应该用于防止内部模块名称成为模块名称的一部分。

classmethod create_full_text_search(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], description: str | None = None, api_version: str | None = None, query_type: Literal['simple', 'full', 'semantic'] = 'simple', search_fields: List[str] | None = None, select_fields: List[str] | None = None, top: int | None = 5, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300) → AzureAISearchTool[source]#

创建一个用于传统文本搜索的工具。

此工厂方法创建了一个针对全文搜索优化的 AzureAISearchTool，支持关键词匹配、Lucene 语法和语义搜索功能。

参数:

name – 此工具实例的名称
endpoint – Azure AI 搜索服务的完整 URL
index_name – 要查询的搜索索引名称
credential – 用于身份验证的 Azure 凭据（API 密钥或令牌）
description – 可选描述，解释工具的目的
api_version – 要使用的 Azure AI 搜索 API 版本
query_type –
要执行的文本搜索类型
- simple：基本关键词搜索，匹配精确术语及其变体
- full：使用 Lucene 查询语法进行高级搜索，以执行复杂查询
- semantic：由 AI 驱动的搜索，理解含义和上下文，提供增强的相关性排名
search_fields – 在文档中搜索的字段
select_fields – 在搜索结果中返回的字段
top – 返回结果的最大数量（默认值：5）
filter – OData 筛选表达式，用于优化搜索结果
semantic_config_name – 语义配置名称（语义查询类型必需）
enable_caching – 是否缓存搜索结果
cache_ttl_seconds – 缓存结果的秒数

返回:

一个已初始化用于全文搜索的 AzureAISearchTool

示例

from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchTool

# Basic keyword search
tool = AzureAISearchTool.create_full_text_search(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="simple",  # Enable keyword search
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)

# full text (Lucene query) search
full_text_tool = AzureAISearchTool.create_full_text_search(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="full",  # Enable Lucene query syntax
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)

# Semantic search with re-ranking
# Note: Make sure your index has semantic configuration enabled
semantic_tool = AzureAISearchTool.create_full_text_search(
    name="semantic-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="semantic",  # Enable semantic ranking
    semantic_config_name="<your-semantic-config>",  # Required for semantic search
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)

# The search tool can be used with an Agent
# assistant = Agent("assistant", tools=[semantic_tool])

classmethod create_vector_search(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], vector_fields: List[str], description: str | None = None, api_version: str | None = None, select_fields: List[str] | None = None, top: int = 5, filter: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300, embedding_provider: str | None = None, embedding_model: str | None = None, openai_api_key: str | None = None, openai_api_version: str | None = None, openai_endpoint: str | None = None) → AzureAISearchTool[source]#

创建一个用于纯向量/相似性搜索的工具。

此工厂方法创建了一个针对向量搜索优化的 AzureAISearchTool，允许使用向量嵌入进行基于语义相似性的匹配。

参数:

name – 此工具实例的名称
endpoint – Azure AI 搜索服务的完整 URL
index_name – 要查询的搜索索引名称
credential – 用于身份验证的 Azure 凭据（API 密钥或令牌）
vector_fields – 用于向量搜索的字段（必需）
description – 可选描述，解释工具的目的
api_version – 要使用的 Azure AI 搜索 API 版本
select_fields – 在搜索结果中返回的字段
top – 返回结果的最大数量 / k-NN 中的 k（默认值：5）
filter – OData 筛选表达式，用于优化搜索结果
enable_caching – 是否缓存搜索结果
cache_ttl_seconds – 缓存结果的秒数
embedding_provider – 客户端嵌入提供程序（例如，“azure_openai”、“openai”）
embedding_model – 客户端嵌入模型（例如，“text-embedding-ada-002”）
openai_api_key – OpenAI/Azure OpenAI 嵌入的 API 密钥
openai_api_version – Azure OpenAI 嵌入的 API 版本
openai_endpoint – Azure OpenAI 嵌入的端点 URL

返回:

一个已初始化用于向量搜索的 AzureAISearchTool

抛出:

ValueError – 如果 vector_fields 为空
ValueError – 如果 embedding_provider 是“azure_openai”但没有 openai_endpoint
ValueError – 如果缺少或参数无效

使用示例

from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchTool

# Vector search with service-side vectorization
tool = AzureAISearchTool.create_vector_search(
    name="vector-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    vector_fields=["content_vector"],  # Your vector field name
    select_fields=["content", "title", "url"],  # Fields to return in results
    top=5,
)

# Vector search with Azure OpenAI embeddings
azure_openai_tool = AzureAISearchTool.create_vector_search(
    name="azure-openai-vector-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    vector_fields=["content_vector"],
    embedding_provider="azure_openai",  # Use Azure OpenAI for embeddings
    embedding_model="text-embedding-ada-002",  # Embedding model to use
    openai_endpoint="https://your-openai.openai.azure.com",  # Your Azure OpenAI endpoint
    openai_api_key="<your-openai-key>",  # Your Azure OpenAI key
    openai_api_version="2024-02-15-preview",  # Azure OpenAI API version
    select_fields=["content", "title", "url"],  # Fields to return in results
    top=5,
)

# Vector search with OpenAI embeddings
openai_tool = AzureAISearchTool.create_vector_search(
    name="openai-vector-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    vector_fields=["content_vector"],
    embedding_provider="openai",  # Use OpenAI for embeddings
    embedding_model="text-embedding-ada-002",  # Embedding model to use
    openai_api_key="<your-openai-key>",  # Your OpenAI API key
    select_fields=["content", "title", "url"],  # Fields to return in results
    top=5,
)

# Use the tool with an Agent
# assistant = Agent("assistant", tools=[azure_openai_tool])

classmethod create_hybrid_search(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], vector_fields: List[str], search_fields: List[str], description: str | None = None, api_version: str | None = None, query_type: Literal['simple', 'full', 'semantic'] = 'simple', select_fields: List[str] | None = None, top: int = 5, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300, embedding_provider: str | None = None, embedding_model: str | None = None, openai_api_key: str | None = None, openai_api_version: str | None = None, openai_endpoint: str | None = None) → AzureAISearchTool[source]#

创建一个结合了向量和文本搜索功能的工具。

此工厂方法创建了一个配置为混合搜索的 AzureAISearchTool，它结合了向量相似性和传统文本搜索的优点。

参数:

name – 此工具实例的名称
endpoint – Azure AI 搜索服务的完整 URL
index_name – 要查询的搜索索引名称
credential – 用于身份验证的 Azure 凭据（API 密钥或令牌）
vector_fields – 用于向量搜索的字段（必需）
search_fields – 用于文本搜索的字段（必需）
description – 可选描述，解释工具的目的
api_version – 要使用的 Azure AI 搜索 API 版本
query_type –
要执行的文本搜索类型
- simple：基本关键词搜索，匹配精确术语及其变体
- full：使用 Lucene 查询语法进行高级搜索，以执行复杂查询
- semantic：由 AI 驱动的搜索，理解含义和上下文，提供增强的相关性排名
select_fields – 在搜索结果中返回的字段
top – 返回结果的最大数量（默认值：5）
filter – OData 筛选表达式，用于优化搜索结果
semantic_config_name – 语义配置名称（如果 query_type=”semantic”，则必需）
enable_caching – 是否缓存搜索结果
cache_ttl_seconds – 缓存结果的秒数
embedding_provider – 客户端嵌入提供程序（例如，“azure_openai”、“openai”）
embedding_model – 客户端嵌入模型（例如，“text-embedding-ada-002”）
openai_api_key – OpenAI/Azure OpenAI 嵌入的 API 密钥
openai_api_version – Azure OpenAI 嵌入的 API 版本
openai_endpoint – Azure OpenAI 嵌入的端点 URL

返回:

一个已初始化用于混合搜索的 AzureAISearchTool

抛出:

ValueError – 如果 vector_fields 或 search_fields 为空
ValueError – 如果 query_type 是“semantic”但没有 semantic_config_name
ValueError – 如果 embedding_provider 是“azure_openai”但没有 openai_endpoint
ValueError – 如果缺少或参数无效

示例

from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchTool

# Basic hybrid search with service-side vectorization
tool = AzureAISearchTool.create_hybrid_search(
    name="hybrid-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    vector_fields=["content_vector"],  # Your vector field name
    search_fields=["content", "title"],  # Your searchable fields
    top=5,
)

# Hybrid search with semantic ranking and Azure OpenAI embeddings
semantic_tool = AzureAISearchTool.create_hybrid_search(
    name="semantic-hybrid-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    vector_fields=["content_vector"],
    search_fields=["content", "title"],
    query_type="semantic",  # Enable semantic ranking
    semantic_config_name="<your-semantic-config>",  # Your semantic config name
    embedding_provider="azure_openai",  # Use Azure OpenAI for embeddings
    embedding_model="text-embedding-ada-002",  # Embedding model to use
    openai_endpoint="https://your-openai.openai.azure.com",  # Your Azure OpenAI endpoint
    openai_api_key="<your-openai-key>",  # Your Azure OpenAI key
    openai_api_version="2024-02-15-preview",  # Azure OpenAI API version
    select_fields=["content", "title", "url"],  # Fields to return in results
    filter="language eq 'en'",  # Optional OData filter
    top=5,
)

# The search tool can be used with an Agent
# assistant = Agent("assistant", tools=[semantic_tool])

class BaseAzureAISearchTool(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], description: str | None = None, api_version: str = DEFAULT_API_VERSION, query_type: Literal['simple', 'full', 'semantic', 'vector'] = 'simple', search_fields: List[str] | None = None, select_fields: List[str] | None = None, vector_fields: List[str] | None = None, top: int | None = None, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300, embedding_provider: str | None = None, embedding_model: str | None = None, openai_api_key: str | None = None, openai_api_version: str | None = None, openai_endpoint: str | None = None)[source]#

基类：BaseTool[SearchQuery, SearchResults]，Component[AzureAISearchConfig]，EmbeddingProvider，ABC

Azure AI 搜索工具的抽象基类。

此类定义了所有 Azure AI 搜索工具的通用接口和功能。它处理配置管理、客户端初始化以及子类必须实现的抽象方法。

search_config#: 搜索服务的配置参数。

注意

这是一个抽象基类，不应直接实例化。请使用 AzureAISearchTool 中的具体实现或工厂方法。

component_config_schema#: 别名为 AzureAISearchConfig

component_provider_override: ClassVar[str | None] = 'autogen_ext.tools.azure.BaseAzureAISearchTool'#: 覆盖组件的提供者字符串。这应该用于防止内部模块名称成为模块名称的一部分。

async close() → None[source]#: 如果需要（用于清理），明确关闭 Azure SearchClient。

async run(args: str | Dict[str, Any] | SearchQuery, cancellation_token: CancellationToken | None = None) → SearchResults[source]#

针对 Azure AI 搜索索引执行搜索。

参数:

args – 搜索查询文本或 SearchQuery 对象
cancellation_token – 可选的取消操作令牌

返回:

SearchResults – 包含搜索结果和元数据的容器

抛出:

ValueError – 如果搜索查询为空或无效
ValueError – 如果存在身份验证错误或其他搜索问题
CancelledError – 如果操作被取消

property schema: ToolSchema#: 返回工具的模式。

return_value_as_string(value: SearchResults) → str[source]#: 将搜索结果转换为字符串表示形式。

pydantic model SearchQuery[source]#

基类: BaseModel

搜索查询参数。

此简化接口仅需要一个搜索查询字符串。所有其他参数（顶部、筛选器、向量字段等）在工具创建期间指定，而不是在查询时指定，这使得语言模型更容易生成结构化输出。

参数:: query (str) – 搜索查询文本。

显示 JSON 模式

{
   "title": "SearchQuery",
   "description": "Search query parameters.\n\nThis simplified interface only requires a search query string.\nAll other parameters (top, filters, vector fields, etc.) are specified during tool creation\nrather than at query time, making it easier for language models to generate structured output.\n\nArgs:\n    query (str): The search query text.",
   "type": "object",
   "properties": {
      "query": {
         "description": "Search query text",
         "title": "Query",
         "type": "string"
      }
   },
   "required": [
      "query"
   ]
}

字段:

query (str)

field query: str [Required]#: 搜索查询文本

pydantic model SearchResult[source]#

基类: BaseModel

搜索结果。

参数:

score (float) – 搜索分数。
content (ContentDict) – 文档内容。
metadata (MetadataDict) – 关于文档的附加元数据。

显示 JSON 模式

{
   "title": "SearchResult",
   "description": "Search result.\n\nArgs:\n    score (float): The search score.\n    content (ContentDict): The document content.\n    metadata (MetadataDict): Additional metadata about the document.",
   "type": "object",
   "properties": {
      "score": {
         "description": "The search score",
         "title": "Score",
         "type": "number"
      },
      "content": {
         "description": "The document content",
         "title": "Content",
         "type": "object"
      },
      "metadata": {
         "description": "Additional metadata about the document",
         "title": "Metadata",
         "type": "object"
      }
   },
   "required": [
      "score",
      "content",
      "metadata"
   ]
}

字段:

content (Dict[str, Any])
metadata (Dict[str, Any])
score (float)

字段 score: float [必需]#: 搜索分数

字段 content: ContentDict [必需]#: 文档内容

字段 metadata: MetadataDict [必需]#: 关于文档的额外元数据

pydantic 模型 SearchResults[源]#

基类: BaseModel

搜索结果的容器。

参数:: results (List[SearchResult]) – 搜索结果列表。

显示 JSON 模式

{
   "title": "SearchResults",
   "description": "Container for search results.\n\nArgs:\n    results (List[SearchResult]): List of search results.",
   "type": "object",
   "properties": {
      "results": {
         "description": "List of search results",
         "items": {
            "$ref": "#/$defs/SearchResult"
         },
         "title": "Results",
         "type": "array"
      }
   },
   "$defs": {
      "SearchResult": {
         "description": "Search result.\n\nArgs:\n    score (float): The search score.\n    content (ContentDict): The document content.\n    metadata (MetadataDict): Additional metadata about the document.",
         "properties": {
            "score": {
               "description": "The search score",
               "title": "Score",
               "type": "number"
            },
            "content": {
               "description": "The document content",
               "title": "Content",
               "type": "object"
            },
            "metadata": {
               "description": "Additional metadata about the document",
               "title": "Metadata",
               "type": "object"
            }
         },
         "required": [
            "score",
            "content",
            "metadata"
         ],
         "title": "SearchResult",
         "type": "object"
      }
   },
   "required": [
      "results"
   ]
}

字段:

results (List[autogen_ext.tools.azure._ai_search.SearchResult])

字段 results: List[SearchResult] [必需]#: 搜索结果列表

pydantic 模型 AzureAISearchConfig[源]#

基类: BaseModel

用于 Azure AI Search 的配置，带有验证。

此类别定义 Azure AI Search 工具的配置参数，包括身份验证、搜索行为、缓存和嵌入设置。

注意

此类别需要 autogen-ext 包的 azure 额外功能。

pip install -U "autogen-ext[azure]"

注意

先决条件

必须在您的 Azure 订阅中创建 Azure AI Search 服务。
搜索索引必须根据您的用例正确配置
- 对于向量搜索：索引必须具有向量字段
- 对于语义搜索：索引必须具有语义配置
- 对于混合搜索：必须同时配置向量字段和文本字段
所需包
- 基本功能： azure-search-documents>=11.4.0
- 对于 Azure OpenAI 嵌入： openai azure-identity
- 对于 OpenAI 嵌入： openai

使用示例

from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchConfig

# Basic configuration for full-text search
config = AzureAISearchConfig(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="simple",
    search_fields=["content", "title"],  # Update with your searchable fields
    top=5,
)

# Configuration for vector search with Azure OpenAI embeddings
vector_config = AzureAISearchConfig(
    name="vector-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="vector",
    vector_fields=["embedding"],  # Update with your vector field name
    embedding_provider="azure_openai",
    embedding_model="text-embedding-ada-002",
    openai_endpoint="https://your-openai.openai.azure.com",  # Your Azure OpenAI endpoint
    openai_api_key="<your-openai-key>",  # Your Azure OpenAI key
    top=5,
)

# Configuration for hybrid search with semantic ranking
hybrid_config = AzureAISearchConfig(
    name="hybrid-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="semantic",
    semantic_config_name="<your-semantic-config>",  # Name of your semantic configuration
    search_fields=["content", "title"],  # Update with your search fields
    vector_fields=["embedding"],  # Update with your vector field name
    embedding_provider="openai",
    embedding_model="text-embedding-ada-002",
    openai_api_key="<your-openai-key>",  # Your OpenAI API key
    top=5,
)

显示 JSON 模式

{
   "title": "AzureAISearchConfig",
   "description": "Configuration for Azure AI Search with validation.\n\nThis class defines the configuration parameters for Azure AI Search tools, including\nauthentication, search behavior, caching, and embedding settings.\n\n.. note::\n    This class requires the ``azure`` extra for the ``autogen-ext`` package.\n\n    .. code-block:: bash\n\n        pip install -U \"autogen-ext[azure]\"\n\n.. note::\n    **Prerequisites:**\n\n    1. An Azure AI Search service must be created in your Azure subscription.\n    2. The search index must be properly configured for your use case:\n\n       - For vector search: Index must have vector fields\n       - For semantic search: Index must have semantic configuration\n       - For hybrid search: Both vector fields and text fields must be configured\n    3. Required packages:\n\n       - Base functionality: ``azure-search-documents>=11.4.0``\n       - For Azure OpenAI embeddings: ``openai azure-identity``\n       - For OpenAI embeddings: ``openai``\n\nExample Usage:\n    .. code-block:: python\n\n        from azure.core.credentials import AzureKeyCredential\n        from autogen_ext.tools.azure import AzureAISearchConfig\n\n        # Basic configuration for full-text search\n        config = AzureAISearchConfig(\n            name=\"doc-search\",\n            endpoint=\"https://your-search.search.windows.net\",  # Your Azure AI Search endpoint\n            index_name=\"<your-index>\",  # Name of your search index\n            credential=AzureKeyCredential(\"<your-key>\"),  # Your Azure AI Search admin key\n            query_type=\"simple\",\n            search_fields=[\"content\", \"title\"],  # Update with your searchable fields\n            top=5,\n        )\n\n        # Configuration for vector search with Azure OpenAI embeddings\n        vector_config = AzureAISearchConfig(\n            name=\"vector-search\",\n            endpoint=\"https://your-search.search.windows.net\",\n            index_name=\"<your-index>\",\n            credential=AzureKeyCredential(\"<your-key>\"),\n            query_type=\"vector\",\n            vector_fields=[\"embedding\"],  # Update with your vector field name\n            embedding_provider=\"azure_openai\",\n            embedding_model=\"text-embedding-ada-002\",\n            openai_endpoint=\"https://your-openai.openai.azure.com\",  # Your Azure OpenAI endpoint\n            openai_api_key=\"<your-openai-key>\",  # Your Azure OpenAI key\n            top=5,\n        )\n\n        # Configuration for hybrid search with semantic ranking\n        hybrid_config = AzureAISearchConfig(\n            name=\"hybrid-search\",\n            endpoint=\"https://your-search.search.windows.net\",\n            index_name=\"<your-index>\",\n            credential=AzureKeyCredential(\"<your-key>\"),\n            query_type=\"semantic\",\n            semantic_config_name=\"<your-semantic-config>\",  # Name of your semantic configuration\n            search_fields=[\"content\", \"title\"],  # Update with your search fields\n            vector_fields=[\"embedding\"],  # Update with your vector field name\n            embedding_provider=\"openai\",\n            embedding_model=\"text-embedding-ada-002\",\n            openai_api_key=\"<your-openai-key>\",  # Your OpenAI API key\n            top=5,\n        )",
   "type": "object",
   "properties": {
      "name": {
         "description": "The name of this tool instance",
         "title": "Name",
         "type": "string"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Description explaining the tool's purpose",
         "title": "Description"
      },
      "endpoint": {
         "description": "The full URL of your Azure AI Search service",
         "title": "Endpoint",
         "type": "string"
      },
      "index_name": {
         "description": "Name of the search index to query",
         "title": "Index Name",
         "type": "string"
      },
      "credential": {
         "anyOf": [],
         "description": "Azure credential for authentication (API key or token)",
         "title": "Credential"
      },
      "api_version": {
         "default": "2023-10-01-preview",
         "description": "Azure AI Search API version to use. Defaults to 2023-10-01-preview.",
         "title": "Api Version",
         "type": "string"
      },
      "query_type": {
         "default": "simple",
         "description": "Type of search to perform: simple, full, semantic, or vector",
         "enum": [
            "simple",
            "full",
            "semantic",
            "vector"
         ],
         "title": "Query Type",
         "type": "string"
      },
      "search_fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Fields to search within documents",
         "title": "Search Fields"
      },
      "select_fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Fields to return in search results",
         "title": "Select Fields"
      },
      "vector_fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Fields to use for vector search",
         "title": "Vector Fields"
      },
      "top": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Maximum number of results to return. For vector searches, acts as k in k-NN.",
         "title": "Top"
      },
      "filter": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "OData filter expression to refine search results",
         "title": "Filter"
      },
      "semantic_config_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Semantic configuration name for enhanced results",
         "title": "Semantic Config Name"
      },
      "enable_caching": {
         "default": false,
         "description": "Whether to cache search results",
         "title": "Enable Caching",
         "type": "boolean"
      },
      "cache_ttl_seconds": {
         "default": 300,
         "description": "How long to cache results in seconds",
         "title": "Cache Ttl Seconds",
         "type": "integer"
      },
      "embedding_provider": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of embedding provider for client-side embeddings",
         "title": "Embedding Provider"
      },
      "embedding_model": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Model name for client-side embeddings",
         "title": "Embedding Model"
      },
      "openai_api_key": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "API key for OpenAI/Azure OpenAI embeddings",
         "title": "Openai Api Key"
      },
      "openai_api_version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "API version for Azure OpenAI embeddings",
         "title": "Openai Api Version"
      },
      "openai_endpoint": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Endpoint URL for Azure OpenAI embeddings",
         "title": "Openai Endpoint"
      }
   },
   "required": [
      "name",
      "endpoint",
      "index_name",
      "credential"
   ]
}

字段:

api_version (str)
cache_ttl_seconds (int)
credential (azure.core.credentials.AzureKeyCredential | azure.core.credentials_async.AsyncTokenCredential)
description (str | None)
embedding_model (str | None)
embedding_provider (str | None)
enable_caching (bool)
endpoint (str)
filter (str | None)
index_name (str)
name (str)
openai_api_key (str | None)
openai_api_version (str | None)
openai_endpoint (str | None)
query_type (Literal['simple', 'full', 'semantic', 'vector'])
search_fields (List[str] | None)
select_fields (List[str] | None)
semantic_config_name (str | None)
top (int | None)
vector_fields (List[str] | None)

验证器:

normalize_query_type » query_type
validate_endpoint » endpoint
validate_interdependent_fields » 所有字段
validate_top » top

字段 name: str [必需]#

此工具实例的名称

由以下验证:

validate_interdependent_fields

字段 description: str | None = None#

解释工具目的的描述

由以下验证:

validate_interdependent_fields

字段 endpoint: str [必需]#

您的 Azure AI Search 服务的完整 URL

由以下验证:

validate_endpoint
validate_interdependent_fields

字段 index_name: str [必需]#

要查询的搜索索引的名称

由以下验证:

validate_interdependent_fields

字段 credential: AzureKeyCredential | AsyncTokenCredential [必需]#

用于身份验证的 Azure 凭据（API 密钥或令牌）

由以下验证:

validate_interdependent_fields

字段 api_version: str = '2023-10-01-preview'#

要使用的 Azure AI Search API 版本。默认为 2023-10-01-preview。

由以下验证:

validate_interdependent_fields

字段 query_type: Literal['simple', 'full', 'semantic', 'vector'] = 'simple'#

要执行的搜索类型：simple、full、semantic 或 vector

由以下验证:

normalize_query_type
validate_interdependent_fields

字段 search_fields: List[str] | None = None#

文档内要搜索的字段

由以下验证:

validate_interdependent_fields

字段 select_fields: List[str] | None = None#

要在搜索结果中返回的字段

由以下验证:

validate_interdependent_fields

字段 vector_fields: List[str] | None = None#

用于向量搜索的字段

由以下验证:

validate_interdependent_fields

字段 top: int | None = None#

要返回的最大结果数。对于向量搜索，充当 k-NN 中的 k。

由以下验证:

validate_interdependent_fields
validate_top

字段 filter: str | None = None#

用于优化搜索结果的 OData 筛选器表达式

由以下验证:

validate_interdependent_fields

字段 semantic_config_name: str | None = None#

用于增强结果的语义配置名称

由以下验证:

validate_interdependent_fields

字段 enable_caching: bool = False#

是否缓存搜索结果

由以下验证:

validate_interdependent_fields

字段 cache_ttl_seconds: int = 300#

缓存结果的秒数

由以下验证:

validate_interdependent_fields

字段 embedding_provider: str | None = None#

用于客户端嵌入的嵌入提供者名称

由以下验证:

validate_interdependent_fields

字段 embedding_model: str | None = None#

用于客户端嵌入的模型名称

由以下验证:

validate_interdependent_fields

字段 openai_api_key: str | None = None#

用于 OpenAI/Azure OpenAI 嵌入的 API 密钥

由以下验证:

validate_interdependent_fields

字段 openai_api_version: str | None = None#

用于 Azure OpenAI 嵌入的 API 版本

由以下验证:

validate_interdependent_fields

字段 openai_endpoint: str | None = None#

用于 Azure OpenAI 嵌入的端点 URL

由以下验证:

validate_interdependent_fields

验证器 validate_endpoint » endpoint[源]#: 验证端点是否为有效 URL。

验证器 normalize_query_type » query_type[源]#: 将查询类型规范化为标准值。

验证器 validate_top » top[源]#: 确保如果提供了 top，则它是一个正整数。

验证器 validate_interdependent_fields » 所有字段[源]#: 在所有字段都已解析后验证相互依赖的字段。

基类：VectorQuery

用于向量搜索的查询参数，当提供了需要向量化的文本值时。

所有必需参数都必须填充才能发送到服务器。

变量:

kind (str 或 VectorQueryKind) – 正在执行的向量查询的种类。必需。已知值为：“vector”和“text”。
k_nearest_neighbors (int) – 作为热门结果返回的最近邻居数量。
fields (str) – 类型为 Collection(Edm.Single) 的向量字段，将包含在向量搜索中。
exhaustive (bool) – 当为 true 时，会触发对向量索引中所有向量的穷举 k 最近邻搜索。对于精确匹配至关重要的场景非常有用，例如确定地面真实值。
oversampling (float) – 过采样因子。最小值为 1。它会覆盖索引定义中配置的“defaultOversampling”参数。只有当“rerankWithOriginalVectors”为 true 时才能设置。此参数仅在底层向量字段使用压缩方法时才允许使用。
weight (float) – 与同一搜索请求中的其他向量查询和/或文本查询相比，向量查询的相对权重。此值用于组合由不同向量查询生成的多个排名列表和/或通过文本查询检索到的结果。权重越高，匹配该查询的文档在最终排名中的位置就越高。默认为 1.0，该值需要是大于零的正数。
text (str) – 要向量化以执行向量搜索查询的文本。必需。