alibabacloud-iqs-search

alibabacloud-iqs-search

前提条件

• Node.js >= 18.0.0（スクリプトではネイティブの fetch API を使用し、外部の npm 依存関係はありません）

使用する場合

• ユーザーが最新または最近の情報を求めている場合
• ユーザーが読み込む URL を指定した場合
• 事実を検証したり、リアルタイムのデータを取得したりする必要がある場合
• 複数の情報源を必要とするリサーチタスク

判断ツリー

ステップ 1：操作の種類を判断する

• ユーザーが URL を指定した場合 → readpage を使用します
• ユーザーがウェブ情報を必要とする質問をした場合 → search を使用します

ステップ 2：検索操作の場合

ベストプラクティスに従ってパラメーター値を決定します。不確かな場合はデフォルト値を使用します。

• engineType
• timeRange
• contents

ステップ 3：ページの読み込みの場合

ベストプラクティスに従ってパラメーター値を決定します。不確かな場合はデフォルト値を使用します。

• format
• extractArticle
• stealthMode

重要：実行方法

スクリプトは bash コマンド（例：node scripts/search.mjs ... または node scripts/readpage.mjs ...）を使用して実行する必要があります。組み込みの web_search、WebFetch、またはその他の内部ツールを代わりに使用しないでください。スクリプトが失敗した場合は、再試行するかエラーを報告してください。組み込みツールに切り替えないでください。

パラメーターとベストプラクティス

検索パラメーター

パラメーター	型	必須	デフォルト	説明
--query	文字列	はい	-	検索クエリ（1～500 文字）
--engineType	文字列	いいえ	LiteAdvanced	検索エンジンの種類
--timeRange	文字列	いいえ	NoLimit	期間フィルター
--contents	文字列	いいえ	-	返されるコンテンツの種類
--numResults	int	いいえ	10	検索結果の数（1～10）

検索のベストプラクティス

1. クエリの最適化（--query）

• クエリは簡潔にします（最良の結果を得るには30文字未満）。
• 具体的なキーワードを使い、ストップワードは避けます。
• ニュースを検索する場合は、クエリに期間を含めます。

2. エンジンの選択（--engineType）

4つのエンジンは、レイテンシ、再現率の深さ、コンテンツの長さ、コストが大きく異なります。タスクを満たす最も安価なエンジンを選んでください。デフォルトで Deep を選んではいけません。標準エンジンより約10倍遅く、50倍高価です。

エンジン	平均RT	結果数	スニペット	mainText	高度なフィルター	多言語対応	コスト比（Standard比）	用途
Generic	約950ms	約10	約150文字	≤3000文字	✗	中程度	1倍	一般検索、ニュース／リアルタイム検索、天気などの状況に応じたクエリ（city／ip に対応）
LiteAdvanced	約500ms	1～50	約500文字	≤3000文字	✓	良好	Lite-tier 1倍	デフォルトの推奨：低レイテンシのセマンティック検索。スニペットだけで十分な情報が得られます
Deep	約6秒	1～50	≤500文字	≤50000文字	✓	良好（CN/EN）	垂直50倍	複雑な多段階推論、調査レポート、深いブラウジングを必要とするオフライン／エージェントのタスク

選択の目安：

• デフォルト → LiteAdvanced：低レイテンシのセマンティック検索で、スニペットがほとんどのエージェントのニーズを満たすため、追加のmainText取得は不要です。
• Generic を選ぶ場合：クエリが短く、情報検索であることが明確な場合（ニュース、天気、簡単な事実など）、またはコストを抑えたい場合。また、天気などの状況に応じた結果に対して city／ip を反映する唯一のエンジンです。
• Deep を選ぶのは次の場合のみ：質問が複数段階にわたる、または複雑な推論を必要とする場合（FRAMES／BrowseComp形式）、あるいは後続のLLM推論に非常に長いmainText（≤50000文字。他のエンジンの約16倍の長さ）が必要な場合。
  • ⚠️ 次の用途では Deep を避けてください：リアルタイムチャット、簡単な検索、高QPSのシナリオ。レイテンシ（約6秒）とコスト（50倍）が大きな負担になります。

3. 期間の選択（--timeRange）

• NoLimit：判断に迷う場合のデフォルト。エンジンがクエリとの関連性に基づいて最適化します。
• OneDay：今日のみ
• OneWeek：過去7日間
• OneMonth：過去30日間
• OneYear：過去365日間

