valyu-best-practices

完整的 Valyu API 工具包，專為 AI 代理設計。當需要執行跨網路、學術、醫療、交通、金融來源的即時搜尋、從 URL 提取內容、提供附引用來源的 AI 答案，或生成深入研究報告時，請使用此技能。

24星標

0分支

更新於 2026/7/26

獲取技能源代碼

Valyu 最佳實踐

本技能提供使用 Valyu API 執行搜尋、內容提取、AI 答案及深入研究的操作指南。

快速參考：選擇正確的 API

使用以下決策樹選擇合適的 Valyu API：

你需要什麼？

├─ 從多個來源尋找資訊
│  └─ 使用 Search API
│
├─ 從特定 URL 提取內容
│  └─ 使用 Contents API
│
├─ 取得附引用來源的 AI 合成答案
│  └─ 使用 Answer API
│
├─ 生成全面的研究報告
│  └─ 使用 DeepResearch API
│
└─ 探索可用的資料來源
   └─ 使用 Datasources API

⚠️ 強制：使用官方 Valyu SDK 函式庫

重要：在撰寫使用 Valyu API 的程式碼時，你必須使用官方 SDK 函式庫。絕對不要直接對 Valyu API 端點進行 raw HTTP/fetch 呼叫。

JavaScript/TypeScript：`valyu-js`

npm install valyu-js
# 或
pnpm add valyu-js

import { Valyu } from 'valyu-js';

const valyu = new Valyu(process.env.VALYU_API_KEY);

// 現在可以使用 valyu.search()、valyu.contents()、valyu.answer()、valyu.deepResearch

Python：`valyu`

pip install valyu
# 或
uv add valyu

from valyu import Valyu

valyu = Valyu(api_key=os.environ.get("VALYU_API_KEY"))

# 現在可以使用 valyu.search()、valyu.contents()、valyu.answer()、valyu.deep_research

為什麼使用 SDK 而非直接呼叫 API？

型別安全 - 所有參數與回應皆有完整的 TypeScript/Python 型別提示
自動重試 - 內建暫時性失敗的重試邏輯
串流支援 - 正確的非同步迭代器支援串流回應
錯誤處理 - 結構化的錯誤型別，附帶實用訊息
未來相容性 - SDK 更新會自動處理 API 變更

❌ 絕對不要這樣做

// 不要直接使用 fetch 呼叫
const response = await fetch('https://api.valyu.ai/v1/search', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: '...' })
});

✅ 永遠這樣做

// 使用 SDK
import { Valyu } from 'valyu-js';

const valyu = new Valyu(process.env.VALYU_API_KEY);
const response = await valyu.search({ query: '...' });

1. Search API

用途： 在網路、學術、醫療、交通、金融、新聞及專有來源中尋找資訊。

使用時機

尋找任何主題的最新資訊
學術研究（arXiv、PubMed、bioRxiv、medRxiv）
金融資料（SEC 申報文件、財報、股票資料）
新聞監控與即時事件
醫療保健資料（臨床試驗、藥品標籤）
預測市場（Polymarket、Kalshi）
交通運輸（英國國鐵、全球航運）

基本用法

const response = await valyu.search({
  query: "transformer architecture attention mechanism 2024",
  searchType: "all",
  maxNumResults: 10
});

搜尋類型

類型	用途
`all`	所有來源 - 網路、學術、金融、專有
`web`	僅一般網路內容
`proprietary`	授權學術論文與研究
`news`	新聞文章與即時事件

主要參數

參數 (TS/JS)	參數 (Python)	用途	範例
`query`	`query`	搜尋查詢（400 字元以內）	`"CRISPR gene editing 2024"`
`searchType`	`search_type`	來源範圍	`"all"`、`"web"`、`"proprietary"`、`"news"`
`maxNumResults`	`max_num_results`	結果數量（1-20）	`10`
`includedSources`	`included_sources`	限制特定來源	`["valyu/valyu-arxiv", "valyu/valyu-pubmed"]`
`startDate` / `endDate`	`start_date` / `end_date`	日期篩選	`"2024-01-01"`
`relevanceThreshold`	`relevance_threshold`	最低相關性（0-1）	`0.7`

