# 知识库agent

**Repository Path**: bingbingyihao/knowledge-base-agent

## Basic Information

- **Project Name**: 知识库agent
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# knowledge-base-agent

知识库 RAG 检索 Agent：接收提问 → 由大模型自主决定检索关键词与检索轮次 → 通过 MCP 检索知识库 → 返回简练结论。

## 特性

- **模型自主决策**：搜几轮、每轮搜什么词全部由大模型决定，代码只做轮次上限、去重、超时兜底
- **只查知识库**：不向模型注册任何联网工具，提示词明确禁止使用网络资料，仅允许自身知识 + 知识库检索结果
- **结论简练**：默认上限 800 字，过短会自动要求模型补全一次
- **过程可追溯**：每轮检索词、检索结果、模型动作与 token 消耗全程落日志，带 `requestId` 串联
- **工具自动适配**：自动识别检索工具名并推断查询词/条数参数，兼容不同知识库 MCP 的命名差异
- **无数据库依赖**：仅 Web / Validation / Actuator / Spring AI MCP Client

## 处理流程

```
POST /api/agent/ask
      │
      ▼
 第 N 轮：问题 + 已检索片段 → 大模型 → {"action":"SEARCH"|"FINAL", ...}
      │                                    │
   SEARCH                              FINAL
      │                                    │
 调用知识库 MCP 检索                    输出简练结论
      └──► 片段回灌，进入第 N+1 轮（直到模型给结论或达轮次上限）
```

## 快速开始

环境：JDK 17+、Maven 3.8+。

```bash
mvn clean package
java -jar target/rag-agent.jar
```

改 `src/main/resources/application.yml`：

```yaml
spring:
  ai:
    mcp:
      client:
        streamable-http:
          connections:
            knowledge-base:
              url: <知识库 MCP 地址>
              endpoint: /mcp          # Streamable HTTP 端点

rag-agent:
  llm:
    api-key: ${DASHSCOPE_API_KEY:}    # 通义千问 API Key，建议走环境变量
    model: qwen3.8-flash
  mcp:
    headers:                          # 附加到每个 MCP 请求的请求头
      X-Dataset-Ids: <数据集 ID>
    search-tool-name: ragflow_search  # 留空则自动识别
    top-k: 5                          # 单次检索返回片段数
```

Key 用环境变量注入，避免进仓库：

```bash
export DASHSCOPE_API_KEY=sk-xxxxxxxx     # Linux / macOS
$env:DASHSCOPE_API_KEY="sk-xxxxxxxx"     # Windows PowerShell
```

启动时预热会真实调用一次 `tools/list`，日志中可确认地址、请求头与工具名是否正确：

```
知识库 MCP 请求头已配置：[X-Dataset-Ids]
知识库 MCP 可用工具共 1 个：[ragflow_search]
知识库 RAG 检索工具已就绪：ragflow_search
```

## 接口

`POST /api/agent/ask`

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `question` | 是 | 提问，最长 2000 字 |
| `maxRounds` | 否 | 本次最多检索轮次，1~10 |
| `topK` | 否 | 单次检索返回条数，1~50 |
| `includeTrace` | 否 | 是否返回检索过程，默认 `false` |

```bash
curl -X POST http://127.0.0.1:8080/api/agent/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"承运人擅自降低服务标准怎么处理？","includeTrace":true}'
```

```json
{
  "requestId": "abc123",
  "answer": "承运人擅自降低服务标准的，应当根据旅客的请求退票或者减收票款。",
  "roundsUsed": 1,
  "totalQueries": 1,
  "durationMillis": 574,
  "model": "qwen3.8-flash",
  "degraded": false,
  "trace": [
    {
      "round": 1,
      "action": "SEARCH",
      "queries": ["承运人擅自降低服务标准"],
      "results": [{ "query": "…", "success": true, "resultLength": 733, "costMillis": 509 }],
      "llmCostMillis": 58,
      "searchCostMillis": 509
    }
  ]
}
```

错误码：`INVALID_REQUEST`(400)、`LLM_ERROR`(502)、`MCP_ERROR`(502)、`INTERNAL_ERROR`(500)。响应头 `X-Request-Id` 可用于检索完整日志。健康检查 `GET /actuator/health`。

## 日志

控制台 + `logs/rag-agent.log`（按天/50MB 滚动，保留 15 天）。

```
[abc123] 用户提问：承运人擅自降低服务标准怎么处理？
[abc123] >>> 第 1 轮模型决策：action=SEARCH, queries=[承运人擅自降低服务标准], reason=需要查询知识库
[abc123] MCP 检索调用：tool=ragflow_search, arguments={question=承运人擅自降低服务标准, size=5}
[abc123] 第 1 轮检索结果：query='…' -> 733 字符，耗时 509ms
[abc123] >>> 第 2 轮模型决策：action=FINAL, answer=…, reason=片段已覆盖
[abc123] Agent 处理结束：检索轮次=1, 检索词总数=1, 总耗时=574ms, 是否降级=false
```

`MCP 检索调用：tool=..., arguments={...}` 打印实际传参，是排查「条数没生效 / 检索词传错字段」最直接的一行。

## 配置说明

| 配置项 | 默认 | 说明 |
| --- | --- | --- |
| `rag-agent.agent.max-rounds` | 5 | 检索轮次硬上限，模型在此范围内自主决定 |
| `rag-agent.agent.max-queries-per-round` | 3 | 单轮最多检索词数 |
| `rag-agent.agent.max-answer-chars` | 800 | 结论字数上限 |
| `rag-agent.agent.total-timeout` | 180s | 单次提问总超时 |
| `rag-agent.mcp.top-k` | 5 | 单次检索返回片段数 |
| `rag-agent.mcp.headers` | - | MCP 请求头（如数据集范围） |

连接地址与超时统一在 `spring.ai.mcp.client.*` 配置，`rag-agent.mcp` 只保留检索语义相关项。

> **条数参数优先级**：部分知识库同时提供 `size`（返回片段数）与 `top_k`（候选池大小）等语义相近的参数，
> 默认候选顺序以 `size` 优先。若换用其他知识库，可按需调整 `top-k-parameter-candidates` 顺序。

## 工程结构

```
src/main/java/com/example/ragagent/
├── agent/      Agent 编排：主流程、提示词、决策解析、过程记录
├── llm/        大模型客户端（OpenAI 兼容 /chat/completions）
├── mcp/        知识库检索：工具识别、参数推断、请求头注入、启动预热
├── config/     全部可配置项
├── common/     异常与文本工具
└── web/        REST 接口、统一异常、请求追踪
```

## 构建

```bash
mvn clean package        # 测试 + 格式校验 + 打包可执行 jar
mvn spotless:apply       # 一键格式化（palantir-java-format，已绑定 validate 阶段）
mvn -DskipTests package  # 跳过测试
```

分层打包已开启（`layers.enabled=true`），便于容器化复用依赖层。

Postman 集合见 `postman/knowledge-base-agent.postman_collection.json`。