跳至主要内容

AI Gateway

Vecstruct AI Gateway 讓你透過一個統一 API 存取 OpenAI、Anthropic、Google 等多家 AI 服務。格式與 OpenAI 100% 相容，現有的 OpenAI 整合只需替換 base_url 就能切換。

不用管多組 API Key，不用擔心單一 Provider 掛掉，帳單也統一在一個地方。

支援的功能​

  • Chat Completions — 對話生成，支援串流回應
  • Embeddings — 文字向量化，用於語義搜尋、相似度計算
  • Rerank — 重新排序搜尋結果，提升相關性精準度
  • Models — 查詢可用模型清單

模型代碼格式​

所有模型以 provider/model-name 格式指定：

openai/gpt-4o
anthropic/claude-3-5-sonnet-20241022
google/gemini-2.0-flash
baai/bge-reranker-v2-m3

可用模型清單：vecstruct.com/models 或透過 Models API 查詢。

Chat Completions​

基本對話​

import { Vecstruct } from '@vecstruct/sdk';

const client = new Vecstruct({ apiKey: process.env.VECSTRUCT_API_KEY });

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'system', content: '你是一位資深工程師，擅長解釋技術概念。' },
    { role: 'user', content: '什麼是向量搜尋？' },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

console.log(reply.choices[0].message.content);
console.log('使用 token 數:', reply.usage.total_tokens);

串流回應​

串流模式下，AI 生成的文字會即時分段推送，適合需要即時顯示的使用者介面。

for await (const event of client.chat.completions.stream({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '寫一段關於向量搜尋的說明' }],
})) {
  if (event.type === 'chunk') {
    process.stdout.write(event.chunk.choices[0]?.delta.content ?? '');
  } else if (event.type === 'vecstruct') {
    // 串流結束後的統計資訊（消耗 token 數、audit ID 等）
    console.log('\n--- 統計:', event.vecstruct);
  }
}

Embeddings​

Embedding 把文字轉成一組數字（向量），讓你可以計算兩段文字的語義相似度。常用於搜尋、推薦、分群等場景。

通俗解釋：想像把每段文字映射到一個多維空間上的點，語義相近的文字在空間中距離更近。

const res = await client.embeddings.create({
  model: 'openai/text-embedding-3-small',
  input: ['向量搜尋是什麼', '機器學習的基本概念'],
});

console.log('向量維度:', res.data[0].embedding.length); // 1536

應用場景：

  • 語義搜尋：計算用戶查詢與文件的相似度
  • 推薦系統：找到與當前內容相似的其他內容
  • 文字分群：把相似主題的文章自動歸類

Rerank​

Rerank 把一組候選文件按照與查詢的相關性重新排序，讓最相關的結果排在最前面。比單純的向量搜尋更精準。

通俗解釋：向量搜尋好比用關鍵字找出一批候選，Rerank 則是精讀每篇候選文章後，挑出真正最符合問題的那幾篇。

const res = await client.rerank.create({
  model: 'baai/bge-reranker-v2-m3',
  query: 'PostgreSQL 連線池設定方法',
  documents: [
    'PostgreSQL 使用 max_connections 控制最大連線數，搭配 PgBouncer 可實現連線池。',
    'Redis 快取層可以降低資料庫查詢壓力，適合高頻讀取的資料。',
    '設定 pool_size 和 max_overflow 可調整 SQLAlchemy 的連線池行為。',
    '資料庫 index 設計對查詢效能影響很大，特別是複合索引的欄位順序。',
  ],
  top_n: 2,
});

for (const r of res.results) {
  console.log(`相關度: ${r.relevance_score.toFixed(3)} | ${r.document}`);
}

應用場景：

  • 精確化 RAG 結果：先向量搜尋取 20 篇，再用 Rerank 篩出最相關的 5 篇
  • 搜尋系統優化：技術文件搜尋、學術論文搜尋

應用場景範例​

範例一：個人技術知識庫助手​

把你的筆記、技術文件、讀過的文章上傳到知識庫，有問題直接問 AI，不用自己翻。

// 查詢你的技術筆記
const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'system', content: '根據知識庫的內容回答問題，引用來源。如果資料庫裡沒有相關內容就直接說。' },
    { role: 'user', content: 'Kubernetes pod 一直 CrashLoopBackOff 的排查步驟是什麼？' },
  ],
  vecstruct: {
    rag: true,      // 開啟知識庫查詢
    rag_top_k: 5,
  },
});

console.log(reply.choices[0].message.content);
if (reply.vecstruct?.rag_sources?.length) {
  console.log('引用來源:');
  for (const src of reply.vecstruct.rag_sources) {
    console.log(`  - ${src.title} (相似度 ${src.similarity.toFixed(2)})`);
  }
}

範例二：根據複雜度自動選模型​

簡單問題用便宜的模型，複雜分析才啟用高階模型，在品質和成本之間取平衡。

// 判斷問題複雜度
const isComplex = userQuery.length > 200 || userQuery.includes('分析') || userQuery.includes('比較');

const reply = await client.chat.completions.create({
  // 簡單問答用 gemini-2.5-flash-lite，複雜分析用 gpt-5.5
  model: isComplex ? 'openai/gpt-5.5' : 'google/gemini-2.5-flash-lite',
  messages: [{ role: 'user', content: userQuery }],
});

範例三：多語言研究助理​

上傳英文論文和中文筆記混合的知識庫，用你習慣的語言提問，AI 自動跨語言搜尋並整理回答。

const reply = await client.chat.completions.create({
  model: 'google/gemini-2.0-flash',
  messages: [
    { role: 'user', content: '這些論文裡有提到 attention mechanism 的哪些改進方向？用繁體中文整理重點。' },
  ],
  vecstruct: {
    rag: true,
    rag_top_k: 8,
    use_memory: true,   // 記住用戶的研究偏好
  },
});

注意事項​

  • 模型代碼大小寫敏感，需與 Models API 回傳的完全一致
  • max_tokens 未設定時，由各 provider 決定最大輸出長度
  • 串流模式下，Vecstruct 的統計資訊（RAG 引用、消耗費用等）在最後的 event: vecstruct 事件中回傳