領域特定搜尋模式

學術研究：

await valyu.search({
  query: "CRISPR therapeutic applications clinical trials",
  searchType: "proprietary",
  includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "valyu/valyu-biorxiv"],
  startDate: "2024-01-01"
});

財務分析：

await valyu.search({
  query: "Apple revenue Q4 2024 earnings",
  searchType: "all",
  includedSources: ["valyu/valyu-sec-filings", "valyu/valyu-earnings-US"]
});

新聞監控：

await valyu.search({
  query: "AI regulation EU",
  searchType: "news",
  startDate: "2024-06-01",
  countryCode: "EU"
});

搜尋食譜

詳細模式請參閱：

2. Contents API

用途： 從網頁提取乾淨、結構化的內容，最佳化供 LLM 處理。

使用時機

將網頁轉換為乾淨的 Markdown
提取文章文字進行摘要
解析文件供 RAG 系統使用
從產品頁面提取結構化資料
處理學術論文

基本用法

const response = await valyu.contents({
  urls: ["https://example.com/article"]
});

搭配摘要

const response = await valyu.contents({
  urls: ["https://arxiv.org/abs/2401.12345"],
  summary: "Extract key findings in 3 bullet points"
});

結構化提取（JSON Schema）

const response = await valyu.contents({
  urls: ["https://example.com/product"],
  summary: {
    type: "object",
    properties: {
      product_name: { type: "string" },
      price: { type: "number" },
      features: { type: "array", items: { type: "string" } }
    },
    required: ["product_name", "price"]
  }
});

主要參數

參數 (TS/JS)	參數 (Python)	用途	範例
`urls`	`urls`	要處理的 URL（1-10 個）	`["https://example.com"]`
`responseLength`	`response_length`	內容長度	`"short"`、`"medium"`、`"large"`、`"max"`
`extractEffort`	`extract_effort`	提取品質	`"normal"`、`"high"`、`"auto"`
`summary`	`summary`	AI 摘要	`true`、`"instructions"` 或 JSON schema
`screenshot`	`screenshot`	擷取螢幕截圖	`true`

內容食譜

詳細模式請參閱：

3. Answer API

用途： 取得基於即時搜尋結果、附引用來源的 AI 答案。

使用時機

需要綜合最新資訊的問題
多來源事實驗證
技術文件問題
需要引用來源的研究
從搜尋結果提取結構化資料

基本用法

const response = await valyu.answer({
  query: "What are the latest developments in quantum computing?"
});

快速模式（較低延遲）

const response = await valyu.answer({
  query: "Current Bitcoin price and 24h change",
  fastMode: true
});

自訂指令

const response = await valyu.answer({
  query: "Compare React and Vue for enterprise applications",
  systemInstructions: "Provide a balanced comparison with pros and cons. Format as a comparison table."
});

串流

const stream = await valyu.answer({
  query: "Explain transformer architecture",
  streaming: true
});

for await (const chunk of stream) {
  // 處理：search_results、content、metadata、done、error
  console.log(chunk);
}

結構化輸出

const response = await valyu.answer({
  query: "Apple Q4 2024 financial highlights",
  structuredOutput: {
    type: "object",
    properties: {
      revenue: { type: "string" },
      growthRate: { type: "string" },
      keyHighlights: { type: "array", items: { type: "string" } }
    }
  }
});

主要參數

參數 (TS/JS)	參數 (Python)	用途	範例
`query`	`query`	要回答的問題	`"What is quantum computing?"`
`fastMode`	`fast_mode`	較低延遲	`true`
`systemInstructions`	`system_instructions`	AI 指令	`"Be concise"`
`structuredOutput`	`structured_output`	JSON schema	`{type: "object", ...}`
`streaming`	`streaming`	啟用 SSE 串流	`true`
`dataMaxPrice`	`data_max_price`	美元上限	`1.0`

