Weaviate 查询代理：使用方法

仅 Weaviate Cloud

Weaviate 查询代理是一种预构建的代理服务，旨在根据存储在 Weaviate Cloud 中的数据回答自然语言查询。

用户只需提供自然语言的提示/问题，查询代理就会负责所有中间步骤以提供答案。

本页描述了如何使用查询代理回答自然语言查询，使用存储在 Weaviate Cloud 中的数据。

先决条件

Weaviate 实例

此代理仅可用于 Weaviate Cloud 实例。请参阅 Weaviate Cloud 文档，了解有关如何设置 Weaviate Cloud 实例的更多信息。

您可以在 Weaviate Cloud 上使用免费的 Sandbox 实例试用此 Weaviate 代理。

客户端库

支持的语言

目前，此代理仅适用于 Python 和 TypeScript/JavaScript。未来将添加对其他语言的支持。

对于 Python，您可以安装带有可选的 agents 附加功能的 Weaviate 客户端库以使用 Weaviate 代理。这将安装 weaviate-agents 包以及 weaviate-client 包。对于 TypeScript/JavaScript，您可以安装 weaviate-agents 包以及 weaviate-client 包。

使用以下命令安装客户端库

Python (Agents)JavaScript/TypeScript (代理)

pip install -U weaviate-client[agents]

故障排除：强制 pip 安装最新版本

对于现有安装，即使 pip install -U "weaviate-client[agents]" 也可能无法将 weaviate-agents 升级到 最新版本。如果发生这种情况，请尝试显式升级 weaviate-agents 包

pip install -U weaviate-agents

或者安装一个 特定版本

pip install -U weaviate-agents==1.0.1

npm install weaviate-agents@latest

实例化查询代理

基本实例化

提供

• 目标 Weaviate Cloud 实例详细信息（例如，WeaviateClient 对象）。
• 要查询的默认集合列表

Python (Agents)JavaScript/TypeScript (代理)

import os
import weaviate
from weaviate.classes.init import Auth
from weaviate.agents.query import QueryAgent


headers = {
    # Provide your required API key(s), e.g. Cohere, OpenAI, etc. for the configured vectorizer(s)
    "X-INFERENCE-PROVIDER-API-KEY": os.environ.get("YOUR_INFERENCE_PROVIDER_KEY", ""),
}

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=os.environ.get("WEAVIATE_URL"),
    auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")),
    headers=headers,
)

# Instantiate a new agent object
qa = QueryAgent(
    client=client, collections=["ECommerce", "FinancialContracts", "Weather"]
)

import weaviate, { WeaviateClient, vectors, dataType, configure } from 'weaviate-client';
import { QueryAgent, ChatMessage } from 'weaviate-agents';

const headers = {
    //  Provide your required API key(s), e.g. Cohere, OpenAI, etc. for the configured vectorizer(s)
    // "X-INFERENCE-PROVIDER-API-KEY": process.env.YOUR_INFERENCE_PROVIDER_KEY,
};

const client = await weaviate.connectToWeaviateCloud(process.env.WEAVIATE_URL as string, {
    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY as string),
    headers
});
// Instantiate a new agent object
const queryAgent = new QueryAgent(
    client, {
    collections: ['ECommerce', 'FinancialContracts', 'Weather'],

});

配置集合

要查询的集合列表可以通过以下方式进一步配置

• 租户名称（多租户集合必需）
• 要查询的集合的目标向量（可选）
• 代理要使用的属性名称列表（可选）
• 其他过滤器始终应用于代理生成的过滤器之上（可选）

Python (Agents)JavaScript/TypeScript (代理)

from weaviate.agents.query import QueryAgent
from weaviate.agents.classes import QueryAgentCollectionConfig

qa = QueryAgent(
    client=client,
    collections=[
        QueryAgentCollectionConfig(
            name="ECommerce",  # The name of the collection to query
            target_vector=[
                "name_description_brand_vector"
            ],  # Target vector name(s) for collections with named vectors
            view_properties=[
                "name",
                "description",
                "price",
            ],  # Optional list of property names the agent can view
            # Optional tenant name for collections with multi-tenancy enabled
            # tenant="tenantA"
        ),
        QueryAgentCollectionConfig(name="FinancialContracts"),
        QueryAgentCollectionConfig(name="Weather"),
    ],
)