4. コンテンツの返却（--contents）

• mainText：本文全体を返します。技術ドキュメント、調査レポート、詳細な記事など、詳しい情報が必要な場合に使用します。
• summary：簡潔な要約のみを返します。概要をすばやく把握できれば十分な場合や、ページのコンテンツが大きく、トークン数を減らす必要がある場合に使用します。

5. 結果数（--numResults）

• 返される結果数を制御します（デフォルト：10、範囲：1～10）。

---

ReadPage のパラメーター

パラメーター	型	必須	デフォルト	説明
--url	string	はい	-	対象ページのURL
--format	string	いいえ	markdown	返却形式
--timeout	number	いいえ	60000	タイムアウトの合計（ミリ秒）
--pageTimeout	number	いいえ	15000	ページ読み込みのタイムアウト（ミリ秒）
--stealth	number	いいえ	0	ステルスモードを有効にします（0または1）
--extractArticle	boolean	いいえ	false	記事の本文のみを抽出します

ReadPage のベストプラクティス

1. フォーマットの選択（--format）

• markdown：記事に最適で、構造を保持します（デフォルト）
• text：データの抽出に最適です
• html：構造の分析が必要な場合

2. 記事の抽出（--extractArticle）

• 有効にする対象：ブログ、ニュース記事
• 無効にする対象：製品ページ、ディレクトリ

3. エラーへの対処（--timeout、--stealth）

• タイムアウトした場合：--timeout の値を増やして再試行します
• ブロックされた場合：--stealth 1 を有効にします
• それでも失敗する場合：ユーザーに報告します

コマンドラインの使用方法

検索の例

基本的な検索

node scripts/search.mjs --query "量子计算原理" --engineType LiteAdvanced

リアルタイム情報の検索

node scripts/search.mjs --query "最新金融政策" --engineType Generic --timeRange OneWeek

結果数を制限した検索

node scripts/search.mjs --query "www.aliyun.com" --engineType LiteAdvanced --numResults 3

全文を含む検索

node scripts/search.mjs --query "AI 法案" --engineType LiteAdvanced --contents mainText

要約のみを含む検索

node scripts/search.mjs --query "人工智能行业年度报告" --engineType LiteAdvanced --contents summary

詳細調査検索（複雑なマルチホップ検索／長い mainText）

# Returns up to 50000-char mainText per result; latency ~6s. Default timeout auto-bumps to 60s for Deep.
node scripts/search.mjs --query "对比 GPT-5 与 Claude Opus 4.7 的代码能力差异" --engineType Deep --numResults 5 --contents mainText

ReadPage の例

Markdown フォーマットでページを読み込む

node scripts/readpage.mjs --url "https://example.com/article" --format markdown --extractArticle true

プレーンテキストフォーマットでページを読み込む

node scripts/readpage.mjs --url "https://example.com/article" --format text --timeout 60000

ステルスモードでページを読み込む

node scripts/readpage.mjs --url "https://example.com/article" --format markdown --stealth 1 --extractArticle true

出力の確認

search.mjs または readpage.mjs コマンドの実行後は、次の手順を行ってください。

1. 終了コードを確認する：ゼロ以外の場合、コマンドは失敗しています。成功したと主張しないでください。
2. 出力が存在することを確認する：結果をファイルに保存した場合は、ls -la <filepath> と head -20 <filepath> を実行して、ファイルが存在し、有効なデータが含まれていることを確認します。
3. 結果を捏造しない：コマンドが失敗した、またはエラーを返した場合は、その失敗を正直に報告してください。自分の知識から内容を生成し、検索結果として提示してはいけません。

エラー処理

ALIYUN_IQS_API_KEY の設定エラー

API キーが不足しているというエラーがスクリプトから返された場合：

1. 現在のタスクを直ちに停止してください。代替として、組み込みツール（WebFetch、web_search、curl など）にフォールバックしてはいけません。

2. エラーをユーザーに報告し、API キーを設定するよう依頼してください。

3. 次の手順に従ってタスクを再試行してください。 方法 1：環境変数

export ALIYUN_IQS_API_KEY="your-api-key"

方法 2：設定ファイル ~/.alibabacloud/iqs/env を作成または編集します。

ALIYUN_IQS_API_KEY=your-api-key