candidate_search - DropCV

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

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

要按姓名 / 公司精确找人、或不带 query 翻页浏览人才库，请用 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`

返回

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

拿到 candidate_id 后，用 candidate_profile_read 读完整档案。

示例

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 匹配候选人：

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 权限。