valyu-best-practices

Valyu 最佳实践

本技能提供有关如何使用 Valyu API 执行搜索、内容提取、AI 驱动的回答和深度研究任务的说明。

快速参考：选择合适的 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

为什么使用 SDK，而不是直接调用 API？

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）
• 交通运输（英国国家铁路、全球航运）

基本用法

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

用途： 从网页中提取整洁、结构化的内容，以便大模型处理。

适用场景

• 将网页转换为整洁的 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. 聚焦主题 - 每个查询只涵盖一个主题
4. 添加限制条件 - 包含时间范围、来源类型

查询要素

要素	说明	示例
意图	你需要什么	“最新进展”与“概述”
领域	主题术语	“transformer 架构”
限制条件	筛选条件	“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 - 《新英格兰医学杂志》
• 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 文档

// 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（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. 集成指南

特定平台的集成文档：

• Anthropic Claude
• OpenAI
• Vercel AI SDK
• LangChain
• LlamaIndex
• MCP 服务

---

其他资源

• 所有示例索引
• 设计理念
• 提示词指南
• 完整 API 参考