valyu-best-practices

Valyu のベストプラクティス

このスキルでは、検索、コンテンツ抽出、AI による回答、ディープリサーチのタスクに Valyu API を使用する手順を説明します。

クイックリファレンス：適切な API の選び方

次の判断フローを使用して、適切な Valyu API を選択してください。

What do you need?

├─ Find information across multiple sources
│  └─ Use Search API
│
├─ Extract content from specific URLs
│  └─ Use Contents API
│
├─ Get an AI-synthesized answer with citations
│  └─ Use Answer API
│
├─ Generate a comprehensive research report
│  └─ Use DeepResearch API
│
└─ Discover available data sources
   └─ Use Datasources API

---

⚠️ 必須：公式 Valyu SDK ライブラリを使用してください

重要：Valyu API を使用するコードを書く場合は、公式 SDK ライブラリを必ず使用してください。Valyu API エンドポイントへの生の HTTP/fetch 呼び出しは絶対に行わないでください。

JavaScript/TypeScript：valyu-js

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

import { Valyu } from 'valyu-js';

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

// Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deepResearch

Python：valyu

pip install valyu
# or
uv add valyu

from valyu import Valyu

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

# Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deep_research

生の API 呼び出しより SDK を使う理由

1. 型安全性 - すべてのパラメーターとレスポンスに、完全な TypeScript/Python の型ヒントが用意されています
2. 自動再試行 - 一時的な障害に対する再試行ロジックが組み込まれています
3. ストリーミングのサポート - ストリーミングレスポンスに適した非同期イテレーターをサポートしています
4. エラー処理 - わかりやすいメッセージを含む、構造化されたエラー型が用意されています
5. 将来の互換性 - SDK の更新によって API の変更が自動的に処理されます

❌ 絶対に行わないでください

// DON'T make raw fetch calls
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: '...' })
});

✅ 必ず次のようにしてください

// DO use the 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）
• 交通（UK National Rail、Global Shipping）

基本的な使い方

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 スキーマ
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) {
  // Handle: 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 スキーマ	{type: "object", ...}
streaming	streaming	SSE ストリーミングを有効化	true
dataMaxPrice	data_max_price	金額の上限	1.0

Answer のレシピ

詳しいパターンについては、以下を参照してください。

• 基本的な回答
• 高速モード
• ストリーミング
• カスタム指示

---

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"
});
// Returns: { 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 report
  console.log(status.sources); // Cited sources
  console.log(status.pdf_url); // PDF download link
}

主なパラメーター

パラメーター（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. クエリ作成のベストプラクティス

基本原則

1. 具体的にする - 分野の専門用語を使います
2. 簡潔にする - クエリは400文字未満にします
3. 焦点を絞る - 1つのクエリにつき1つのトピックにします
4. 制約を追加する - 期間やソースの種類を含めます

クエリの構成要素

要素	説明	例
意図	必要なもの	「最新の進展」と「概要」
分野	トピックの用語	「トランスフォーマーアーキテクチャ」
制約	フィルター	「2024年」、「査読済み」
ソースの種類	検索対象	学術論文、SEC提出書類

良いクエリと悪いクエリ

BAD:  "I want to know about AI"
GOOD: "transformer attention mechanism survey 2024"

BAD:  "Apple financial information"
GOOD: "Apple revenue growth Q4 2024 earnings SEC filing"

BAD:  "gene editing research"
GOOD: "CRISPR off-target effects therapeutic applications 2024"

複雑なリクエストを分割する

# Don't do this
"Tesla stock performance, new products, and Elon Musk statements"

# Do this instead
Query 1: "Tesla stock performance Q4 2024"
Query 2: "Tesla Cybertruck production updates 2024"
Query 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 - New England Journal of Medicine
• thelancet.com - The Lancet ​ 技術ドキュメントコレクション。含めるソースの例：
• docs.aws.amazon.com - AWSのドキュメント
• cloud.google.com/docs - Google Cloudのドキュメント
• learn.microsoft.com - Microsoftのドキュメント
• kubernetes.io/docs - Kubernetesのドキュメント
• developer.mozilla.org - MDN Web Docs

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

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

// Tech news
includedSources: ["techcrunch.com", "theverge.com", "arstechnica.com"]

プロンプト作成ガイドの全文については、references/prompting.md を参照してください。

---

6. 一般的なワークフロー

リサーチのワークフロー

// 1. Quick search to find sources
const searchResults = await valyu.search({
  query: "CRISPR therapeutic applications",
  searchType: "proprietary",
  maxNumResults: 20
});

// 2. Extract key content from top results
const contents = await valyu.contents({
  urls: searchResults.results.slice(0, 3).map(r => r.url),
  summary: "Extract key findings"
});

// 3. Deep analysis for comprehensive report
const research = await valyu.deepResearch.create({
  query: "CRISPR therapeutic applications comprehensive review",
  model: "heavy"
});

財務分析のワークフロー

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

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

// 3. Structured extraction
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（3,700万件以上）、bioRxiv、medRxiv
金融	SEC提出書類、決算説明会の記録、株式データ、暗号資産
ヘルスケア	臨床試験、DailyMed、PubChem、医薬品ラベル、ChEMBL、DrugBank、Open Target、WHO ICD
経済	FRED、BLS、World Bank、US Treasury、Destatis
予測	Polymarket、Kalshi
特許	米国特許データベース
交通	UK Rail、船舶追跡

データソースの詳細については、references/datasources.md を参照してください。

---

8. APIリファレンス

すべてのパラメーター、レスポンス構造、エラーコードを含むAPIドキュメントの全文については、references/api-guide.md を参照してください。

---

9. インテグレーションガイド

プラットフォーム別のインテグレーションドキュメント：

• Anthropic Claude
• OpenAI
• Vercel AI SDK
• LangChain
• LlamaIndex
• MCP サーバー

---

その他のリソース

• すべてのレシピのインデックス
• 設計思想
• プロンプト作成ガイド
• APIリファレンス全文