const qaWithConfig = new QueryAgent(client, {
    collections: [
        {
            name: 'ECommerce',
            targetVector: ['name_description_brand_vector'],
            viewProperties: ['description']
            // tenant: 'tenantA' // Optional for multi-tenancy
        },
        { name: 'FinancialContracts' },
        { name: 'Weather' }
    ]
});

查询代理可以访问什么？

查询代理从传递给它的 Weaviate 客户端对象派生其访问凭据。这可以通过提供给查询代理的集合名称进一步限制。

例如，如果关联的 Weaviate 凭据的用户只能访问一部分集合，则查询代理只能访问这些集合。

其他选项

查询代理可以使用其他选项进行实例化，例如

• system_prompt：自定义系统提示，用于替换 Weaviate 团队提供的默认系统提示（JavaScript 的 systemPrompt）。
• timeout：查询代理在单个查询上花费的最大时间，以秒为单位（服务器端默认值：60）。

对于长时间运行的查询

如果您遇到超时或预计需要很长时间的复杂查询，请考虑使用 流式响应以及增加超时值。

流式处理通过发送心跳来保持连接活跃，并在查询处理时提供进度更新，从而更好地处理长时间运行的请求。

自定义系统提示

您可以提供自定义系统提示来指导查询代理的行为

Python (Agents)JavaScript/TypeScript (代理)

from weaviate.agents.query import QueryAgent
from weaviate.agents.classes import QueryAgentCollectionConfig

# Define a custom system prompt to guide the agent's behavior
system_prompt = """You are a helpful assistant that can answer questions about the products and users in the database.
When you write your response use standard markdown formatting for lists, tables, and other structures.
Emphasize key insights and provide actionable recommendations when relevant."""

qa = QueryAgent(
    client=client,
    collections=[
        QueryAgentCollectionConfig(
            name="ECommerce",  # The name of the collection to query
            target_vector=[
                "name_description_brand_vector"
            ],  # Target vector name(s) for collections with multiple vectors
        ),
        "FinancialContracts",
        "Weather",
    ],
    system_prompt=system_prompt,
)

response = qa.ask("What are the most expensive items in the store?")
response.display()

// Define a custom system prompt to guide the agent's behavior
const systemPrompt = `You are a helpful assistant that can answer questions about the products and 
                      users in the database. When you write your response use standard markdown 
                      formatting for lists, tables, and other structures. Emphasize key insights 
                      and provide actionable recommendations when relevant.`

const qaWithPrompt = new QueryAgent(
    client, {
    collections: [{
            name: 'ECommerce',
            targetVector: ['name_description_brand_vector'],
            viewProperties: ['description']
            // tenant: 'tenantA' // Optional for multi-tenancy
        }, "FinancialContracts", "Weather"],
    systemPrompt: systemPrompt
})

const responseWithPrompt = await qaWithPrompt.ask("What are the most expensive items in the store?")

responseWithPrompt.display()

用户定义的过滤器

您可以应用持久过滤器，这些过滤器将始终与代理生成的过滤器结合使用，并使用逻辑 AND 运算。

Python (Agents)JavaScript/TypeScript (代理)

from weaviate.agents.query import QueryAgent
from weaviate.agents.classes import QueryAgentCollectionConfig
from weaviate.classes.query import Filter

# Apply persistent filters that will always be combined with agent-generated filters
qa = QueryAgent(
    client=client,
    collections=[
        QueryAgentCollectionConfig(
            name="ECommerce",
            # This filter ensures only items above $50 are considered
            additional_filters=Filter.by_property("price").greater_than(50),
            target_vector=[
                "name_description_brand_vector"
            ],  # Required target vector name(s) for collections with named vectors
        ),
    ],
)

# The agent will automatically combine these filters with any it generates
response = qa.ask("Find me some affordable clothing items")
response.display()

# You can also apply filters dynamically at runtime
runtime_config = QueryAgentCollectionConfig(
    name="ECommerce",
    additional_filters=Filter.by_property("category").equal("Footwear"),
    target_vector=[
        "name_description_brand_vector"
    ],  # Required target vector name(s) for collections with named vectors
)

response = qa.ask("What products are available?", collections=[runtime_config])
response.display()

// Apply persistent filters that will always be combined with agent-generated filters

const eCommerceCollection = client.collections.use("ECommerce")

