websearch

Web Search Plugin Configuration Guide

Overview

The Web Search Plugin is a plugin that provides real-time web search capabilities for AI models, supporting multiple search engines (Google, Bing, BingCN, Arxiv, SearchXNG), with automatic search query rewriting and search result formatting.

Configuration Example

{
    "model": "claude-3-7-sonnet-20250219",
    "retry_times": 5,
    "owner": "anthropic",
    "type": 1,
    "plugin": {
        "web-search": {
            "enable": true,
            "force_search": true,
            "search_rewrite": {
                "enable": true,
                "add_rewrite_usage": true,
                "rewrite_usage_field": "rewrite_usage"
            },
            "need_reference": true,
            "reference_location": "content",
            "search_from": [
                {
                    "type": "google",
                    "spec": {
                        "api_key": "api key",
                        "cx": "cx"
                    }
                }
            ]
        }
    }
}

Model Config Field Details

Basic Configuration

Web Search Plugin Configuration

Main Configuration Items

Search Rewrite Configuration (search_rewrite)

Search Engine Configuration (search_from)

Each search engine configuration contains the following fields:

{
    "type": "google",
    "spec": {
        "api_key": "your_google_api_key",
        "cx": "your_custom_search_engine_id"
    }
}

{
    "type": "bing",
    "spec": {
        "api_key": "your_bing_api_key"
    }
}

{
    "type": "bingcn",
    "spec": {}
}

BingCN search engine requires no additional configuration parameters.

{
    "type": "arxiv",
    "spec": {}
}

Arxiv search engine requires no additional configuration parameters.

{
    "type": "searchxng",
    "spec": {
        "base_url": "https://searchxng.com"
    }
}

User Request Configuration

web_search_options Field

Users can add the web_search_options field in their requests to control search behavior:

{
    "model": "claude-3-7-sonnet-20250219",
    "messages": [
        {
            "role": "user",
            "content": "Please search for the latest AI technology developments"
        }
    ],
    "web_search_options": {
        "enable": true,
        "search_context_size": "medium"
    }
}

web_search_options Configuration Items

search_context_size Details

The search_context_size field controls the breadth and depth of searches:

• low: Generates 1 search query, suitable for simple, direct questions
• medium: Generates 3 search queries (default), suitable for most scenarios
• high: Generates 5 search queries, suitable for complex questions or scenarios requiring comprehensive information

This field overrides the search_rewrite.max_count value in the configuration, allowing users to dynamically adjust search strategy based on specific needs.

Conditions for Enabling Search

The Web Search plugin is enabled under the following conditions:

1. Default Enable: When force_search is true in the configuration, all requests will enable search
2. On-Demand Enable: When force_search is false, only requests containing the web_search_options field will enable search

Usage Examples

Basic Search Request

{
    "model": "claude-3-7-sonnet-20250219",
    "messages": [
        {
            "role": "user",
            "content": "What's the weather like today?"
        }
    ],
    "web_search_options": {
        "enable": true
    }
}

High-Precision Search Request

{
    "model": "claude-3-7-sonnet-20250219",
    "messages": [
        {
            "role": "user",
            "content": "Analyze the latest applications and development trends of artificial intelligence in the medical field"
        }
    ],
    "web_search_options": {
        "enable": true,
        "search_context_size": "high"
    }
}

Usage Instructions

Basic Usage

1. Enable Plugin: Set enable to true
2. Configure Search Engines: Add at least one search engine configuration in the search_from array
3. Set Default Behavior: Control whether to enable search by default through force_search
4. User Control: Users can control search behavior through the web_search_options field

Advanced Features

Search Query Rewriting

When search_rewrite.enable is enabled, the plugin will use AI models to automatically optimize user search queries, improving the relevance of search results.

Reference Management

When need_reference is true:

• Search results will include numbered references [1], [2], etc.
• Reference display position can be controlled through reference_location
• Reference format can be customized through reference_format

Dynamic Search Control

Users can dynamically adjust search depth through the search_context_size parameter:

• Use low for simple questions to reduce latency
• Use high for complex questions to get more comprehensive information
• Use medium by default to balance performance and quality

Important Notes

1. API Keys: Ensure valid API keys are provided for selected search engines
2. Quota Limits: Be aware of API call quota limits for various search engines
3. Performance Impact: Enabling search functionality will increase response time; higher search_context_size settings result in greater latency
4. Cost Considerations: Search API calls and additional AI model calls will incur costs
5. Request Cleanup: The web_search_options field is automatically removed from requests after processing

Troubleshooting

• If search functionality is not working, check if enable is set to true
• Verify that search engine API keys are correctly configured
• Ensure the model supports Chat Completions mode
• Check network connectivity and API service availability
• Ensure the request contains the web_search_options field (when force_search is false)