> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dropcv.work/llms.txt
> Use this file to discover all available pages before exploring further.

# candidate_search

> 基于关键词或 JD 片段在人才库中检索候选人。

`candidate_search` 基于 **embedding 语义相似度**在人才库召回候选人 —— 把 query（关键词组、人选画像或整段 JD）向量化后做相似匹配。常用两种场景：

1. **画像搜**："Python 后端 5 年" / "互联网大厂技术总监"
2. **JD 匹配候选人**：直接把整段 JD 文本作为 query

要按姓名 / 公司**精确**找人、或不带 query 翻页浏览人才库，请用 [`candidate_list`](/integration/skills/candidate-list)（非语义、纯结构化查询）。

## 参数

| 字段               | 类型                    | 必填 | 说明                           |
| ---------------- | --------------------- | -- | ---------------------------- |
| `query`          | string (1-2000 字符)    | 是  | 关键词组或 JD 文本片段（语义匹配，非精确）      |
| `top_k`          | integer (1-50, 默认 10) | 否  | 返回数量上限                       |
| `current_city`   | string                | 否  | 在语义召回基础上按当前城市过滤（精确匹配）        |
| `min_years`      | integer (≥0)          | 否  | 最低总工作年限                      |
| `profile_status` | string                | 否  | 按档案状态过滤，如 `draft` / `active` |

## 返回

```json theme={null}
{
  "query": "...",
  "total": 42,
  "items": [
    {
      "candidate_id": "uuid",
      "full_name": "张三",
      "current_title": "高级后端工程师",
      "current_company": "字节跳动",
      "current_city": "北京",
      "similarity_score": 0.87
    }
  ]
}
```

拿到 `candidate_id` 后，用 [`candidate_profile_read`](/integration/skills/candidate-profile-read) 读完整档案。

## 示例

```bash theme={null}
curl -X POST https://api.dropcv.work/api/external/v1/skills/candidate_search/invoke \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"query": "Python 后端 5 年大厂", "top_k": 5}}'
```

## 常见用法

**JD 匹配候选人**：

```bash theme={null}
curl -X POST https://api.dropcv.work/api/external/v1/skills/candidate_search/invoke \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "query": "招聘高级后端工程师，要求 Python / Go 5 年以上经验，熟悉分布式系统...",
      "top_k": 20
    }
  }'
```

## 权限

不需要 write 权限。