const qaWithFilter = new QueryAgent(
    client, {
    collections: [{
            name: "ECommerce",
            // This filter ensures only items above $50 are considered
            additionalFilters: eCommerceCollection.filter.byProperty("price").greaterThan(50),
            targetVector:[
                "name_description_brand_vector"
            ],  // Required target vector name(s) for collections with named vectors
    }],
})

// The agent will automatically combine these filters with any it generates
const responseWithFilter = await qaWithFilter.ask("Find me some affordable clothing items")

responseWithFilter.display()

// You can also apply filters dynamically at runtime
const runtimeConfig = {
    name: "ECommerce",
    additionalFilters: eCommerceCollection.filter.byProperty("category").equal("Footwear"),
    targetVector:["name_description_brand_vector"]
}

const responseWithRuntimeFilter = await queryAgent.ask("What products are available?", {
    collections: [runtimeConfig]
})

responseWithRuntimeFilter.display()

异步 Python 客户端

有关使用异步 Python 客户端的示例，请参阅 异步 Python 客户端部分。

查询

查询代理支持两种查询类型

• 搜索
• 提问

搜索

使用自然语言使用查询代理搜索 Weaviate。查询代理将处理问题，在 Weaviate 中执行必要的搜索，并返回相关对象。

Python (Agents)JavaScript/TypeScript (代理)

# Perform a search using Search Mode (retrieval only, no answer generation)
search_response = qa.search("Find me some vintage shoes under $70", limit=10)

# Access the search results
for obj in search_response.search_results.objects:
    print(f"Product: {obj.properties['name']} - ${obj.properties['price']}")

// Perform a search using Search Mode (retrieval only, no answer generation)
const basicSearchResponse = await qa.search("Find me some vintage shoes under $70", {
    limit: 10
} )

// Access the search results
for (const obj of basicSearchResponse.searchResults.objects) {
    console.log(`Product: ${obj.properties['name']} - ${obj.properties['price']}`)
}

搜索响应结构

Python (Agents)JavaScript/TypeScript (代理)

# SearchModeResponse structure for Python
search_response = qa.search("winter boots for under $100", limit=5)

# Access different parts of the response
print(f"Original query: {search_response.searches[0].query}")
print(f"Total time: {search_response.total_time}")

# Access usage statistics
print(f"Usage statistics: {search_response.usage}")

# Access the searches performed (if any)
if search_response.searches:
    for search in search_response.searches:
        print(f"Search performed: {search}")

# Access the search results (QueryReturn object)
for obj in search_response.search_results.objects:
    print(f"Properties: {obj.properties}")
    print(f"Metadata: {obj.metadata}")

// SearchModeResponse structure for TypeScript
const searchResponse = await qa.search("winter boots for under $100", {
    limit: 5 
})

// Access different parts of the response
console.log("Original query:", basicQuery)
console.log("Total time:", searchResponse.totalTime)

// Access usage statistics
console.log("Usage statistics:", searchResponse.usage)

// Access the searches performed (if any)
if (searchResponse.searches) {
    for (const search in searchResponse.searches) {
        console.log("Search performed:", search)
    }
}
// Access the search results (QueryReturn object)
for (const obj of searchResponse.searchResults.objects){
    console.log("Properties:", obj.properties)
    console.log("Metadata:", obj.metadata)
}

示例输出

