AI Search Agent v2.0

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

核心能力清单

能力	说明
LLM 驱动多轮规划	模型自主分解查询、规划下一轮搜索
多语言扩展	CJK 自动翻译为英文，双语并行检索
Jina Reranker 语义重排	按查询相关性重排页面顺序
置信度自评 + 自动补搜	LLM 返回置信度，不足时自动触发补搜
追问建议（Follow-up）	生成 3 条推荐的后续问题
Token 级流式输出	LLM 回答逐字流式返回，非事件粒度
双模式搜索预算	fast 30 秒预算，deep 120 秒预算
超时硬约束（无降级）	超时直接返回 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	同步搜索（阻塞式，本地 FastAPI）
POST	/search/stream	流式搜索（SSE 事件，仅常驻 FastAPI 服务）

Azure Functions 部署时由 function_app.py 挂载到 /api 前缀，仅提供 /api/health、/api/search。
/search/stream 必须走常驻 uvicorn 服务（避免 Functions 网关缓冲导致假流式）。

1. 健康检查

curl https://aisousuo.azurewebsites.net/api/health
# {"status": "ok"}

2. 同步搜索

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

search_mode 说明：

• fast：30 秒时间预算，超时返回 504
• deep：120 秒时间预算，超时返回 504
• 两种模式均不做降级回答
• fast 使用极简路径：跳过 decompose/expand，固定单轮搜索，Reader 最多读取 3 页，并关闭 reranker/KG/confidence retry

Jina 搜索结果固定上限：

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

响应包含：

• answer.confidence - 置信度评分
• answer.follow_up_questions - 3 条推荐追问
• answer.citations[].trust_score - 引用可信度
• search_rounds - 多轮搜索轨迹
• knowledge_triples - 抽取的知识三元组
• cache_hit - 是否缓存命中
• audit_id - 审计追踪 ID

3. SSE 流式搜索（常驻 FastAPI）

curl -N -X POST https://your-stream-service/search/stream \
  -H "Content-Type: application/json" \
  -d '{"query":"PydanticAI 适合哪些场景?","search_mode":"deep"}'

事件类型（含前端 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 事件并结束流。

如果你误调 Azure Functions 的 /api/search/stream，会返回 501，并提示使用独立流式服务地址。

---

环境变量配置

必选

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 Functions 部署

部署命令

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

# 2. 配置应用设置
az functionapp config appsettings set -g gongdan -n aisousuo --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. 发布
func azure functionapp publish aisousuo --python

# 4. 验证
curl https://aisousuo.azurewebsites.net/api/health

流式服务部署（推荐 App Service / Container）

# 启动常驻服务（示例）
uvicorn serve:app --host 0.0.0.0 --port 8080

• 将前端流式请求改为 https://<stream-service>/search/stream
• Azure Functions 继续承载同步接口：/api/search
• 可在 Functions 环境变量中配置 STREAM_SERVICE_BASE_URL=https://<stream-service>，用于错误提示回传目标流式地址

---

设计架构

数据流

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