byted-contextsearch（字节上下文搜索）

Context Search Skill

This skill provides two main capabilities for interacting with context-aware knowledge bases:

1. Search: Retrieve relevant documents based on text queries
2. Chat: Have conversations with RAG-powered systems

Configuration

This skill requires:

1. Environment Variable: Set the CTX_SEARCH_API_KEY environment variable with your API key: export CTX_SEARCH_API_KEY='your-api-key-here'
2. Config File: Create a config.json file in the skill directory with the following structure:

{
  "contexts": {
    "default": {
      "type": "",
      "base_url": "https://your-api-endpoint.com",
      "description": "Default context service"
    },
    "knowledge-base-a": {
      "type": "",
      "base_url": "https://another-endpoint.com",
      "description": "Knowledge base A for technical docs"
    }
  }
}

Context Type: Each context can optionally define a type:

• (empty / missing): Knowledge base (default; supports search and chat)
• image: Image context (supports search only)
• video: Video context (supports search only)

Multiple Knowledge Base Support: You can configure multiple knowledge bases for different scenarios in the config.json file. Each knowledge base is identified by a unique name (e.g., "default", "knowledge-base-a") and can have its own base_url and description. This allows you to:

• Separate knowledge bases by topic or domain (e.g., technical docs, product manuals, FAQs)
• Use different knowledge bases for different projects or teams
• Switch between knowledge bases using the --context parameter

Example configuration for multiple scenarios:

{
  "contexts": {
    "tech-docs": {
      "type": "",
      "base_url": "https://tech-docs.example.com",
      "description": "Technical documentation and API references"
    },
    "product-manuals": {
      "type": "",
      "base_url": "https://manuals.example.com",
      "description": "Product user manuals and guides"
    },
    "internal-wiki": {
      "type": "",
      "base_url": "https://wiki.example.com",
      "description": "Internal company knowledge base"
    },
    "image-index": {
      "type": "image",
      "base_url": "https://image.example.com",
      "description": "Image search context (search only)"
    }
  }
}

Usage

Running the Script

Important: The script must be run from the skill directory (where config.json is located).

cd <skill-directory>
uv run scripts/context_search.py <command> [args...] \
  || python3 scripts/context_search.py <command> [args...] \
  || python scripts/context_search.py <command> [args...]

List Available Knowledge Bases

List all configured knowledge bases:

uv run scripts/context_search.py list

Parameters:

• --json: Output raw JSON response (optional)

Example:

uv run scripts/context_search.py list

This will display all available knowledge bases with their descriptions and base URLs.

Search Function

Use the search function to retrieve relevant documents:

uv run scripts/context_search.py search \
  --context <context-name> \
  --text "your search query" \
  --mode <quick|normal|deep> \
  --size <number-of-results>

Parameters:

• --context: Name of the context service (default: "default")
• --text: The search query text
• --mode: Search mode - quick, normal, or deep (default: not sent, uses server default). Note: For image and video contexts, only quick mode is supported; if not specified, defaults to quick.
• --size: Number of results to return (default: not sent, uses server default)

Example:

uv run scripts/context_search.py search \
  --context knowledge-base-a \
  --text "how to implement authentication" \
  --mode deep \
  --size 10

Chat Function

Use the chat function to have conversations with the RAG system:

uv run scripts/context_search.py chat \
  --context <context-name> \
  --message "your message" \
  --mode <quick|normal|deep> \
  --size <number-of-results> \
  --stream

Parameters:

• --context: Name of the context service (default: "default")
• --message: The message to send
• --mode: Chat mode - quick, normal, or deep (default: not sent, uses server default)
• --size: Number of results to return (default: 5)
• --stream: Enable streaming output (optional flag)

Note: chat is only supported for knowledge base contexts (type is empty/missing). For type: "image" or type: "video", use search.

Example:

uv run scripts/context_search.py chat \
  --context default \
  --message "What are the best practices for API design?" \
  --mode deep \
  --size 10

Mode Descriptions

• quick: Fast response, suitable for simple queries
• normal: Balanced speed and quality (default)
• deep: Comprehensive search/chat, best for complex queries

Output Format

Search Output

Returns a JSON object with search results:

• Document ID
• Content
• Relevance score
• Metadata including retrieval score and index

Chat Output

Returns a JSON object with:

• Response content
• Token usage statistics
• Model information

Error Handling

The script will display error messages if:

• CTX_SEARCH_API_KEY environment variable is not set
• Configuration file is missing or invalid
• Network connection fails
• Invalid context name is provided

Setting Up Configuration

1. Set the environment variable: export CTX_SEARCH_API_KEY='your-api-key-here'
2. Copy the config.json.template file to config.json
3. Fill in the base URLs for each context service
4. Add as many context services as needed
5. Keep the config file secure and never commit it to version control