Original query: winter boots for under $100
Total time: 4.695224046707153
Usage statistics: requests=2 request_tokens=143 response_tokens=9 total_tokens=152 details=None
Search performed: queries=['winter boots'] filters=[[IntegerPropertyFilter(property_name='price', operator=<ComparisonOperator.LESS_THAN: '<'>, value=100.0)]] filter_operators='AND' collection='ECommerce'
Properties: {'name': 'Bramble Berry Loafers', 'description': 'Embrace your love for the countryside with our soft, hand-stitched loafers, perfect for quiet walks through the garden. Crafted with eco-friendly dyed soft pink leather and adorned with a subtle leaf embossing, these shoes are a testament to the beauty of understated simplicity.', 'price': 75.0}
Metadata: {'creation_time': None, 'last_update_time': None, 'distance': None, 'certainty': None, 'score': 0.4921875, 'explain_score': None, 'is_consistent': None, 'rerank_score': None}
Properties: {'name': 'Glitter Bootcut Fantasy', 'description': "Step back into the early 2000s with these dazzling silver bootcut jeans. Embracing the era's optimism, these bottoms offer a comfortable fit with a touch of stretch, perfect for dancing the night away.", 'price': 69.0}
Metadata: {'creation_time': None, 'last_update_time': None, 'distance': None, 'certainty': None, 'score': 0.47265625, 'explain_score': None, 'is_consistent': None, 'rerank_score': None}
Properties: {'name': 'Celestial Step Platform Sneakers', 'description': 'Stride into the past with these baby blue platforms, boasting a dreamy sky hue and cushy soles for day-to-night comfort. Perfect for adding a touch of whimsy to any outfit.', 'price': 90.0}
Metadata: {'creation_time': None, 'last_update_time': None, 'distance': None, 'certainty': None, 'score': 0.48828125, 'explain_score': None, 'is_consistent': None, 'rerank_score': None}
Properties: {'name': 'Garden Bliss Heels', 'description': 'Embrace the simplicity of countryside elegance with our soft lavender heels, intricately designed with delicate floral embroidery. Perfect for occasions that call for a touch of whimsy and comfort.', 'price': 90.0}
Metadata: {'creation_time': None, 'last_update_time': None, 'distance': None, 'certainty': None, 'score': 0.45703125, 'explain_score': None, 'is_consistent': None, 'rerank_score': None}
Properties: {'name': 'Garden Stroll Loafers', 'description': 'Embrace the essence of leisurely countryside walks with our soft, leather loafers. Designed for the natural wanderer, these shoes feature delicate, hand-stitched floral motifs set against a soft, cream background, making every step a blend of comfort and timeless elegance.', 'price': 90.0}
Metadata: {'creation_time': None, 'last_update_time': None, 'distance': None, 'certainty': None, 'score': 0.451171875, 'explain_score': None, 'is_consistent': None, 'rerank_score': None}

搜索分页

搜索支持分页，以有效地处理大型结果集

Python (Agents)JavaScript/TypeScript (代理)

# Search with pagination
response_page_1 = qa.search(
    "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'",
    limit=3,
)

# Get the next page of results
response_page_2 = response_page_1.next(limit=3, offset=3)

# Continue paginating
response_page_3 = response_page_2.next(limit=3, offset=3)

# Access results from each page
for page_num, page_response in enumerate(
    [response_page_1, response_page_2, response_page_3], 1
):
    print(f"Page {page_num}:")
    for obj in page_response.search_results.objects:
        # Safely access properties in case they don't exist
        name = obj.properties.get("name", "Unknown Product")
        price = obj.properties.get("price", "Unknown Price")
        print(f"  {name} - ${price}")
    print()

// Search with pagination
const responsePage1 = await qa.search(
    "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", {
    limit: 3,
})

// Get the next page of results
const responsePage2 = await responsePage1.next({
    limit: 3, 
    offset: 3, 
})

// Continue paginating
const responsePage3 = await responsePage2.next({
    limit: 3, 
    offset: 6, 
})

const pages = [responsePage1, responsePage2, responsePage3];

pages.forEach((pageResponse, index) => {
    const pageNum = index + 1;
    console.log(`Page ${pageNum}:`);
    
    pageResponse.searchResults.objects.forEach(obj => {
        // Safely access properties in case they don't exist
        const name = obj.properties.name || "Unknown Product";
        const price = obj.properties.price || "Unknown Price";
        console.log(`${name} - $${price}`);
    });
});

示例输出

Page 1:
  Glide Platforms - $90.0
  Garden Haven Tote - $58.0
  Sky Shimmer Sneaks - $69.0

Page 2:
  Garden Haven Tote - $58.0
  Celestial Step Platform Sneakers - $90.0
  Eloquent Satchel - $59.0

Page 3:
  Garden Haven Tote - $58.0
  Celestial Step Platform Sneakers - $90.0
  Eloquent Satchel - $59.0

提问

使用自然语言向查询代理提问。查询代理将处理问题，在 Weaviate 中执行必要的搜索，并返回答案。

仔细考虑你的查询

查询代理将根据您的查询制定其策略。因此，尽可能地努力使您的查询明确、完整但简洁。

Python (Agents)JavaScript/TypeScript (代理)

# Perform a query using Ask Mode (with answer generation)
response = qa.ask(
    "I like vintage clothes and nice shoes. Recommend some of each below $60."
)

# Print the response
response.display()

// Perform a query
const basicQuery = "I like vintage clothes and nice shoes. Recommend some of each below $60."
const basicResponse = await qaWithConfig.ask(basicQuery);

