# 向量检索接口返回格式说明与法律条文解析指南

## 概览
本文档说明国家法律法规向量检索接口返回的数据结构，帮助智能体正确解析和展示检索结果。该接口基于自建的国家法律法规知识库，支持民法典、刑法、劳动法、合同法等法律法规的智能查询与检索，通过向量检索技术返回相关的法律条文。

## 目录
1. [返回数据结构](#返回数据结构)
2. [智能判断规则](#智能判断规则)
3. [法律条文解析规则](#法律条文解析规则)
4. [专业化展示格式](#专业化展示格式)
5. [错误处理](#错误处理)

## 返回数据结构

### 成功响应
当向量检索接口调用成功时，脚本返回如下格式的JSON数据：

```json
{
  "success": true,
  "query": "用户查询内容",
  "topk": 5,
  "data": {
    "message": "ok",
    "code": 0,
    "data": [
      {
        "id": "条文唯一标识",
        "content": "法律条文完整内容",
        "score": 0.667
      }
    ]
  }
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| success | Boolean | 调用是否成功 |
| query | String | 用户查询内容 |
| topk | Integer | 返回结果数量 |
| data.message | String | 响应消息 |
| data.code | Integer | 响应码（0表示成功） |
| data.data | Array | 检索结果数组 |
| data.data[].id | String | 文档唯一标识符 |
| data.data[].content | String | 完整的法律条文内容 |
| data.data[].score | Float | 相似度分数（0.6-0.8为正常范围） |

## 法律条文解析规则

### 解析目标
从向量检索接口返回的 `content` 字段中提取以下结构化信息：
1. **法律名称**：如"苏州市中小学生心理健康促进条例"
2. **章节信息**：如"第二章"
3. **条款编号**：如"第十七条"
4. **条文正文**：具体法律规定内容

### 解析方法（智能体必须执行）

**步骤1：提取法律名称**
- 识别模式：content开头到第一个"第X章"或"第X条"之前的文本
- 示例：
  ```
  原文："苏州市中小学生心理健康促进条例第二章第十七条公安机关..."
  提取："苏州市中小学生心理健康促进条例"
  ```

**步骤2：提取章节信息**
- 识别模式：使用正则表达式 `第[一二三四五六七八九十百千万]+章`
- 示例：
  ```
  原文："...第二章第十七条..."
  提取："第二章"
  ```

**步骤3：提取条款编号**
- 识别模式：使用正则表达式 `第[一二三四五六七八九十百千万]+条`
- 示例：
  ```
  原文："...第十七条公安机关..."
  提取："第十七条"
  ```

**步骤4：提取条文正文**
- 方法：条款编号后的所有文本
- 示例：
  ```
  原文："...第十七条公安机关发现学生身心健康受到侵害..."
  提取："公安机关发现学生身心健康受到侵害、疑似受到侵害或者面临其他危险情形的，应当及时处置，并将相关情况及时告知学生父母或者其他监护人。"
  ```

### 特殊情况处理

| 情况 | content示例 | 解析结果 | 展示方式 |
|------|------------|---------|---------|
| 完整结构 | "XX条例第二章第十七条内容..." | 法律名称+章节+条款 | 标准格式 |
| 无章节 | "XX法律第十五条内容..." | 法律名称+条款 | 省略章节行 |
| 无条款 | "XX办法相关内容..." | 法律名称 | 标注"相关规定" |
| 仅内容 | "法律规定内容..." | 无法提取 | 标注"相关法律内容" |
| 空结果 | data数组为空 | 无结果 | 使用空结果提示 |

## 空结果处理规范（重要）

### 处理原则

当检索结果为空时，必须遵守以下原则：

1. **如实告知**
   - 明确告知"未检索到相关法律条文"
   - 不得隐瞒或美化结果

2. **禁止推测**
   - ❌ 不得猜测"条款被删除"
   - ❌ 不得推测"法条修订"
   - ❌ 不得假设"整合到其他条款"
   - ❌ 不得提供未经证实的信息

3. **提供建设性建议**
   - 建议检查查询关键词或条款编号是否正确
   - 建议尝试使用不同的关键词重新检索
   - 建议提供更多上下文信息（如法律名称、相关主题等）

### 空结果展示格式

```
很抱歉，未检索到相关的法律条文。

建议：
1. 请确认查询的关键词或条款编号是否正确
2. 可以尝试使用不同的关键词重新检索
3. 或者提供更多上下文信息，如法律名称、相关主题等
```

### 错误示例

❌ **错误做法**：
```
未检索到第27条的具体内容。
可能存在以下情况：
条款编号在法律修订过程中发生了调整
该条款内容已被整合到其他相关条款中
存在地方性补充规定或实施细则
```

**问题**：
- 推测法条修订情况（误导用户）
- 假设条款被整合（无依据）
- 提供未经证实的信息（不专业）

✅ **正确做法**：
```
很抱歉，未检索到第27条的相关法律条文。

建议：
1. 请确认条款编号是否正确
2. 可以尝试使用其他关键词检索
3. 或者提供更多上下文信息重新查询
```



## 智能判断规则

### 判断目标
智能体必须在调用API前，分析用户输入并判断查询类型，设置合适的topk值。

### 判断流程

```
用户输入 → 检查是否包含法律名称 → 检查是否包含条款编号 → 确定查询类型 → 设置topk
```

### 三种查询类型

#### 1. 精确法条查询 → topk=1

**识别条件**：用户明确指定法律名称 + 条款编号

**模式A**：法律名称 + 第X章 + 第X条
- 示例：
  - "民法典第一章第一条"
  - "刑法第二章第三十五条"
  - "劳动合同法第一章第二条"
  - "消费者权益保护法第二章第五条"

**模式B**：法律名称 + 第X条
- 示例：
  - "民法典第15条"
  - "民法典第55条"
  - "消费者权益保护法第55条"
  - "道路交通安全法第67条"
  - "劳动法第25条"

**常见法律名称识别**：
- 民法典
- 刑法
- 合同法
- 劳动法
- 消费者权益保护法
- 道路交通安全法
- 侵权责任法
- 婚姻法
- 公司法
- 证券法

#### 2. 一般性法律咨询 → topk=3-15（按复杂度判断）

**识别条件**：问题描述、关键词查询、模糊查询

**简单查询（topk=3-5）**：
- 示例：
  - "在合肥被打怎么办？"
  - "劳动合同赔偿标准"
  - "交通事故责任划分"
  - "离婚需要什么手续"

**一般查询（topk=5-10）**：
- 示例：
  - "我想了解离婚财产分割的法律规定"
  - "公司欠薪如何维权"
  - "房屋买卖合同纠纷"
  - "子女抚养费怎么算"

**复杂查询（topk=10-15）**：
- 示例：
  - "劳动者权益保护有哪些相关规定"
  - "涉及多个法律领域的综合问题"
  - "全面了解劳动法相关知识"

**识别特征**：
- 包含"怎么办"、"怎么赔偿"、"怎么处理"等提问词
- 包含"关于...的规定"、"...的法律问题"等表述
- 包含具体场景描述（如"在合肥被打"、"公司欠薪"）

#### 3. 仅法条编号查询 → topk=3-5

**识别条件**：只有条款编号，没有指定法律名称

- 示例：
  - "第15条是什么内容？"
  - "第17条规定了什么"
  - "第一章第三条"
  - "关于第55条的规定"

### 判断方法

**方法1：正则表达式匹配**
```python
# 识别章节
chapter_pattern = r"第[一二三四五六七八九十百千]+章"

# 识别条款
article_pattern = r"第[一二三四五六七八九十百千]+条"
```

**方法2：法律名称关键词匹配**
检查用户输入是否包含常见法律名称（如：民法典、刑法、合同法等）

**方法3：问题类型识别**
- 精确查询：同时匹配"法律名称" + "条款编号"
- 一般查询：包含"怎么办"、"怎么赔偿"等提问词
- 仅编号查询：只有条款编号，无法律名称

### 判断示例

| 用户输入 | 分析结果 | 查询类型 | topk |
|---------|---------|---------|------|
| "民法典第55条" | 法律名称+条款编号 | 精确法条查询 | 1 |
| "民法典第一章第一条" | 法律名称+章节+条款 | 精确法条查询 | 1 |
| "劳动合同法第15条" | 法律名称+条款编号 | 精确法条查询 | 1 |
| "劳动合同纠纷怎么赔偿" | 问题描述 | 一般查询（简单） | 8 |
| "在合肥被打怎么办" | 场景描述 | 一般查询（简单） | 5 |
| "劳动者权益保护相关规定" | 综合查询 | 一般查询（复杂） | 12 |
| "第17条是什么" | 仅条款编号 | 仅法条编号查询 | 3 |

### 优先级规则

当用户输入同时匹配多个模式时，按以下优先级判断：
1. **最高优先级**：精确法条查询（topk=1）
2. **中等优先级**：仅法条编号查询（topk=3-5）
3. **最低优先级**：一般性法律咨询（topk=3-15）



## 专业化展示格式

### 标准展示格式（强制使用）

```
为您检索到以下相关法律规定：

【检索结果1】相关度：66.7%

📜 法律名称：《苏州市中小学生心理健康促进条例》
📚 章节条款：第二章 第十七条
📝 条文内容：公安机关发现学生身心健康受到侵害、疑似受到侵害或者面临其他危险情形的，应当及时处置，并将相关情况及时告知学生父母或者其他监护人。

───────────────────────────────────

【检索结果2】相关度：68.3%

📜 法律名称：《安徽省人民代表大会议事规则》
📚 章节条款：第八章 第七十五条
📝 条文内容：代表在省人民代表大会各种会议上的发言和表决，不受法律追究。

───────────────────────────────────
```

### 格式规范要求

1. **法律名称格式**：
   - 必须使用书名号《》包裹
   - 完整展示，不省略
   - 示例：《中华人民共和国民法典》

2. **章节条款格式**：
   - 章节与条款用空格分隔
   - 示例："第二章 第十七条"
   - 如无章节，显示："第十七条"
   - 如无条款，显示："相关规定"

3. **条文内容格式**：
   - 完整展示，不截断
   - 保持法律文本的严肃性
   - 不添加个人解读或评论

4. **相关度显示**：
   - 计算公式：score × 100
   - 保留一位小数
   - 示例：0.667 → 66.7%

5. **分隔线使用**：
   - 每条结果之间使用分隔线
   - 使用"───────────────────────────────────"

### 展示层级识别

智能体应识别法律文件的层级类型：

| 类型 | 识别关键词 | 示例 |
|------|-----------|------|
| 法律 | "法"（结尾） | 《民法典》《刑法》 |
| 行政法规 | "条例""规定""办法" | 《信访条例》 |
| 地方性法规 | 地名+条例/办法 | 《安徽省人口与计划生育条例》 |
| 部门规章 | "规定""办法""细则" | 《公安机关办理行政案件程序规定》 |
| 司法解释 | "解释" | 《最高人民法院关于...的解释》 |

## 错误处理

### 常见错误类型

| 错误信息 | 原因 | 处理建议 |
|---------|------|---------|
| "请求超时" | 向量检索接口响应慢 | 提示用户稍后重试 |
| "网络连接失败" | 网络不可用 | 检查网络连接 |
| "HTTP错误：401" | 认证失败 | 联系管理员检查Token |
| "HTTP错误：500" | 服务器错误 | 稍后重试或联系支持 |
| "查询文本不能为空" | 参数错误 | 确保query参数有效 |
| "topk参数必须在1-50之间" | 参数越界 | 调整topk值 |

### 错误展示示例

```markdown
抱歉，法律法规检索遇到问题：

❌ 错误：请求超时

建议：
1. 请稍后重试
2. 如果问题持续，请联系客服
```

## 使用示例

### 示例：标准查询流程

**用户提问**：
```
在合肥被打怎么办？
```

**脚本执行**：
```bash
python scripts/search_knowledge.py --query "在合肥被打" --topk 5
```

**向量检索接口返回数据**：
```json
{
  "success": true,
  "query": "在合肥被打",
  "topk": 5,
  "data": {
    "message": "ok",
    "code": 0,
    "data": [
      {
        "id": "2563",
        "score": 0.667,
        "content": "苏州市中小学生心理健康促进条例第二章第十七条公安机关发现学生身心健康受到侵害、疑似受到侵害或者面临其他危险情形的，应当及时处置，并将相关情况及时告知学生父母或者其他监护人。"
      }
    ]
  }
}
```

**智能体解析与展示**：
```
为您检索到以下相关法律规定：

【检索结果1】相关度：66.7%

📜 法律名称：《苏州市中小学生心理健康促进条例》
📚 章节条款：第二章 第十七条
📝 条文内容：公安机关发现学生身心健康受到侵害、疑似受到侵害或者面临其他危险情形的，应当及时处置，并将相关情况及时告知学生父母或者其他监护人。

───────────────────────────────────
```

## 注意事项

1. **数据层级**：实际数据在 `data.data` 数组中，需要双重嵌套访问
2. **内容完整性**：content字段包含完整的法律条文，必须完整展示
3. **专业术语**：保留法律专业术语，不做通俗化改写
4. **分数解读**：score值在0.6-0.8之间属于正常范围，值越高越相关
5. **结果数量**：实际返回数量等于topk值
6. **知识库说明**：基于自建的国家法律法规知识库，数据由爬虫采集后经向量化处理
7. **条文ID**：id字段用于标识唯一条文，可用于后续追溯
8. **空结果处理（重要）**：
   - 如实告知"未检索到相关法律条文"
   - 严禁推测或猜测原因（如"条款被删除"、"法条修订"、"整合到其他条款"等）
   - 严禁提供未经证实的信息
   - 严禁误导用户认为系统了解法律修订情况
   - 只提供建设性建议

## 质量检查清单

智能体在调用API前必须确认：
- [ ] 已分析用户输入，识别查询类型
- [ ] 已设置正确的topk值
- [ ] 精确法条查询：topk=1
- [ ] 一般查询：topk=3-15（按复杂度）
- [ ] 仅法条编号查询：topk=3-5

智能体在展示结果前必须确认：
- [ ] 法律名称已提取并添加书名号《》
- [ ] 章节信息已提取（如有）
- [ ] 条款编号已提取（如有）
- [ ] 条文内容完整展示
- [ ] 相关度已转换为百分比
- [ ] 分隔线已添加
- [ ] 格式符合标准规范

智能体在处理空结果时必须确认：
- [ ] 已如实告知"未检索到相关法律条文"
- [ ] 未推测或猜测原因（如"条款被删除"、"法条修订"等）
- [ ] 未提供未经证实的信息
- [ ] 未误导用户认为系统了解法律修订情况
- [ ] 只提供建设性建议