LLM搜索功能API使用指南

概述

LLM搜索功能为对话API提供了实时信息检索能力，支持联网搜索、垂直领域搜索等高级功能。

API端点

1. 统一对话端点（推荐）

端点: POST /api/llm/chat

特性:

自动检测搜索选项
完全向后兼容
支持流式和非流式输出

请求示例:

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "今天北京天气怎么样？"
    }
  ],
  "stream": false,
  "search_options": {
    "enable_search": true,
    "search_strategy": "turbo",
    "enable_source": true,
    "enable_citation": true
  }
}

2. 专用搜索端点

端点: POST /api/llm/chat/search

特性:

专门用于搜索增强对话
支持所有搜索选项
支持流式和非流式输出

搜索选项配置

SearchOptions 参数说明

搜索策略说明

turbo: 快速搜索模式，响应速度快
max: 多源详尽搜索模式，结果更全面
agent: 多轮检索整合模式，智能程度最高

时效性控制

仅对 turbo 策略生效：

7: 最近7天的内容
30: 最近30天的内容
180: 最近180天的内容
365: 最近365天的内容

使用示例

基础搜索

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "最新的AI技术发展如何？"
    }
  ],
  "search_options": {
    "enable_search": true
  }
}

垂直领域搜索

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "今天上海的天气和股市情况"
    }
  ],
  "search_options": {
    "enable_search": true,
    "enable_search_extension": true,
    "search_strategy": "max"
  }
}

带引用的搜索

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "2024年人工智能的重要突破有哪些？"
    }
  ],
  "search_options": {
    "enable_search": true,
    "enable_source": true,
    "enable_citation": true,
    "citation_format": "[ref_<number>]"
  }
}

流式搜索

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "最新的科技新闻"
    }
  ],
  "stream": true,
  "search_options": {
    "enable_search": true,
    "prepend_search_result": true,
    "enable_source": true
  }
}

响应格式

非流式响应

{
  "code": 200,
  "message": "success",
  "data": {
    "content": "根据最新信息，今天北京天气晴朗...[1]",
    "finish_reason": "stop",
    "usage": {
      "input_tokens": 15,
      "output_tokens": 120,
      "total_tokens": 135
    },
    "search_info": {
      "search_results": [...]
    },
    "search_results": [
      {
        "index": 1,
        "title": "北京天气预报",
        "url": "https://weather.example.com",
        "snippet": "今天北京天气晴朗，温度25度..."
      }
    ]
  }
}

流式响应

data: {"content": "根据最新", "search_results": [...]}

data: {"content": "信息，今天北京天气"}

data: {"content": "晴朗", "finish_reason": "stop"}

data: [DONE]

辅助API

获取支持搜索的模型列表

端点: GET /api/llm/search/models

响应:

{
  "code": 200,
  "message": "success",
  "data": ["qwen-plus", "qwen-turbo", "qwen-max"]
}

检查模型搜索支持

端点: GET /api/llm/search/check/{model}

响应:

{
  "code": 200,
  "message": "success",
  "data": {
    "model": "qwen-plus",
    "search_supported": true
  }
}

错误处理

常见错误码

403: 未配置API密钥
400: 参数验证失败
500: 服务异常

错误响应示例

{
  "code": 403,
  "message": "未配置API密钥，请在用户设置中配置apikey",
  "data": null
}

向后兼容性

现有的 /api/llm/chat 端点完全向后兼容
不提供 search_options 时自动使用普通对话模式
提供 search_options 且 enable_search: true 时自动启用搜索功能

高级功能示例

组合功能使用

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "分析一下最近AI领域的投资趋势"
    }
  ],
  "search_options": {
    "enable_search": true,
    "search_strategy": "agent",
    "forced_search": true,
    "enable_search_extension": true,
    "freshness": 30,
    "enable_source": true,
    "enable_citation": true,
    "citation_format": "[ref_<number>]",
    "prepend_search_result": false,
    "intention_options": {
      "prompt_intervene": "重点搜索权威投资机构和知名财经媒体的AI投资分析报告"
    }
  }
}