basicResponse.display();

在运行时配置集合

要查询的集合列表可以在查询时被覆盖，作为名称列表，或通过进一步的配置

仅指定集合名称

此示例仅为此查询覆盖配置的查询代理集合。

Python (Agents)JavaScript/TypeScript (代理)

response = qa.ask(
    "What kinds of contracts are listed? What's the most common type of contract?",
    collections=["FinancialContracts"],
)

response.display()

const contractResponse = await qa.ask(
    "What kinds of contracts are listed? What's the most common type of contract?", { 
    collections: ['FinancialContracts'] 
});

contractResponse.display();

详细配置集合

此示例仅为此查询覆盖配置的查询代理集合，指定了相关选项，例如

• 目标向量
• 要查看的属性
• 目标租户
• 其他过滤器

Python (Agents)JavaScript/TypeScript (代理)

from weaviate.agents.classes import QueryAgentCollectionConfig

response = qa.ask(
    "I like vintage clothes and nice shoes. Recommend some of each below $60.",
    collections=[
        # Use QueryAgentCollectionConfig class to provide further collection configuration
        QueryAgentCollectionConfig(
            name="ECommerce",  # The name of the collection to query
            target_vector=[
                "name_description_brand_vector"
            ],  # Required target vector name(s) for collections with named vectors
            view_properties=[
                "name",
                "description",
                "category",
                "brand",
            ],  # Optional list of property names the agent can view
        ),
        QueryAgentCollectionConfig(
            name="FinancialContracts",  # The name of the collection to query
            # Optional tenant name for collections with multi-tenancy enabled
            # tenant="tenantA"
        ),
    ],
)

response.display()

const clothingResponse = await qaWithConfig.ask(
    "I like vintage clothes and nice shoes. Recommend some of each below $60.", {
    collections: [
        {
            name: 'ECommerce',
            targetVector: ['name_description_brand_vector'],
            viewProperties: ['name', 'description', 'category', 'brand']
        },
        {
            name: 'FinancialContracts'
        }
    ]
});

clothingResponse.display();

对话查询

查询代理通过传递 ChatMessage 对象列表来支持多轮对话。这适用于 搜索 和 提问 查询类型。

在使用 ChatMessage 构建对话时，有两种可用的消息角色

• user - 代表提出问题或提供上下文的人类用户发出的消息
• assistant - 代表查询代理的响应或对话历史中的任何 AI 助手响应

对话历史记录有助于查询代理理解先前交流中的上下文，从而实现更连贯的多轮对话。始终在用户和助手角色之间交替，以保持适当的对话流程。

Python (Agents)JavaScript/TypeScript (代理)

from weaviate.agents.classes import ChatMessage

# Create a conversation with multiple turns
conversation = [
    ChatMessage(role="user", content="Hi!"),
    ChatMessage(role="assistant", content="Hello! How can I assist you today?"),
    ChatMessage(
        role="user",
        content="I have some questions about the weather data. You can assume the temperature is in Fahrenheit and the wind speed is in mph.",
    ),
    ChatMessage(
        role="assistant",
        content="I can help with that. What specific information are you looking for?",
    ),
]

# Add the user's query
conversation.append(
    ChatMessage(
        role="user",
        content="What's the average wind speed, the max wind speed, and the min wind speed",
    )
)

# Get the response
response = qa.ask(conversation)
print(response.final_answer)

# Continue the conversation
conversation.append(ChatMessage(role="assistant", content=response.final_answer))
conversation.append(ChatMessage(role="user", content="and for the temperature?"))

response = qa.ask(conversation)
print(response.final_answer)

// Create a conversation with multiple turns
const conversation: ChatMessage[] = [
    {   
        role: "user", 
        content: "Hi!"
    },
    {   
        role: "assistant", 
        content: "Hello! How can I assist you today?"
    },
    {
        role: "user",
        content:  "I have some questions about the weather data. You can assume the temperature is in Fahrenheit and the wind speed is in mph.",
    },
    {
        role: "assistant",
        content:  "I can help with that. What specific information are you looking for?",
    },
]

// Add the user's query
conversation.push(
    {
        role: "user",
        content:  "What's the average wind speed, the max wind speed, and the min wind speed",
    }
)

// Get the response
const response = await qaWithConfig.ask(conversation)
console.log(response.finalAnswer)

