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)[Quelle]#

Bases: EmbeddingProviderMixin, BaseAzureAISearchTool

Azure AI Search-Tool für Abfragen von Azure Search-Indizes.

Dieses Tool bietet eine vereinfachte Schnittstelle für die Abfrage von Azure AI Search-Indizes unter Verwendung verschiedener Suchmethoden. Es wird empfohlen, die Factory-Methoden zu verwenden, um Instanzen zu erstellen, die auf bestimmte Suchtypen zugeschnitten sind

  1. Volltextsuche: Für traditionelle schlüsselwortbasierte Suchen, Lucene-Abfragen oder semantisch neu geordnete Ergebnisse. - Verwenden Sie AzureAISearchTool.create_full_text_search() - Unterstützt query_type: „simple“ (Schlüsselwort), „full“ (Lucene), „semantic“.

  2. Vektorsuche: Für reine Ähnlichkeitssuchen basierend auf Vektoreinbettungen. - Verwenden Sie AzureAISearchTool.create_vector_search()

  3. Hybride Suche: Zum Kombinieren von Vektorsuche mit Volltext- oder semantischer Suche, um die Vorteile beider zu nutzen. - Verwenden Sie AzureAISearchTool.create_hybrid_search() - Die Textkomponente kann über den Parameter query_type „simple“, „full“ oder „semantic“ sein.

Jede Factory-Methode konfiguriert das Tool mit geeigneten Standardwerten und Validierungen für die gewählte Suchstrategie.

Warnung

Wenn Sie query_type=”semantic” setzen, müssen Sie auch einen gültigen semantic_config_name angeben. Diese Konfiguration muss im Voraus in Ihrem Azure AI Search-Index eingerichtet werden.

component_provider_override: ClassVar[str | None] = 'autogen_ext.tools.azure.AzureAISearchTool'#

Überschreibe den Anbieter-String für die Komponente. Dies sollte verwendet werden, um zu verhindern, dass interne Modulnamen Teil des Modulnamens werden.

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[Quelle]#

Erstellt ein Tool für traditionelle textbasierte Suchen.

Diese Factory-Methode erstellt ein AzureAISearchTool, das für die Volltextsuche optimiert ist und Schlüsselwortabgleiche, Lucene-Syntax und semantische Suchfunktionen unterstützt.

Parameter:

  • name – Der Name dieser Tool-Instanz

  • endpoint – Die vollständige URL Ihres Azure AI Search-Dienstes

  • index_name – Name des zu durchsuchenden Suchindex

  • credential – Azure-Anmeldeinformationen zur Authentifizierung (API-Schlüssel oder Token)

  • description – Optionale Beschreibung, die den Zweck des Tools erklärt

  • api_version – Zu verwendende Azure AI Search-API-Version

  • query_type –

    Art der durchzuführenden Textsuche

    • simple: Einfache Schlüsselwortsuche, die exakte Begriffe und deren Variationen abgleicht

    • full: Erweiterte Suche mit Lucene-Abfragesyntax für komplexe Abfragen

    • semantic: KI-gestützte Suche, die Bedeutung und Kontext versteht und eine verbesserte Relevanzbewertung bietet

  • search_fields – Felder, innerhalb derer Dokumente durchsucht werden sollen

  • select_fields – Felder, die in den Suchergebnissen zurückgegeben werden sollen

  • top – Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)

  • filter – OData-Filterausdruck zur Verfeinerung der Suchergebnisse

  • semantic_config_name – Name der semantischen Konfiguration (erforderlich für semantischen query_type)

  • enable_caching – Ob Suchergebnisse zwischengespeichert werden sollen

  • cache_ttl_seconds – Wie lange die Ergebnisse in Sekunden zwischengespeichert werden sollen

Gibt zurück:

Eine initialisierte AzureAISearchTool für die Volltextsuche

Beispiel

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])

Erstellt ein Tool für reine Vektorsuche/Ähnlichkeitssuche.

Diese Factory-Methode erstellt ein AzureAISearchTool, das für die Vektorsuche optimiert ist und die semantische Ähnlichkeitssuche mithilfe von Vektor-Embeddings ermöglicht.