多轮对话搜索

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的信息助手，擅长提供准确的实时信息。"
    },
    {
      "role": "user",
      "content": "今天杭州天气如何？"
    },
    {
      "role": "assistant", 
      "content": "根据最新信息，杭州今天天气晴朗，气温25度。"
    },
    {
      "role": "user",
      "content": "那明天呢？会下雨吗？"
    }
  ],
  "search_options": {
    "enable_search": true,
    "enable_search_extension": true,
    "freshness": 1
  }
}

错误处理示例

{
  "code": 400,
  "message": "模型不支持搜索功能",
  "data": {
    "model": "unsupported-model",
    "supported_models": ["qwen-plus", "qwen-turbo", "qwen-max"],
    "error_type": "model_compatibility"
  }
}

性能优化建议

1. 搜索策略选择指南

参数	类型	默认值	说明
`enable_search`	boolean	false	是否启用联网搜索
`search_strategy`	string	"turbo"	搜索策略：turbo/max/agent
`forced_search`	boolean	false	是否强制搜索
`enable_search_extension`	boolean	false	是否启用垂域搜索
`freshness`	number	null	搜索时效性（天）：7/30/180/365
`enable_source`	boolean	false	是否返回搜索来源
`enable_citation`	boolean	false	是否启用角标引用
`citation_format`	string	"[]"	角标格式
`prepend_search_result`	boolean	false	是否提前返回搜索结果
`intention_options`	object	null	自然语言搜索控制

场景	推荐策略	原因
实时新闻查询	turbo	速度快，时效性好
学术研究	max	结果全面，多源整合
复杂分析	agent	智能程度高，多轮优化
垂直领域查询	turbo	专业数据，响应迅速

2. 缓存策略

# 启用搜索结果缓存
export LLM_SEARCH_CACHE_ENABLED=true
export LLM_SEARCH_CACHE_TTL=300  # 5分钟缓存

# 缓存键策略
# 基于: 查询内容 + 搜索选项 + 模型名称

3. 并发控制

# 限制并发搜索请求
export SEARCH_CONNECTION_POOL_SIZE=10
export SEARCH_USER_RATE_LIMIT=10  # 每用户每分钟10次

监控和日志

关键指标

搜索成功率: 应保持在95%以上
平均响应时间: 应在5秒以内
降级触发频率: 应低于5%
缓存命中率: 应在30%以上

日志示例

INFO: 搜索请求 - 用户:user123, 模型:qwen-plus, 策略:turbo
INFO: 搜索完成 - 耗时:2.3s, 结果数:3, 缓存:miss
WARNING: 搜索降级 - 原因:api_timeout, 降级到普通对话
ERROR: 搜索失败 - 错误:rate_limit_exceeded, 用户:user456

最佳实践

选择合适的搜索策略：
- 实时信息查询使用 turbo
- 深度研究使用 max
- 复杂问题使用 agent
合理使用时效性控制：
- 新闻类查询设置较短时效性（7-30天）
- 技术文档查询可设置较长时效性（180-365天）
启用引用功能：
- 重要信息查询建议启用 enable_source 和 enable_citation
- 便于用户验证信息来源
流式输出优化：
- 长对话建议启用 stream: true
- 可选择启用 prepend_search_result 提前显示搜索来源
使用搜索指导：
- 通过 intention_options 精确控制搜索范围
- 指导语句要具体明确，避免过于宽泛
垂直领域搜索：
- 专业领域查询启用 enable_search_extension
- 支持天气、股票、汇率等11个垂直领域
错误处理：
- 实现搜索失败的降级机制
- 记录详细的错误日志便于调试
性能优化：
- 合理设置超时时间
- 启用结果缓存
- 控制并发请求数量

MD006_联网搜索.md 8.5 KB Permalink Verlauf Originalformat