// Continue the conversation
conversation.push({role: "assistant", content:  response.finalAnswer})
conversation.push({role: "user", content:  "and for the temperature?"})

const followUpResponse = await qaWithConfig.ask(conversation)
console.log(followUpResponse.finalAnswer)

流式响应

查询代理还可以流式传输响应，允许您在生成时接收答案。

可以使用以下可选参数请求流式响应

• include_progress：如果设置为 True，查询代理将在处理查询时流式传输进度更新。
• include_final_state：如果设置为 True，查询代理将流式传输生成的最终答案，而不是在返回之前等待整个答案生成。

如果 include_progress 和 include_final_state 都设置为 False，查询代理将仅包含生成的答案标记，而不提供任何进度更新或最终状态。

Python (Agents)JavaScript/TypeScript (代理)

from weaviate.agents.classes import ProgressMessage, StreamedTokens

for output in qa.ask_stream(
    query,
    # Setting this to false will skip ProgressMessages, and only stream
    # the StreamedTokens / the final QueryAgentResponse
    include_progress=True,  # Default is True
    include_final_state=True,  # Default is True
):
    if isinstance(output, ProgressMessage):
        # The message is a human-readable string, structured info available in output.details
        print(output.message)
    elif isinstance(output, StreamedTokens):
        # The delta is a string containing the next chunk of the final answer
        print(output.delta, end="", flush=True)
    else:
        # This is the final response, as returned by QueryAgent.ask()
        output.display()

// Setting includeProgress to false will skip progressMessages, and only stream
// the streamedTokens / the final response.
for await (const event of qa.askStream(query, {
    includeProgress: true,      // Default: True
    includeFinalState: true,    // Default: True
})) {
    if (event.outputType === "progressMessage") {
        // The message is a human-readable string, structured info available in event.details
        console.log(event.message);
    } else if (event.outputType === "streamedTokens") {
        // The delta is a string containing the next chunk of the final answer
        process.stdout.write(event.delta);
    } else {
        // This is the final response, as returned by queryAgent.ask()
        event.display();
    }
}

检查响应

查询代理的响应将包含最终答案以及其他支持信息。

支持信息可能包括执行的搜索或聚合、可能缺少的信息以及代理使用的 LLM 令牌数量。

辅助函数

尝试提供的辅助函数（例如，.display() 方法）以可读格式显示响应。

Python (Agents)JavaScript/TypeScript (代理)

# Perform a query using Ask Mode (with answer generation)
response = qa.ask(
    "I like vintage clothes and nice shoes. Recommend some of each below $60."
)

# Print the response
response.display()

// Perform a query
const basicQuery = "I like vintage clothes and nice shoes. Recommend some of each below $60."
const basicResponse = await qaWithConfig.ask(basicQuery);

basicResponse.display();

这将打印响应和查询代理找到的支持信息摘要。

示例输出

╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────── 🔍 Original Query ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                   │
│ I like vintage clothes and nice shoes. Recommend some of each below $60.                                                                                                                                                                          │
│                                                                                                                                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────── 📝 Final Answer ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                   │
│ For vintage clothing under $60, you might like the Vintage Philosopher Midi Dress by Echo & Stitch. It features deep green velvet fabric with antique gold button details, tailored fit, and pleated skirt, perfect for a classic vintage look.   │
│                                                                                                                                                                                                                                                   │
│ For nice shoes under $60, consider the Glide Platforms by Vivid Verse. These are high-shine pink platform sneakers with cushioned soles, inspired by early 2000s playful glamour, offering both style and comfort.                                │
│                                                                                                                                                                                                                                                   │
│ Both options combine vintage or retro aesthetics with an affordable price point under $60.                                                                                                                                                        │
│                                                                                                                                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────── 🔭 Searches Executed 1/2 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                   │
│ QueryResultWithCollection(queries=['vintage clothing'], filters=[[]], filter_operators='AND', collection='ECommerce')                                                                                                                             │
│                                                                                                                                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────── 🔭 Searches Executed 2/2 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                   │
│ QueryResultWithCollection(queries=['nice shoes'], filters=[[]], filter_operators='AND', collection='ECommerce')                                                                                                                                   │
│                                                                                                                                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                   │
│ 📊 No Aggregations Run                                                                                                                                                                                                                            │
│                                                                                                                                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 📚 Sources ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                   │
│  - object_id='a7aa8f8a-f02f-4c72-93a3-38bcbd8d5581' collection='ECommerce'                                                                                                                                                                        │
│  - object_id='ff5ecd6e-8cb9-47a0-bc1c-2793d0172984' collection='ECommerce'                                                                                                                                                                        │
│                                                                                                                                                                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯


  📊 Usage Statistics
