valyu-best-practices

适用于AI代理的完整Valyu API工具包。当需要执行跨网页、学术、医疗、交通、金融来源的实时搜索、从URL提取内容、带引用的AI驱动答案或全面的深度研究报告时，请使用此技能。

24Star

0Fork

更新于 2026/7/26

获取 Skill 源代码

Valyu 最佳实践

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

快速参考：选择合适的API

使用以下决策树选择适当的Valyu API：

你需要什么？

├─ 跨多个来源查找信息
│  └─ 使用搜索API
│
├─ 从特定URL提取内容
│  └─ 使用内容API
│
├─ 获取带引用的AI合成答案
│  └─ 使用答案API
│
├─ 生成全面的研究报告
│  └─ 使用深度研究API
│
└─ 发现可用的数据源
   └─ 使用数据源API

⚠️ 强制要求：使用官方Valyu SDK库

关键：在编写使用Valyu API的代码时，必须使用官方SDK库。切勿直接对Valyu API端点进行原始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. 搜索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. 内容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. 答案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. 深度研究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"`

深度研究配方

详细模式请参见：

5. 查询编写最佳实践

核心原则

具体明确 - 使用领域术语
简洁精炼 - 查询不超过400字符
聚焦主题 - 每次查询一个主题
添加约束 - 包含时间范围、来源类型

查询结构

元素	描述	示例
意图	你需要什么	"最新进展" vs "概述"
领域	主题术语	"transformer architecture"
约束	过滤器	"2024"、"peer-reviewed"
来源类型	查找位置	学术论文、SEC文件

好查询与差查询

差：  "I want to know about AI"
好：  "transformer attention mechanism survey 2024"

差：  "Apple financial information"
好：  "Apple revenue growth Q4 2024 earnings SEC filing"

差：  "gene editing research"
好：  "CRISPR off-target effects therapeutic applications 2024"

拆分复杂请求

# 不要这样做
"Tesla stock performance, new products, and Elon Musk statements"

# 改为这样做
查询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

相关 Skills

Valyu 最佳实践

快速参考：选择合适的API

⚠️ 强制要求：使用官方Valyu SDK库

JavaScript/TypeScript：valyu-js

Python：valyu

为什么使用SDK而非原始API调用？

❌ 切勿这样做

✅ 始终这样做

1. 搜索API

何时使用

基本用法

搜索类型

关键参数

特定领域搜索模式

搜索配方

2. 内容API

何时使用

基本用法

带摘要

结构化提取（JSON Schema）

关键参数

内容配方

3. 答案API

何时使用

基本用法

快速模式（低延迟）

自定义指令

流式输出

结构化输出

关键参数

答案配方

4. 深度研究API

何时使用

研究模式

创建研究任务

轮询完成状态

关键参数

深度研究配方

5. 查询编写最佳实践

核心原则

查询结构

好查询与差查询

拆分复杂请求

来源过滤

6. 常见工作流

研究工作流

金融分析工作流

7. 可用数据源

8. API参考

9. 集成指南

其他资源

你可能还喜欢

mcp-builder

planning-with-files

planning-and-task-breakdown

继续探索

JavaScript/TypeScript：`valyu-js`

Python：`valyu`