# 委内瑞拉专题知识库 API

该 API 基于委内瑞拉专题资料切片向量化数据，提供相似片段检索和 RAG 问答能力。当前包含《对外投资合作国别（地区）指南：委内瑞拉（2024年版）》及“委内瑞拉风俗文化及外交礼仪”资料。

## 接口地址

```text
POST https://resqai.org/api/venezuela_knowledge.php
Content-Type: application/json
```

## 1. 相似片段检索

### 请求

```json
{
  "action": "search",
  "text": "委内瑞拉外汇管理有哪些风险？",
  "limit": 5,
  "min_similarity": 0.2,
  "include_text": true
}
```

### 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| action | string | 否 | `search` 或 `ask`，默认 `search` |
| text/query/question | string | 是 | 查询文本，最长按 4000 字截断 |
| limit | int | 否 | 返回数量，1-30，默认 10 |
| min_similarity | number | 否 | 最低相似度，默认 0.2 |
| include_text | bool | 否 | 是否返回完整切片正文，默认 true |
| doc_key | string | 否 | 文档筛选，默认 `all`。可选 `venezuela_country_guide_2024`、`venezuela_diplomatic_etiquette_2026` |

### 响应

```json
{
  "success": true,
  "data": {
    "action": "search",
    "query": "委内瑞拉外汇管理有哪些风险？",
    "total": 5,
    "model": "embedding-2",
    "items": [
      {
        "id": 12,
        "chunk_index": 12,
        "section_path": "委内瑞拉 > 4. 投资环境 > 4.2 金融环境",
        "heading": "4.2.2 外汇管理",
        "similarity": 0.681234,
        "similarity_percent": 68.12,
        "text_excerpt": "...",
        "text": "..."
      }
    ],
    "served_at": "2026-06-25T00:00:00+00:00"
  }
}
```

## 2. RAG 问答

### 请求

```json
{
  "action": "ask",
  "question": "地震后中资企业在委内瑞拉应关注哪些合规和安全风险？",
  "limit": 5,
  "min_similarity": 0.18,
  "include_text": false
}
```

### 响应

```json
{
  "success": true,
  "data": {
    "action": "ask",
    "query": "地震后中资企业在委内瑞拉应关注哪些合规和安全风险？",
    "answer": "...",
    "references": [
      {
        "chunk_index": 120,
        "section_path": "...",
        "heading": "...",
        "similarity_percent": 64.23,
        "text_excerpt": "..."
      }
    ],
    "model": {
      "embedding": "embedding-2",
      "chat": "deepseek-chat"
    },
    "served_at": "2026-06-25T00:00:00+00:00"
  }
}
```

## 错误响应

```json
{
  "success": false,
  "error": "text不能为空"
}
```

## 调用示例

```bash
curl -X POST 'https://resqai.org/api/venezuela_knowledge.php' \
  -H 'Content-Type: application/json' \
  -d '{"action":"search","text":"委内瑞拉社会治安风险","limit":3,"include_text":false}'
```

## 前端页面

```text
https://resqai.org/venezuela-rag/
```