┌────────────────┬─────┐
│ LLM Requests:  │ 5   │
│ Input Tokens:  │ 288 │
│ Output Tokens: │ 17  │
│ Total Tokens:  │ 305 │
└────────────────┴─────┘

Total Time Taken: 7.58s

检查示例

此示例输出

• 原始用户查询
• 查询代理提供的答案
• 查询代理进行的搜索和聚合（如果有）
• 任何缺失的信息

Python (Agents)JavaScript/TypeScript (代理)

print("\n=== Query Agent Response ===")
print(f"Original Query: {response.searches[0].query}\n")

print("🔍 Final Answer Found:")
print(f"{response.final_answer}\n")

print("🔍 Searches Executed:")
for collection_searches in response.searches:
    for result in collection_searches:
        print(f"- {result}\n")

if len(response.aggregations) > 0:
    print("📊 Aggregation Results:")
    for collection_aggs in response.aggregations:
        for agg in collection_aggs:
            print(f"- {agg}\n")

if response.missing_information:
    if response.is_partial_answer:
        print("⚠️ Answer is Partial - Missing Information:")
    else:
        print("⚠️ Missing Information:")
    for missing in response.missing_information:
        print(f"- {missing}")

console.log('\n=== Query Agent Response ===');
console.log(`Original Query: ${basicQuery}\n`); // Pre-defined by user

console.log('🔍 Final Answer Found:');
console.log(`${basicResponse.finalAnswer}\n`);

console.log('🔍 Searches Executed:');
for (const collectionSearches of basicResponse.searches) {
        console.log(`- ${collectionSearches.query}\n`);
}

if (basicResponse.aggregations) {
    console.log('📊 Aggregation Results:');
    for (const collectionAggs of basicResponse.aggregations) {
        for (const agg in collectionAggs) {
            console.log(`- ${agg}\n`);
        }
    }
}

if (basicResponse.missingInformation && basicResponse.missingInformation.length > 0) {
    if (basicResponse.isPartialAnswer) {
        console.log('⚠️ Answer is Partial - Missing Information:');
    } else {
        console.log('⚠️ Missing Information:');
    }
    for (const missing of basicResponse.missingInformation) {
        console.log(`- ${missing}`);
    }
}

示例输出

=== Query Agent Response ===
Original Query: vintage style clothing

🔍 Final Answer Found:
For vintage-style clothing under $60, I recommend the Vintage Scholar Turtleneck priced at $55. It features a soft, stretchable fabric with timeless pleated details, perfect for a Dark Academia-inspired intellectual and moody look, whether layered or worn solo.

However, based on the available information, no shoes under $60 were found. If you want, I can help search further for nice shoes within your budget. Let me know!

🔍 Searches Executed:
- ('query', 'vintage style clothing')

- ('filters', IntegerPropertyFilter(property_name='price', operator=<ComparisonOperator.LESS_THAN: '<'>, value=60.0))

- ('collection', 'ECommerce')

- ('query', 'nice shoes')

- ('filters', IntegerPropertyFilter(property_name='price', operator=<ComparisonOperator.LESS_THAN: '<'>, value=60.0))

- ('collection', 'ECommerce')

⚠️ Answer is Partial - Missing Information:
- No recommendations were provided for nice shoes under $60, though the user specifically requested shoes as well as vintage clothes.

使用 - 异步 Python 客户端

如果您正在使用异步 Python Weaviate 客户端，则实例化模式保持不变。区别在于使用 AsyncQueryAgent 类而不是 QueryAgent 类。

生成的异步模式如下所示

Python (Agents)

import asyncio
import os
import weaviate
from weaviate.agents.query import AsyncQueryAgent


async_client = weaviate.use_async_with_weaviate_cloud(
    cluster_url=os.environ.get("WEAVIATE_URL"),
    auth_credentials=os.environ.get("WEAVIATE_API_KEY"),
    headers=headers,
)


async def query_vintage_clothes(async_query_agent: AsyncQueryAgent):
    response = await async_query_agent.ask(
        "I like vintage clothes and nice shoes. Recommend some of each below $60."
    )
    return ("Vintage Clothes", response)


