AI Search Agent v2.0

企业级 Agentic 搜索系统，完整集成多轮规划、多源搜索、智能重排、知识抽取与缓存能力。

核心能力清单

能力	说明
LLM 驱动多轮规划	模型自主分解查询、规划下一轮搜索
多语言扩展	CJK 自动翻译为英文，双语并行检索
Jina Reranker 语义重排	按查询相关性重排页面顺序
置信度自评 + 自动补搜	LLM 返回置信度，不足时自动触发补搜
追问建议（Follow-up）	生成 3 条推荐的后续问题
Token 级流式输出	LLM 回答逐字流式返回，非事件粒度
双模式搜索预算	fast 最长 60 秒，deep 最长 300 秒
超时硬约束（无降级）	超时直接返回 504，不返回降级答案
Fast 极简路径	单轮原查询、最多读取 3 页、关闭重排/KG/补搜以压缩时延
引用可信度标注	基于域名预设权重为每条引用打分
Redis 查询缓存	相同 query/top_k 命中缓存直接返回
知识图谱三元组提取	从搜索结果提取实体-关系-实体，返回结构化知识
个性化历史记忆	缓存用户过往查询，注入到 LLM 上下文增强个性化
审计日志完整记录	每次请求完整记录投入、输出、耗时、模型决策

目录结构

ai_search_agent/
├── agent.py                 # 核心编排层
├── api.py                   # FastAPI：同步搜索+流式SSE
├── audit.py                 # 审计日志
├── cache.py                 # Redis：查询缓存+历史记忆
├── config.py                # 配置管理
├── jina.py                  # Jina Reader 并发读取
├── knowledge_graph.py       # 知识图谱三元组提取
├── llm_client.py            # LLM 调用+Token流式
├── models.py                # 数据模型
├── parsers.py               # 解析工具+域名信任度
├── planner.py               # LLM 驱动的多轮规划
├── prompts.py               # 系统提示
├── reranker.py              # Jina Reranker 重排
├── search_client.py         # Jina Search 客户端
├── __init__.py
├── tests/
│   └── test_parsers.py
├── main.py                  # CLI 入口
├── serve.py                 # FastAPI 启动
├── function_app.py          # Azure Functions 入口
├── host.json                # Azure Functions 配置
├── local.settings.json.example
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

快速开始

安装

git clone http://gitee.ath.cx:3000/xiaohei/aisou.git && cd aisou
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

配置环境变量

复制 .env.example 为 .env，填入必选密钥：

JINA_API_KEY=your-jina-key
LLM_API_KEY=your-llm-key
REDIS_HOST=your-redis.cache.windows.net  # 可选
REDIS_KEY=your-redis-password            # 可选

CLI 方式运行

# 基础查询
python main.py "Jina AI 是什么"

# JSON 输出
python main.py "Jina AI 是什么" --json

# 自定义参数
python main.py "Jina AI 是什么" --top-k-pages 3

启动 FastAPI 服务

uvicorn serve:app --host 0.0.0.0 --port 8080 --reload

---

API 文档

端点总览

方法	路径	说明
GET	/health	健康检查（本地 FastAPI）
POST	/search/stream	统一流式搜索入口（SSE）

线上已迁移到 Azure Web App：https://aisousuogongdan-gehqaceacuf2cade.eastasia-01.azurewebsites.net
快速与深度通过请求参数 search_mode 区分，不再通过不同 URL 区分。

1. 健康检查

curl https://aisousuogongdan-gehqaceacuf2cade.eastasia-01.azurewebsites.net/health
# {"status": "ok"}

2. 统一流式搜索

curl -N -X POST https://aisousuogongdan-gehqaceacuf2cade.eastasia-01.azurewebsites.net/search/stream \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PydanticAI 适合哪些场景？",
    "top_k_pages": 3,
    "search_mode": "fast"
  }'

search_mode 说明：

