vector search

[yutin1987]

---	Gemini Developer API	Vertex AI
認證	API key（GEMINI_API_KEY）	GCP 專案 + ADC / service account、IAM
端點	全域 generativelanguage.googleapis.com	綁專案 + 區域（location）
檔案	Files API（暫存 ~48h）、GCS gs://、HTTPS URL、inlineData	GCS gs://、inlineData
學習成本	低（貼 key 即用）	高（專案、IAM、憑證）

混合搜尋(kNN 檢索 + BM25 排序)使用說明

如何啟用

在 ListArticles / ListReplies 的 filter 加上 embedding 欄位：

• 不傳 embedding → 純 BM25（預設，完全向後相容）。
• 傳一個數字（最小 cosine 相似度，0~1）→ kNN 檢索 + BM25 排序。
  • 數字越大越嚴格；建議從 0.7 起調。

embedding 是一個 Float，直接給門檻值即可，不是物件。

範例

文字查詢

# 純 BM25（原本行為）
query {
  ListArticles(filter: { moreLikeThis: { like: "雞蛋 缺蛋 漲價" } }) {
    edges { node { id text } }
  }
}

# kNN 檢索 + BM25 排序，相似度門檻 0.7
query {
  ListArticles(filter: {
    moreLikeThis: { like: "雞蛋 缺蛋 漲價" }
    embedding: 0.7
  }) {
    edges { node { id text } }
  }
}

ListReplies 用法相同（文字查詢）：

query {
  ListReplies(filter: {
    moreLikeThis: { like: "疫苗 副作用" }
    embedding: 0.7
  }) {
    edges { node { id text } }
  }
}

媒體查詢（僅 ListArticles）

傳入媒體 URL + embedding，就會對圖片／音訊／影片做語意 kNN：

query {
  ListArticles(filter: {
    mediaUrl: "https://example.com/suspicious.jpg"
    embedding: 0.7
  }) {
    edges { node { id articleType attachmentHash } }
  }
}

- 若該媒體系統裡已有（相同內容雜湊），直接重用既有向量，不重算。
- 沒有的話，伺服器會抓該 URL 的內容即時產生向量（不落地 GCS）。

行為與注意事項

- Opt-in：沒傳 embedding 時一律純 BM25，行為不變。
- 永不弄壞搜尋：若向量產生失敗（例如外部服務異常），會自動退回純 BM25。
- 相似度門檻：embedding 的值是每個查詢片段對文件向量的最小 cosine 相似度；低於門檻的候選會被丟掉。
- 音訊／影片：文件向量只涵蓋前 80 秒（模型單次上限）；超過的內容仍由逐字稿走 BM25 涵蓋。

伺服器端前提

- 必須設定 GEMINI_API_KEY（查詢向量與文件向量都靠它產生）。
- 文件要先有向量才搜得到：
  - 新文章／回覆建立時會自動 embed。
  - 舊資料需跑 backfill：node build/scripts/migrations/backfillVertexEmbeddings.js --index both
（建議先 --dry-run 或 --limit 小量試跑）。

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[gemini-code-assist]

Code Review

This pull request introduces AI embedding generation and caching capabilities. It adds a new EMBEDDING type to the GraphQL schema, implements a createEmbedding utility using Google Vertex AI with support for media chunking, and includes comprehensive tests. Feedback focuses on a breaking change in the createAIResponse utility that affects existing callers, the lack of handling for concurrent 'LOADING' states which could lead to redundant API calls, and opportunities to improve performance by parallelizing media chunk processing and reusing AI clients. Additionally, the AIEmbedding GraphQL type should include the text field to expose error messages.

[gemini-code-assist]

The current logic only returns cached embeddings if the status is SUCCESS. If an embedding is currently being generated (status: 'LOADING'), this code will proceed to call createAIResponse, which likely creates a duplicate loading record and starts a redundant generation process. It should instead wait for the existing process to complete.

[gemini-code-assist]

The AIEmbedding type is missing the text field. Since createEmbedding stores error messages in the text field when the status is ERROR, this field should be added to the GraphQL model to allow clients to retrieve error details.

  fields: {
    ...commonAiResponseFields,
    text: { type: GraphQLString },
  },

[coveralls]

coverage: 82.958% (+0.7%) from 82.22% — vector-search into master