shouhou-kb
by oTAKUBANG1
README.md
# shouhou-kb
家庭宽带 / 路由器 **售后知识库**:BM25 检索 + 回答生成 + MCP 服务。
装完就能用:**检索不需要任何 API key**,只有“让模型生成回答”需要 `DEEPSEEK_API_KEY`。
```bash
pip install .
shouhou-mcp # MCP 服务(stdio)
shouhou-web # 网页问答
```
## 用 MCP(给任意 agent 用)
```json
{
"mcpServers": {
"shouhou-kb": {
"command": "shouhou-mcp",
"env": { "DEEPSEEK_API_KEY": "sk-你的key" }
}
}
}
```
三个工具:
| 工具 | 作用 | 需要 key |
|---|---|---|
| `search_kb(query, top_k)` | 检索知识库切片,返回文件/标题/相关度 | ❌ |
| `get_article(file)` | 取一篇全文(`01` 或 `01-光猫与宽带接入.md`) | ❌ |
| `answer_question(question, strict)` | 检索 + 生成,带来源 | ✅ |
`strict=True` 时只依据知识库回答,资料没覆盖就明确说“知识库未覆盖”,不拿通用知识编。
## 用网页
```bash
shouhou-web # http://127.0.0.1:8899
shouhou-web --port 9000
```
接口:
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/search` | `{"query": "...", "top_k": 3}` |
| POST | `/api/ask` | `{"question": "...", "strict": false}` |
## 用 Python
```python
from shouhou_kb import retrieve, answer
hits = retrieve("5G 信号只有一格", top_k=3) # 不需要 key
out = answer("5G 信号只有一格", strict=True) # 需要 key
print(out["answer"], out["citations"])
```
## 知识库内容
8 篇 / 70 个切片:
| 篇 | 主题 |
|---|---|
| 01 | 光猫与宽带接入(指示灯、光衰、桥接) |
| 02 | 拨号错误码与上网方式(691 / 678 / 651 / PPPoE) |
| 03 | WiFi 频段与干扰(2.4G/5G、信道、DFS、双频合一) |
| 04 | 路由器后台与常用设置(登录、改密码、端口映射、安全加固) |
| 05 | 组网与漫游(Mesh、AC+AP、有线回程、伪漫游) |
| 06 | 网速诊断与测速(百兆/千兆瓶颈、测速达标率) |
| 07 | 选购与硬件接口(2.5G 网口、六类线、光猫选型) |
| 08 | 故障速查表(按现象 / 按设备两套索引) |
## 循环检测(内置)
| 层 | 触发 | 处理 |
|---|---|---|
| 输出循环 | 同一句重复 ≥3 次或 8 字片段重复率 ≥0.32 | 换说法重试一次,仍重复则去重截断 |
| 工具循环 | 同参数连续调同一工具 3 次 | 返回上次结果并提示换关键词 |
| 会话循环 | 同一问题问第 2 次 | 复用上次答案,标记 `guard.same_question` |
阈值可用环境变量调:`SHOUHOU_MAX_TOOL_REPEAT` / `SHOUHOU_MAX_SAME_QUESTION` / `SHOUHOU_OUTPUT_LOOP_RATIO`。
## 为什么默认 BM25,不用向量
同一套 50 题、同一个知识库、同一判定口径下的配对实验:
| | BM25 | 向量混合 |
|---|---|---|
| 平均要点分 | **0.656** | 0.630 |
| 配对差 95% CI | — | [−0.068, +0.016](跨 0) |
没有可测差异,而向量需要云端 embedding 服务——多一个外部依赖、多一个失效点。
所以默认 BM25(`shouhou_kb/retrieval.py` 里是自包含实现,零依赖)。
要换成向量检索,替换 `KB.search()` 即可,接口不变。
## 测试
```bash
python -m pytest tests -q # 7 个用例
```
## 许可
MIT。知识库为整理的通用售后经验,不含厂商机密;具体产品参数请以官方文档为准。
回答由模型生成,仅供参考。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data