• fast：通常 40~60 秒返回，超时事件为 timeout（error=TIMEOUT_FAST_SEARCH）
• deep：通常 110~300 秒返回，超时事件为 timeout（error=TIMEOUT_DEEP_SEARCH）
• fast：无 COT 过程事件，只输出必要流式事件（如 connected、llm_token、result、timeout、audit）
• deep：输出完整 COT 过程事件
• fast 继续使用极简路径：跳过 decompose/expand，固定单轮搜索，Reader 最多读取 3 页，并关闭 reranker/KG/confidence retry

Jina 搜索结果固定上限：

• 每次搜索查询最多保留 10 条结果用于后续处理

事件类型（含前端 COT 过程事件）： connected, mode_budget, progress, query_plan, cache_hit, decomposed, expanded, round_started, search_hits, page_fetch_status, reasoning_note, round_finished, llm_started, llm_token, final_meta, result, timeout, audit

当请求超时时，SSE 会发送 timeout 事件并结束流。 POST /search 已下线，调用会返回 410，请统一改为 /search/stream。

---

环境变量配置

必选

JINA_API_KEY=              # Jina API 密钥
LLM_API_KEY=               # LLM API 密钥

搜索参数（有默认值）

LLM_API_STYLE=openai_chat  # 或 xai_responses
LLM_ENDPOINT=...           # LLM API 端点
MODEL_NAME=qwen3.5-flash   # 模型名称
SEARCH_PROVIDER=jina_search
JINA_SEARCH_URL=https://s.jina.ai/
TOP_K_PAGES=5              # 返回前 K 个页面
MAX_PAGE_CHARS=5000        # 单页最大字符数
MAX_CONCURRENCY=5          # 并发数
MAX_SEARCH_ROUNDS=2        # 最大搜索轮数
SEARCH_TIMEOUT=20          # 搜索超时（秒）
READER_TIMEOUT=25          # Reader 超时（秒）
MODEL_TIMEOUT=90           # 模型超时（秒）
RETRY_ATTEMPTS=2           # 重试次数

Redis 与缓存（可选）

REDIS_HOST=testagnet.redis.cache.windows.net
REDIS_KEY=your-redis-password
CACHE_TTL=3600             # 缓存有效期（秒）
ENABLE_CACHE=true          # 启用查询缓存
ENABLE_MEMORY=true         # 启用历史记忆

高级功能（可选）

CONFIDENCE_THRESHOLD=0.6   # 置信度阈值，低于此值自动补搜
ENABLE_RERANKER=true       # 启用 Jina Reranker
ENABLE_KG=true             # 启用知识图谱提取
AUDIT_LOG_PATH=logs/audit.jsonl

---

Azure Web App 部署

部署命令

# 1. 获取 Redis 密钥
REDIS_KEY=$(az redis list-keys -g taiji-ai-test -n testagnet --query primaryKey -o tsv)

# 2. 配置应用设置
az webapp config appsettings set -g gongdan -n aisousuogongdan --settings \
  JINA_API_KEY="your-key" \
  LLM_API_KEY="your-key" \
  REDIS_HOST="testagnet.redis.cache.windows.net" \
  REDIS_KEY="$REDIS_KEY" \
  ENABLE_CACHE="true" \
  ENABLE_MEMORY="true" \
  ENABLE_RERANKER="true" \
  ENABLE_KG="true"

# 3. 发布（zip 部署示例）
az webapp deploy --resource-group gongdan --name aisousuogongdan --src-path /tmp/aisou-webapp.zip --type zip --restart true

# 4. 验证
curl https://aisousuogongdan-gehqaceacuf2cade.eastasia-01.azurewebsites.net/health

设计架构

数据流

Query → [Cache] → Decompose → Expand → Loop(Search|Read|Rerank) → 
  Confidence → KG → Answer → Citations → Cache+History → Response

核心模块

• agent.py - 编排全流程
• planner.py - LLM 驱动规划
• reranker.py - 语义重排
• cache.py - Redis 存储
• llm_client.py - 流式 LLM 调用
• knowledge_graph.py - 三元组提取
• audit.py - 完整审计日志

---

性能参考

指标	数值
单轮搜索	15-25 秒
缓存命中	<100 ms
多轮搜索（2 轮）	40-70 秒
Token 流式延迟	平均 50-100 ms/token

---

License

MIT