Search Agent
基于 Pydantic AI 的智能搜索 Agent，能够理解用户查询意图、自动规划搜索策略、从多个来源获取信息，并生成高质量、有来源引用的答案。
功能特点
| 能力 | 描述 |
|---|---|
| 🧠 查询理解 | 分析用户意图，提取关键实体，生成扩展查询 |
| 📋 搜索规划 | 智能分解问题，制定搜索策略 |
| 🔎 多源搜索 | 支持Web搜索和新闻搜索 |
| 📄 内容提取 | 智能提取网页核心内容 |
| 🎯 结果排序 | 基于相关性重排搜索结果 |
| ✍️ 答案生成 | 综合信息生成结构化回答 |
| 🔄 自我反思 | 评估答案质量，决定是否迭代 |
| ⚡ 并行优化 | 流水线执行，高置信度快速返回 |
性能优化
本 Agent 实现了多项并行优化，显著提升响应速度：
流水线模式（Pipeline Mode）
传统模式下，搜索和内容提取是串行执行的：
搜索任务1 → 搜索任务2 → 搜索任务3 → 等待全部完成 → 内容提取
流水线模式下，搜索完成后立即开始提取：
搜索任务1完成 → 立即开始提取1
搜索任务2完成 → 立即开始提取2
搜索任务3完成 → 立即开始提取3
预期收益：减少 3-8 秒等待时间
高置信度快速返回
对于简单查询（事实查询、操作指南），如果答案置信度为 high，则跳过反思评估步骤，直接返回结果。
预期收益：减少 1-3 秒 LLM 调用时间
性能对比
| 场景 | 优化前耗时 | 优化后耗时 | 提升 |
|---|---|---|---|
| 简单事实查询 | 15-25秒 | 8-15秒 | 40-50% |
| 复杂研究查询 | 30-60秒 | 20-40秒 | 30-40% |
快速开始
1. 安装依赖
cd search_agent
pip install -r requirements.txt
2. 配置环境变量
# LLM 配置
export OPENAI_BASE_URL=https://your-litellm-gateway/v1
export OPENAI_API_KEY=your-api-key
export MODEL_NAME=taiji/gpt-4o-mini
# Serper API（Google搜索）
export SERPER_API_KEY=your-serper-key
# Jina API（内容提取和重排序）
export JINA_API_KEY=your-jina-key
# 可选配置
export MAX_ITERATIONS=3
export MAX_RESULTS_PER_QUERY=10
export CONTENT_MAX_LENGTH=5000
export API_PORT=8000
3. 本地测试
python run_api_server.py
4. 构建镜像
docker build -t search-agent:latest .
项目结构
search_agent/
├── Dockerfile
├── requirements.txt
├── run_api_server.py # 启动脚本
└── src/
├── __init__.py
└── server/
├── __init__.py
├── api_server.py # FastAPI + MCP HTTP
├── mcp_server.py # MCP 工具定义
└── core/ # 业务逻辑
├── config.py # 配置管理
├── agent.py # SearchAgent 主类
├── schemas.py # 数据模型
├── prompts.py # Prompt 模板
├── modules/ # 功能模块
│ ├── query_analyzer.py
│ ├── search_planner.py
│ ├── search_executor.py
│ ├── content_extractor.py
│ ├── result_processor.py
│ ├── answer_generator.py
│ └── reflector.py
├── tools/ # 外部 API 封装
│ ├── serper.py
│ ├── jina_reader.py
│ └── jina_reranker.py
└── utils/ # 工具函数
├── llm_client.py
└── helpers.py
API 端点
健康检查
GET /- 服务状态GET /health- 健康检查
MCP 端点
POST /mcp- MCP HTTP 端点GET /mcp/sse- MCP SSE 端点POST /mcp/sse- MCP SSE POST 端点
REST API
POST /api/v1/search- 智能搜索POST /api/v1/quick_search- 快速搜索GET /api/v1/tools- 获取工具列表
MCP 工具
search
执行智能搜索，支持多轮迭代和自我反思。
{
"query": "什么是Kubernetes？",
"max_iterations": 3
}
quick_search
快速搜索，单次迭代，适合简单问题。
{
"query": "Python是什么？"
}
使用示例
Python
import requests
# 智能搜索
response = requests.post(
"http://localhost:8000/api/v1/search",
headers={"api-key": "your-api-key"},
json={"query": "什么是Kubernetes？", "max_iterations": 3},
timeout=120
)
result = response.json()
print(result["answer"]["content"])
cURL
curl -X POST "http://localhost:8000/api/v1/search" \
-H "api-key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"query": "什么是Kubernetes？"}'
环境变量
| 变量 | 必需 | 说明 | 默认值 |
|---|---|---|---|
| OPENAI_BASE_URL | 是 | LiteLLM Gateway URL | - |
| OPENAI_API_KEY | 是 | API Key | sk |
| MODEL_NAME | 否 | 模型名称 | taiji/gpt-4o-mini |
| SERPER_API_KEY | 是 | Serper API Key | - |
| JINA_API_KEY | 是 | Jina API Key | - |
| MAX_ITERATIONS | 否 | 最大迭代次数 | 3 |
| MAX_RESULTS_PER_QUERY | 否 | 每次搜索结果数 | 10 |
| CONTENT_MAX_LENGTH | 否 | 内容最大长度 | 5000 |
| API_PORT | 否 | 服务端口 | 8000 |
| LOG_LEVEL | 否 | 日志级别 | INFO |
| TIMEOUT | 否 | 请求超时时间 | 30 |
| 并行优化配置 | |||
| MAX_CONCURRENT_EXTRACTION | 否 | 内容提取最大并发数 | 10 |
| ENABLE_PIPELINE_MODE | 否 | 启用流水线模式 | true |
| ENABLE_FAST_RETURN | 否 | 启用高置信度快速返回 | true |
注册到 Agent Manager
在 k8s_manager.py 中添加：
# TEMPLATE_PORTS
"search_agent": 8000,
# image_map
"search_agent": "agnettaiji.azurecr.io/ai-agents/search-agent:latest",
在 app.py 的 valid_templates 中添加 "search_agent"。