Parameter:

  • name – Der Name dieser Tool-Instanz

  • endpoint – Die vollständige URL Ihres Azure AI Search-Dienstes

  • index_name – Name des zu durchsuchenden Suchindex

  • credential – Azure-Anmeldeinformationen zur Authentifizierung (API-Schlüssel oder Token)

  • vector_fields – Felder, die für die Vektorsuche verwendet werden sollen (erforderlich)

  • description – Optionale Beschreibung, die den Zweck des Tools erklärt

  • api_version – Zu verwendende Azure AI Search-API-Version

  • select_fields – Felder, die in den Suchergebnissen zurückgegeben werden sollen

  • top – Maximale Anzahl von zurückzugebenden Ergebnissen / k in k-NN (Standard: 5)

  • filter – OData-Filterausdruck zur Verfeinerung der Suchergebnisse

  • enable_caching – Ob Suchergebnisse zwischengespeichert werden sollen

  • cache_ttl_seconds – Wie lange die Ergebnisse in Sekunden zwischengespeichert werden sollen

  • embedding_provider – Anbieter für clientseitige Embeddings (z. B. ‘azure_openai’, ‘openai’)

  • embedding_model – Modell für clientseitige Embeddings (z. B. ‘text-embedding-ada-002’)

  • openai_api_key – API-Schlüssel für OpenAI/Azure OpenAI-Embeddings

  • openai_api_version – API-Version für Azure OpenAI-Embeddings

  • openai_endpoint – Endpunkt-URL für Azure OpenAI-Embeddings

Gibt zurück:

Ein initialisiertes AzureAISearchTool für die Vektorsuche

Löst aus:

  • ValueError – Wenn vector_fields leer ist

  • ValueError – Wenn embedding_provider ‘azure_openai’ ist, aber kein openai_endpoint angegeben ist

  • ValueError – Wenn erforderliche Parameter fehlen oder ungültig sind

Beispielhafte Verwendung
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])

Erstellt ein Tool, das Vektor- und Textsuchfunktionen kombiniert.

Diese Factory-Methode erstellt ein AzureAISearchTool, das für die hybride Suche konfiguriert ist, welche die Vorteile der Vektorähnlichkeit und der traditionellen Textsuche kombiniert.

Parameter:

  • name – Der Name dieser Tool-Instanz

  • endpoint – Die vollständige URL Ihres Azure AI Search-Dienstes

  • index_name – Name des zu durchsuchenden Suchindex

  • credential – Azure-Anmeldeinformationen zur Authentifizierung (API-Schlüssel oder Token)

  • vector_fields – Felder, die für die Vektorsuche verwendet werden sollen (erforderlich)

  • search_fields – Felder, die für die Textsuche verwendet werden sollen (erforderlich)

  • description – Optionale Beschreibung, die den Zweck des Tools erklärt

  • api_version – Zu verwendende Azure AI Search-API-Version

  • query_type –

    Art der durchzuführenden Textsuche

    • simple: Einfache Stichwortsuche, die exakte Begriffe und ihre Variationen abgleicht

    • full: Erweiterte Suche mit Lucene-Abfragesyntax für komplexe Abfragen

    • semantic: KI-gestützte Suche, die Bedeutung und Kontext versteht und eine verbesserte Relevanzbewertung bietet

  • select_fields – Felder, die in den Suchergebnissen zurückgegeben werden sollen

  • top – Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)

  • filter – OData-Filterausdruck zur Verfeinerung der Suchergebnisse

  • semantic_config_name – Name der semantischen Konfiguration (erforderlich, wenn query_type=”semantic”)

  • enable_caching – Ob Suchergebnisse zwischengespeichert werden sollen

  • cache_ttl_seconds – Wie lange die Ergebnisse in Sekunden zwischengespeichert werden sollen

  • embedding_provider – Anbieter für clientseitige Embeddings (z. B. ‘azure_openai’, ‘openai’)

  • embedding_model – Modell für clientseitige Embeddings (z. B. ‘text-embedding-ada-002’)

  • openai_api_key – API-Schlüssel für OpenAI/Azure OpenAI-Embeddings

  • openai_api_version – API-Version für Azure OpenAI-Embeddings

  • openai_endpoint – Endpunkt-URL für Azure OpenAI-Embeddings

