# Threads 語意搜尋 API

`GET /post/semantic-search` 用「意思」找串文，不是比對字面關鍵字。把想找的主題用一句話描述出來，API 會回傳最近 30 天內語意最接近的串文。

## 什麼時候用語意搜尋、什麼時候用關鍵字搜尋

假設你要找「上班族抱怨老闆、想離職」的串文。用 `/post/search` 你得自己列出關鍵字：離職、辭職、慣老闆、遣散……永遠列不完，而且很多串文根本沒用到這些詞。語意搜尋只要一句：

> 上班族被老闆氣到想離職

結果會同時包含寫「提離職」、「辭職」、「被通知遣散」的串文，甚至完全沒提這些詞、只是在抱怨主管的串文。

反過來說，如果你要找的是**明確的詞**，例如品牌名、帳號、活動 hashtag、產品型號，請用 `/post/search`。語意搜尋對一兩個字的關鍵字表現很差（見下方的分數說明）。

| 情境 | 建議 |
| --- | --- |
| 知道主題，但列不出完整的關鍵字 | 語意搜尋 |
| 想找某種情境或心情的串文 | 語意搜尋 |
| 監測品牌名、帳號、特定詞彙 | `/post/search` |
| 需要 30 天以前的資料 | `/post/search` |
| 需要包含回覆 | `/post/search` |

## 快速開始

```bash
curl -G 'https://premium-api.throk.ai/post/semantic-search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'query=新手第一次去健身房不知道要練什麼' \
  --data-urlencode 'size=10'
```

回應（節錄）：

```json
{
  "results": [
    {
      "post": {
        "url": "https://threads.com/post/DaXXXXXX",
        "caption": "健身新手要怎麼練 怎麼吃 那麼多器械要怎麼選 求大佬指教",
        "like_count": 12,
        "reply_count": 3,
        "post_timestamp": 1784402170
      },
      "user": { "username": "...", "full_name": "..." },
      "score": 0.990
    }
  ],
  "credits_consumed": 30
}
```

結果依相關度排序，每筆都帶完整的串文與作者資料。

## 分數怎麼看

每筆結果的 `score` 是查詢與串文的語意相似度，範圍 0–1：

- **0.98 以上**：強相關，可以直接使用
- **0.95–0.98**：大致相關，可能混入「主題像但主體不對」的結果（例如查小孩睡不著，混進毛小孩睡不著）
- **0.95 以下**：當成雜訊

意思不完整的破碎關鍵字（例如只寫「蛋白」）最高分只會落在 0.92–0.94，而且同一個分數帶裡不相關的串文分數一樣高，無法過濾。「台南美食」這種本身就是完整主題的詞則沒問題，可以拿到 0.98 以上。

:::tip
如果回傳的最高分低於 0.96，代表這個查詢不適合語意搜尋，改用 `/post/search` 關鍵字比對會更準確。
:::

## 查詢怎麼寫

以「台南美食」實測，三種寫法的結果傾向不同：

- **同主題關鍵字組**：`台南美食 台南小吃 台南餐廳推薦`。多個同主題的詞會讓主題更集中，是最穩定的寫法，兩三個就夠。注意只能是**同一個**主題，不相關的主題請分開查詢。
- **完整句子**：`去台南玩有什麼在地美食推薦`。結果會貼近句子的情境。這句是問句，回來的多半也是發問求推薦的串文；想找食記，請用陳述句描述內容。
- **單一主題詞**：`台南美食`。可以用，但容易混入很短的串文與鄰近城市的結果。

想要高互動的串文，搭配 `min_like_count` 即可，不需要改寫查詢。

## 參數

| 參數 | 說明 | 預設 |
| --- | --- | --- |
| `query` | 用一句話描述要找什麼，2–200 字 | 必填 |
| `size` | 回傳筆數，10–3000 | 10 |
| `language` | 市場，見[地區與語言](/api/guides/regions/) | `zh` |
| `exclude_hk` | 排除粵語與港式中文串文，僅 `language=zh` 適用 | `false` |
| `from_timestamp` | 起始時間（UNIX 秒），最多回溯 30 天 | 30 天前 |
| `to_timestamp` | 結束時間（UNIX 秒） | 現在 |
| `min_like_count` | 只保留讚數達標的串文 | 不篩選 |
| `min_reply_count` | 只保留回覆數達標的串文 | 不篩選 |

`min_like_count` 與 `min_reply_count` 是在語意排名最前面的候選串文中篩選，所以設了門檻後，回傳筆數可能少於 `size`。門檻設太高（例如 1000 讚）時，冷門主題可能一筆都不剩。

範例：找最近一週、至少 100 讚的減脂話題串文：

```bash
curl -G 'https://premium-api.throk.ai/post/semantic-search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'query=減脂期到底可以吃什麼' \
  --data-urlencode "from_timestamp=$(date -v-7d +%s)" \
  --data-urlencode 'min_like_count=100'
```

## 計費

前 10 筆共 30 積分，之後每筆加 2 積分（例如回傳 30 筆為 70 積分）。超過 10 筆的部分依實際回傳筆數計費，但每次呼叫最低收 30 積分，即使篩選後結果不足 10 筆、甚至 0 筆。

## 在 MCP 中使用

MCP 工具名稱是 `semantic_search_posts`，參數相同，但 `size` 上限為 10。

它和 `get_inspiration` 的差別：`get_inspiration` 只搜高互動的精選串文；`semantic_search_posts` 搜所有近期串文，一般小帳號的串文也找得到。

## 限制

- **只搜最近 30 天。** 更早的串文請用 `/post/search`。
- **只搜主串文，不含回覆**，也不包含太短的串文。
- **無法保證結果包含特定字詞。** 需要精確比對時請用 `/post/search`。
- **地名限定的查詢**（例如「台北美食」）容易混入其他城市的結果，這是目前語意模型的已知弱點。