答案食譜

詳細模式請參閱：

4. DeepResearch API

用途： 生成包含詳細分析與引用來源的全面研究報告。

使用時機

全面的市場分析
文獻回顧
競爭情報
技術深度探討
需要多來源綜合的主題

研究模式

模式	持續時間	最佳用途
`fast`	約 5 分鐘	快速查詢、簡單問題
`standard`	約 10-20 分鐘	平衡研究（最常見）
`heavy`	約 90 分鐘	全面分析、複雜主題

建立研究任務

const task = await valyu.deepResearch.create({
  query: "AI chip market competitive landscape 2024",
  model: "standard"
});
// 回傳：{ deepresearch_id: "abc123", status: "queued" }

輪詢完成狀態

const status = await valyu.deepResearch.getStatus(task.deepresearch_id);
// status: "queued" | "running" | "completed" | "failed" | "cancelled"

if (status.status === "completed") {
  console.log(status.output);  // Markdown 報告
  console.log(status.sources); // 引用來源
  console.log(status.pdf_url); // PDF 下載連結
}

主要參數

參數 (TS/JS)	參數 (Python)	用途	範例
`query`	`query`	研究問題	`"AI market trends 2024"`
`model`	`model`	研究深度	`"fast"`、`"standard"`、`"heavy"`
`outputFormat`	`output_format`	報告格式	`"markdown"`、`"pdf"`
`includedSources`	`included_sources`	來源篩選	`["valyu/valyu-arxiv", "techcrunch.com"]`
`startDate` / `endDate`	`start_date` / `end_date`	日期範圍	`"2024-01-01"`

DeepResearch 食譜

詳細模式請參閱：

5. 查詢撰寫最佳實踐

核心原則

具體明確 - 使用領域術語
簡潔扼要 - 查詢保持在 400 字元以內
聚焦主題 - 每次查詢一個主題
加入限制 - 包含時間範圍、來源類型

查詢結構

元素	說明	範例
意圖	你需要什麼	"最新進展" vs "概述"
領域	主題術語	"transformer architecture"
限制	篩選條件	"2024"、"同儕審查"
來源類型	搜尋範圍	學術論文、SEC 申報文件

好查詢 vs 壞查詢

壞："我想了解 AI"
好："transformer attention mechanism survey 2024"

壞："Apple 財務資訊"
好："Apple revenue growth Q4 2024 earnings SEC filing"

壞："基因編輯研究"
好："CRISPR off-target effects therapeutic applications 2024"

拆分複雜請求

# 不要這樣做
"Tesla 股票表現、新產品、以及 Elon Musk 的聲明"

# 改為這樣做
查詢 1："Tesla stock performance Q4 2024"
查詢 2："Tesla Cybertruck production updates 2024"
查詢 3："Tesla FSD autonomous driving progress"

來源篩選

使用 includedSources 進行領域權威篩選：

金融研究集合。可包含的來源：

valyu/valyu-sec-filings - SEC 監管申報文件
valyu/valyu-stocks - 股票市場資料
valyu/valyu-earnings-US - 財報
reuters.com - 金融新聞
bloomberg.com - 市場分析

醫學研究集合。可包含的來源：

valyu/valyu-pubmed - 醫學文獻
valyu/valyu-clinical-trials - 臨床試驗資料
valyu/valyu-drug-labels - FDA 藥品資訊
nejm.org - 新英格蘭醫學期刊
thelancet.com - 刺胳針

技術文件集合。可包含的來源：

docs.aws.amazon.com - AWS 文件
cloud.google.com/docs - Google Cloud 文件
learn.microsoft.com - Microsoft 文件
kubernetes.io/docs - Kubernetes 文件
developer.mozilla.org - MDN Web 文件

// 學術
includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "nature"]

// 金融
includedSources: ["valyu/valyu-sec-filings", "bloomberg.com", "reuters.com"]

// 科技新聞
includedSources: ["techcrunch.com", "theverge.com", "arstechnica.com"]