Gibt zurück:

Ein initialisiertes AzureAISearchTool für die hybride Suche

Löst aus:

  • ValueError – Wenn vector_fields oder search_fields leer sind

  • ValueError – Wenn query_type “semantic” ist, aber keine semantic_config_name angegeben ist

  • ValueError – Wenn embedding_provider ‘azure_openai’ ist, aber kein openai_endpoint angegeben ist

  • ValueError – Wenn erforderliche Parameter fehlen oder ungültig sind

Beispiel

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]#

Basisklassen: BaseTool[SearchQuery, SearchResults], Component[AzureAISearchConfig], EmbeddingProvider, ABC

Abstrakte Basisklasse für Azure AI Search-Tools.

Diese Klasse definiert die gemeinsame Schnittstelle und Funktionalität für alle Azure AI Search-Tools. Sie verwaltet die Konfiguration, die Client-Initialisierung und die abstrakten Methoden, die von Unterklassen implementiert werden müssen.

search_config#

Konfigurationsparameter für den Suchdienst.

Hinweis

Dies ist eine abstrakte Basisklasse und sollte nicht direkt instanziiert werden. Verwenden Sie konkrete Implementierungen oder die Factory-Methoden in AzureAISearchTool.

component_config_schema#

Alias von AzureAISearchConfig

component_provider_override: ClassVar[str | None] = 'autogen_ext.tools.azure.BaseAzureAISearchTool'#

Überschreibe den Anbieter-String für die Komponente. Dies sollte verwendet werden, um zu verhindern, dass interne Modulnamen Teil des Modulnamens werden.

async close() → None[source]#

Schließt den Azure SearchClient explizit, falls erforderlich (zur Bereinigung).

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

Führt eine Suche im Azure AI Search-Index aus.

Parameter:

  • args – Suchanfragetext oder SearchQuery-Objekt

  • cancellation_token – Optionales Token zum Abbrechen der Operation

Gibt zurück:

SearchResults – Container mit Suchergebnissen und Metadaten

Löst aus:

  • ValueError – Wenn die Suchanfrage leer oder ungültig ist

  • ValueError – Wenn ein Authentifizierungsfehler oder ein anderes Suchproblem auftritt

  • CancelledError – Wenn die Operation abgebrochen wird

property schema: ToolSchema#

Gibt das Schema für das Tool zurück.

return_value_as_string(value: SearchResults) → str[source]#

Konvertiert die Suchergebnisse in eine String-Repräsentation.

pydantic model SearchQuery[source]#

Bases: BaseModel

Suchanfrageparameter.

Diese vereinfachte Schnittstelle erfordert nur eine Suchanfragezeichenfolge. Alle anderen Parameter (top, filter, vector fields usw.) werden während der Tool-Erstellung und nicht zur Abfragezeit angegeben, was es für Sprachmodelle einfacher macht, strukturierte Ausgaben zu generieren.

Parameter:

query (str) – Der Text der Suchanfrage.

JSON-Schema anzeigen
{
   "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"
   ]
}

Felder:

  • query (str)

field query: str [Erforderlich]#

Suchanfragetext

pydantic model SearchResult[source]#

Bases: BaseModel

Suchergebnis.

Parameter:

  • score (float) – Der Such-Score.

  • content (ContentDict) – Der Inhalt des Dokuments.

  • metadata (MetadataDict) – Zusätzliche Metadaten zum Dokument.

JSON-Schema anzeigen
{
   "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"
   ]
}

Felder:

  • content (Dict[str, Any])

  • metadata (Dict[str, Any])

  • score (float)

field score: float [Erforderlich]#

Der Such-Score

field content: ContentDict [Erforderlich]#

Der Inhalt des Dokuments

field metadata: MetadataDict [Erforderlich]#

Zusätzliche Metadaten zum Dokument