async def query_financial_data(async_query_agent: AsyncQueryAgent):
    response = await async_query_agent.ask(
        "What kinds of contracts are listed? What's the most common type of contract?",
    )
    return ("Financial Contracts", response)


async def run_concurrent_queries():
    try:
        await async_client.connect()

        async_qa = AsyncQueryAgent(
            async_client,
            collections=[
                QueryAgentCollectionConfig(
                    name="ECommerce",  # The name of the collection to query
                    target_vector=[
                        "name_description_brand_vector"
                    ],  # Optional target vector name(s) for collections with named vectors
                    view_properties=[
                        "name",
                        "description",
                        "category",
                        "brand",
                    ],  # Optional list of property names the agent can view
                ),
                QueryAgentCollectionConfig(
                    name="FinancialContracts",  # The name of the collection to query
                    # Optional tenant name for collections with multi-tenancy enabled
                    # tenant="tenantA"
                ),
            ],
        )

        # Wait for both to complete
        vintage_response, financial_response = await asyncio.gather(
            query_vintage_clothes(async_qa), query_financial_data(async_qa)
        )

        # Display results
        print(f"=== {vintage_response[0]} ===")
        vintage_response[1].display()

        print(f"=== {financial_response[0]} ===")
        financial_response[1].display()

    finally:
        await async_client.close()


asyncio.run(run_concurrent_queries())

流式传输

异步查询代理也可以流式传输响应，允许您在生成时接收答案。

Python (Agents)

async def stream_query(async_query_agent: AsyncQueryAgent):
    async for output in async_query_agent.ask_stream(
        "What are the top 5 products sold in the last 30 days?",
        # Setting this to false will skip ProgressMessages, and only stream
        # the StreamedTokens / the final QueryAgentResponse
        include_progress=True,  # Default is True
    ):
        if isinstance(output, ProgressMessage):
            # The message is a human-readable string, structured info available in output.details
            print(output.message)
        elif isinstance(output, StreamedTokens):
            # The delta is a string containing the next chunk of the final answer
            print(output.delta, end="", flush=True)
        else:
            # This is the final response, as returned by QueryAgent.ask()
            output.display()


async def run_streaming_query():
    try:
        await async_client.connect()
        async_qa = AsyncQueryAgent(
            async_client,
            collections=[
                QueryAgentCollectionConfig(
                    name="ECommerce",  # The name of the collection to query
                    target_vector=[
                        "name_description_brand_vector"
                    ],  # Optional target vector name(s) for collections with named vectors
                    view_properties=[
                        "name",
                        "description",
                        "category",
                        "brand",
                    ],  # Optional list of property names the agent can view
                ),
                QueryAgentCollectionConfig(
                    name="FinancialContracts",  # The name of the collection to query
                    # Optional tenant name for collections with multi-tenancy enabled
                    # tenant="tenantA"
                ),
            ],
        )
        await stream_query(async_qa)

    finally:
        await async_client.close()


asyncio.run(run_streaming_query())

限制与故障排除

使用限制

每个 Weaviate Cloud 组织每月最多可以免费进行 1,000 次查询代理请求。

请求根据查询类型消耗

• Ask：每个查询 4 个请求
• Search：每个查询 1 个请求

此限制可能会在未来发生变化。有关使用限制的问题，请联系 product@weaviate.io。

自定义集合描述

查询代理会利用每个集合的 description 元数据以及各个属性描述来决定查询哪个集合。

集合描述和属性描述都可以在集合创建后更新。有关更新集合和属性描述的详细说明，请参阅 更新集合定义文档。

我们正在研究在运行时指定自定义集合描述的能力。

执行时间

查询代理执行多个操作，将自然语言查询转换为 Weaviate 查询，并处理响应。

这通常需要多次调用生成模型（例如 LLM）和多次查询 Weaviate。

因此，每次查询代理运行可能需要一些时间才能完成。根据查询的复杂性，执行时间达到 ~10 秒的情况并不少见。

对于长时间运行或复杂的查询，请考虑使用 流式响应，而不是非流式请求。流式传输提供进度更新并发送心跳以保持连接，从而防止长时间运行的非流式请求可能发生的超时问题。

问题和反馈

如果您有任何问题或反馈，请在 用户论坛 中告诉我们。

技术问题

如果您有任何问题，请在我们的 社区论坛 上发帖。

文档反馈

通过打开 GitHub issue 提供反馈。