完整提示指南請參閱 references/prompting.md。

6. 常見工作流程

研究工作流程

// 1. 快速搜尋尋找來源
const searchResults = await valyu.search({
  query: "CRISPR therapeutic applications",
  searchType: "proprietary",
  maxNumResults: 20
});

// 2. 從前幾筆結果提取關鍵內容
const contents = await valyu.contents({
  urls: searchResults.results.slice(0, 3).map(r => r.url),
  summary: "Extract key findings"
});

// 3. 深入分析生成全面報告
const research = await valyu.deepResearch.create({
  query: "CRISPR therapeutic applications comprehensive review",
  model: "heavy"
});

財務分析工作流程

// 1. 取得 SEC 申報文件
const filings = await valyu.search({
  query: "Apple 10-K 2024",
  includedSources: ["valyu/valyu-sec-filings"]
});

// 2. 快速綜合
const summary = await valyu.answer({
  query: "Apple Q4 2024 financial highlights",
  fastMode: true
});

// 3. 結構化提取
const metrics = await valyu.answer({
  query: "Apple financial metrics 2024",
  structuredOutput: {
    type: "object",
    properties: {
      revenue: { type: "string" },
      netIncome: { type: "string" },
      growthRate: { type: "string" }
    }
  }
});

7. 可用資料來源

Valyu 提供 25 個以上的專業資料集：

類別	範例
學術	arXiv（250 萬+ 論文）、PubMed（3700 萬+）、bioRxiv、medRxiv
金融	SEC 申報文件、財報逐字稿、股票資料、加密貨幣
醫療保健	臨床試驗、DailyMed、PubChem、藥品標籤、ChEMBL、DrugBank、Open Target、WHO ICD
經濟	FRED、BLS、世界銀行、美國財政部、Destatis
預測	Polymarket、Kalshi
專利	美國專利資料庫
交通運輸	英國鐵路、船舶追蹤

完整資料來源參考請參閱 references/datasources.md。

8. API 參考

完整的 API 文件，包含所有參數、回應結構及錯誤碼，請參閱 references/api-guide.md。

9. 整合指南

各平台特定的整合文件：

其他資源

您可能也喜歡

mcp-builder

69Kresearch-knowledge

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

composiohq

獲取

planning-with-files

24Kresearch-knowledge

Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.

othmanadi

獲取

planning-and-task-breakdown

77Kresearch-knowledge

將工作分解為有序的任務。當你有規格或明確的需求，需要將工作分解為可實作的任務時使用。當任務感覺太大而無法開始、需要估算範圍或可以平行工作時使用。

addyosmani

獲取

繼續探索

瀏覽 research-knowledge 熱門 Skills 最近更新

valyu-best-practices

相關技能

Valyu 最佳實踐

快速參考：選擇正確的 API

⚠️ 強制：使用官方 Valyu SDK 函式庫

JavaScript/TypeScript：valyu-js

Python：valyu

為什麼使用 SDK 而非直接呼叫 API？

❌ 絕對不要這樣做

✅ 永遠這樣做

1. Search API

使用時機

基本用法

搜尋類型

主要參數

領域特定搜尋模式

搜尋食譜

2. Contents API

使用時機

基本用法

搭配摘要

結構化提取（JSON Schema）

主要參數

內容食譜

3. Answer API

使用時機

基本用法

快速模式（較低延遲）

自訂指令

串流

結構化輸出

主要參數

答案食譜

4. DeepResearch API

使用時機

研究模式

建立研究任務

輪詢完成狀態

主要參數

DeepResearch 食譜

5. 查詢撰寫最佳實踐

核心原則

查詢結構

好查詢 vs 壞查詢

拆分複雜請求

來源篩選

6. 常見工作流程

研究工作流程

財務分析工作流程

7. 可用資料來源

8. API 參考

9. 整合指南

其他資源

您可能也喜歡

mcp-builder

planning-with-files

planning-and-task-breakdown

繼續探索

JavaScript/TypeScript：`valyu-js`

Python：`valyu`