pydantic model SearchResults[source]#

Bases: BaseModel

Container für Suchergebnisse.

Parameter:

results (List[SearchResult]) – Liste der Suchergebnisse.

JSON-Schema anzeigen
{
   "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"
   ]
}

Felder:

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

field results: List[SearchResult] [Erforderlich]#

Liste der Suchergebnisse

pydantic model AzureAISearchConfig[source]#

Bases: BaseModel

Konfiguration für Azure AI Search mit Validierung.

Diese Klasse definiert die Konfigurationsparameter für Azure AI Search-Tools, einschließlich Authentifizierung, Suchverhalten, Caching und Embedding-Einstellungen.

Hinweis

Diese Klasse erfordert die azure-Erweiterung für das Paket autogen-ext.

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

Hinweis

Voraussetzungen

  1. Ein Azure AI Search-Dienst muss in Ihrem Azure-Abonnement erstellt werden.

  2. Der Suchindex muss für Ihren Anwendungsfall richtig konfiguriert sein

    • Für Vektorsuche: Der Index muss Vektorfelder enthalten

    • Für semantische Suche: Der Index muss eine semantische Konfiguration enthalten

    • Für hybride Suche: Sowohl Vektorfelder als auch Textfelder müssen konfiguriert sein

  3. Erforderliche Pakete

    • Basisfunktionalität: azure-search-documents>=11.4.0

    • Für Azure OpenAI Embeddings: openai azure-identity

    • Für OpenAI Embeddings: openai

Beispielhafte Verwendung
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-Schema anzeigen
{
   "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"
   ]
}

Felder:

  • 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)

Validatoren:

  • normalize_query_type » query_type

  • validate_endpoint » endpoint

  • validate_interdependent_fields » all fields

  • validate_top » top

field name: str [Erforderlich]#

Der Name dieser Tool-Instanz

Validiert durch:

  • validate_interdependent_fields

field description: str | None = None#

Beschreibung, die den Zweck des Tools erklärt

Validiert durch:

  • validate_interdependent_fields

field endpoint: str [Erforderlich]#

Die vollständige URL Ihres Azure AI Search-Dienstes

Validiert durch:

  • validate_endpoint

  • validate_interdependent_fields

field index_name: str [Erforderlich]#

Name des zu durchsuchenden Suchindexes

Validiert durch:

  • validate_interdependent_fields

field credential: AzureKeyCredential | AsyncTokenCredential [Erforderlich]#

Azure-Anmeldeinformationen für die Authentifizierung (API-Schlüssel oder Token)

Validiert durch:

  • validate_interdependent_fields

field api_version: str = '2023-10-01-preview'#

Azure AI Search API-Version, die verwendet werden soll. Standardmäßig 2023-10-01-preview.

Validiert durch:

  • validate_interdependent_fields

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

Art der durchzuführenden Suche: simple, full, semantic oder vector

Validiert durch:

  • normalize_query_type

  • validate_interdependent_fields

field search_fields: List[str] | None = None#

Felder, in denen in Dokumenten gesucht werden soll

Validiert durch:

  • validate_interdependent_fields

field select_fields: List[str] | None = None#

Felder, die in den Suchergebnissen zurückgegeben werden sollen

Validiert durch:

  • validate_interdependent_fields

field vector_fields: List[str] | None = None#

Felder, die für die Vektorsuche verwendet werden sollen

Validiert durch:

  • validate_interdependent_fields

field top: int | None = None#

Maximale Anzahl der zurückzugebenden Ergebnisse. Bei Vektorsuchen fungiert dies als k in k-NN.

Validiert durch:

  • validate_interdependent_fields

  • validate_top

field filter: str | None = None#

OData-Filterausdruck zur Verfeinerung von Suchergebnissen

Validiert durch:

  • validate_interdependent_fields

field semantic_config_name: str | None = None#

Name der semantischen Konfiguration für verbesserte Ergebnisse

Validiert durch:

  • validate_interdependent_fields

field enable_caching: bool = False#

Gibt an, ob Suchergebnisse zwischengespeichert werden sollen

