# 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 上下文增强个性化 |
| **审计日志完整记录** | 每次请求完整记录投入、输出、耗时、模型决策 |

## 目录结构

```text
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
```

## 快速开始

### 安装

```bash
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`，填入必选密钥：

```bash
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 方式运行

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

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

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

### 启动 FastAPI 服务

```bash
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. 健康检查

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

### 2. 统一流式搜索

```bash
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`。

---

## 环境变量配置

### 必选

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

### 搜索参数（有默认值）

```bash
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 与缓存（可选）

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

### 高级功能（可选）

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

---

## Azure Web App 部署

### 部署命令

```bash
# 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