Validiert durch:

  • validate_interdependent_fields

field cache_ttl_seconds: int = 300#

Wie lange Ergebnisse in Sekunden zwischengespeichert werden sollen

Validiert durch:

  • validate_interdependent_fields

field embedding_provider: str | None = None#

Name des Embedding-Providers für clientseitige Embeddings

Validiert durch:

  • validate_interdependent_fields

field embedding_model: str | None = None#

Modellname für clientseitige Embeddings

Validiert durch:

  • validate_interdependent_fields

field openai_api_key: str | None = None#

API-Schlüssel für OpenAI/Azure OpenAI-Embeddings

Validiert durch:

  • validate_interdependent_fields

field openai_api_version: str | None = None#

API-Version für Azure OpenAI-Embeddings

Validiert durch:

  • validate_interdependent_fields

feld openai_endpoint: str | None = None#

Endpunkt-URL für Azure OpenAI-Embeddings

Validiert durch:

  • validate_interdependent_fields

validator validate_endpoint  »  endpoint[Quelle]#

Validiert, dass der Endpunkt eine gültige URL ist.

validator normalize_query_type  »  query_type[Quelle]#

Normalisiert den Abfragetyp auf Standardwerte.

validator validate_top  »  top[Quelle]#

Stellt sicher, dass „top“ eine positive ganze Zahl ist, falls angegeben.

validator validate_interdependent_fields  »  alle Felder[Quelle]#

Validiert abhängige Felder, nachdem alle Felder analysiert wurden.

Klasse VectorizableTextQuery(*, text: str, k_nearest_neighbors: int | None = None, fields: str | None = None, exhaustive: bool | None = None, oversampling: float | None = None, weight: float | None = None, **kwargs: Any)[Quelle]#

Basiert auf: VectorQuery

Die Abfrageparameter für die Vektorsuche, wenn ein Textwert angegeben wird, der vektorisiert werden muss.

Alle erforderlichen Parameter müssen ausgefüllt sein, um an den Server gesendet zu werden.

Variablen:

  • kind (str oder VectorQueryKind) – Die Art der durchgeführten Vektorabfrage. Erforderlich. Bekannte Werte sind: „vector“ und „text“.

  • k_nearest_neighbors (int) – Anzahl der nächsten Nachbarn, die als Top-Treffer zurückgegeben werden sollen.

  • fields (str) – Vektorfelder vom Typ Collection(Edm.Single), die in der Vektorsuche einbezogen werden sollen.

  • exhaustive (bool) – Wenn true, wird eine erschöpfende k-nächste-Nachbarn-Suche über alle Vektoren im Vektorindex ausgelöst. Nützlich für Szenarien, in denen exakte Übereinstimmungen entscheidend sind, z. B. zur Ermittlung von Ground-Truth-Werten.

  • oversampling (float) – Übersampelfaktor. Minimalwert ist 1. Überschreibt den Parameter „defaultOversampling“, der in der Indexdefinition konfiguriert ist. Kann nur gesetzt werden, wenn „rerankWithOriginalVectors“ true ist. Dieser Parameter ist nur zulässig, wenn eine Komprimierungsmethode für das zugrunde liegende Vektorfeld verwendet wird.

  • weight (float) – Relatives Gewicht der Vektorabfrage im Vergleich zu anderen Vektorabfragen und/oder der Textabfrage innerhalb derselben Suchanfrage. Dieser Wert wird verwendet, wenn die Ergebnisse mehrerer Ranglisten, die von den verschiedenen Vektorabfragen erzeugt wurden, und/oder die über die Textabfrage abgerufenen Ergebnisse kombiniert werden. Je höher das Gewicht, desto weiter oben in der endgültigen Rangliste stehen die Dokumente, die dieser Abfrage entsprochen haben. Standard ist 1,0 und der Wert muss eine positive Zahl größer als Null sein.

  • text (str) – Der Text, der vektorisiert werden soll, um eine Vektorsuchabfrage durchzuführen. Erforderlich.

Auf dieser Seite
Auf GitHub bearbeiten
Quellcode anzeigen