快速入门:进行第一次 Web IQ API 调用

小窍门

在 Microsoft Ignite 2026 上?在一处即可找到所有 Web IQ 资源:文档、培训、代码示例以及如何联系团队。

在几分钟内进行第一次Microsoft Web IQ API 调用。 搜索 Web、检查响应,并从已知 URL 中提取以查询为中心的段落。 其他示例显示位置搜索和自动证据检索。

如果还没有 Web IQ 资源,请在继续之前使用 Azure 门户或Azure CLI创建一个。

选择此页面顶部的 SDK 或 REST 示例,即可同时切换所有示例。 SDK 会为你处理身份验证、重试和响应类型。

API 密钥是评估 Web IQ 的最快方法。 对于生产工作负荷,请使用Microsoft Entra ID。

Prerequisites

Note

如果应用程序在中国运行,则调用 https://api.microsoftol.com/v3 而不是 https://api.microsoft.ai/v3 搜索终结点。 在 REST 示例中,替换 URL。 构造 SDK 客户端时,请使用 Python 的参数base_url、TypeScript baseUrl 选项、Rust WebIqClient::builder().base_url(...)选项、JavaWebIQClientOptions.builder().baseUrl(...)或.NETWebIQClientOptions.BaseUrl的属性设置相同的基 URL。 请参阅 基本 URL。

小窍门

更喜欢无需代码的引导式开始吗? 在 Web IQ 开发者门户中,按照 开始使用 操作:选择应用配置文件、创建 API 密钥、从 Playground 发送请求、复制生成的代码并检查使用情况。

1. 保存您的 API 密钥

将密钥放在环境变量中,这样,请求示例就无需重复写出密钥,也不用将其放入源代码中。

macOS 或 Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

$env:WEBIQ_API_KEY="your-api-key"

Warning

不要将密钥提交到源代码管理,也不要在浏览器或客户端代码中公开密钥。 将生产凭据存储在机密管理器中。

2. 搜索网页

如果有问题或查询,并且希望 Web IQ 发现并对相关页面进行排序,请使用 Web 搜索。

我们建议在每个请求中设置maxResults = 10、contentFormat = passage和maxLength = 3000,作为优化的运行点。 在此处,可以根据用例微调这些设置。

终结点:POST https://api.microsoft.ai/v3/search/web

curl --request POST "https://api.microsoft.ai/v3/search/web" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "latest developments in retrieval augmented generation",
    "maxResults": 10,
    "contentFormat": "passage",
    "maxLength": 3000
  }'

安装 SDK(python -m pip install webiq==1.2.1Python 3.11 或更高版本),然后运行:

import os
from webiq import WebIQClient
from webiq.types import ContentFormat

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    results = client.web.search(
        "latest developments in retrieval augmented generation",
        max_results=10,
        content_format=ContentFormat.passage,
        max_length=3000,
    )
    for result in results.webResults or []:
        print(result.title, result.url)

使用 npm install @microsoft/webiq@1.2.1 安装 SDK(22.x 需 Node.js 22.18 或更高版本,或 24+)。 将此示例另存为 search.mts,并使用 node search.mts 运行它。

import { WebIQClient, ContentFormat } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const results = await client.web.search(
      "latest developments in retrieval augmented generation",
      {
        maxResults: 10,
        contentFormat: ContentFormat.PASSAGE,
        maxLength: 3000,
      },
    );
    for (const result of results.webResults ?? []) {
      console.log(result.title, result.url);
    }
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

在 Rust 1.88 或更高版本的项目中,运行 cargo add tokio --features macros,rt-multi-thread 和 cargo add webiq@1.2.1。 将此示例保存为 src/main.rs 并运行 cargo run。

use webiq::{ContentFormat, WebIqClient, WebSearchOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let results = client.web().search(
        "latest developments in retrieval augmented generation",
        WebSearchOptions::new()
            .max_results(10)
            .content_format(ContentFormat::Passage)
            .max_length(3000),
    ).await?;
    for result in results.web_results.unwrap_or_default() {
        println!("{:?} {:?}", result.title, result.url);
    }
    Ok(())
}

在为 Java 11 或更高版本配置的 Maven 项目中,将此依赖项添加到pom.xml:

<dependency>
    <groupId>com.microsoft.webiq</groupId>
    <artifactId>webiq</artifactId>
    <version>1.2.1</version>
</dependency>

将此示例保存为 src/main/java/Search.java 并运行 mvn compile exec:java -Dexec.mainClass=Search。

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.ContentFormat;
import com.microsoft.webiq.models.WebResponse;
import com.microsoft.webiq.models.WebResult;
import com.microsoft.webiq.resources.WebSearchOptions;

public class Search {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            WebResponse results = client.web.search(
                    "latest developments in retrieval augmented generation",
                    WebSearchOptions.builder()
                            .maxResults(10)
                            .contentFormat(ContentFormat.PASSAGE)
                            .maxLength(3000)
                            .build());
            if (results.getWebResults() != null) {
                for (WebResult result : results.getWebResults()) {
                    System.out.println(result.getTitle() + " " + result.getUrl());
                }
            }
        }
    }
}

在 .NET 8 或更高版本的控制台项目中,运行 dotnet add package Microsoft.WebIQ --version 1.2.1。 将此示例保存为 Program.cs 并运行 dotnet run。

using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var results = await client.Web.SearchAsync(
    "latest developments in retrieval augmented generation",
    request =>
    {
        request.MaxResults = 10;
        request.ContentFormat = ContentFormat.Passage;
        request.MaxLength = 3000;
    });
foreach (var result in results.WebResults ?? [])
    Console.WriteLine($"{result.Title} {result.Url}");
import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/search/web",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "latest developments in retrieval augmented generation",
        "maxResults": 10,
        "contentFormat": "passage",
        "maxLength": 3000,
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

将此示例另存为 search.mjs,并使用 node search.mjs 运行它。

const response = await fetch("https://api.microsoft.ai/v3/search/web", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "latest developments in retrieval augmented generation",
    maxResults: 10,
    contentFormat: "passage",
    maxLength: 3000,
  }),
});

if (!response.ok) {
  throw new Error(`Web Search failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

3. 了解响应

成功的 Web 搜索返回 webResults 数组。 此简略示例显示最常使用的字段:

{
  "webResults": [
    {
      "title": "Example result",
      "url": "https://example.com/article",
      "content": "The query-relevant passage extracted from the page...",
      "crawledAt": "2026-07-18T12:00:00Z"
    }
  ],
  "traceId": "00000000000000000000000000000000"
}
  • title 和 url 识别来源。
  • content 包含与查询相关的段落,因为该请求使用了 contentFormat: "passage"。
  • traceId 帮助 Web IQ 支持调查某个请求。

在 REST 响应和 MCP 工具结果中,省略具有 null 或空字符串("")值的模型字段,包括嵌套结果对象的字段;空列表/数组([])字段保留在 Places 中,其中列表字段也可以不存在。 将缺席字段视为不可用,将空或缺席列表视为没有项目。 保留仅包含空格的字符串、空字典、false、0、单独的数组/字典条目和嵌入的原始 JSON。 根数组和协议信封集合(如 MCP content )保持不变。

有关所有参数和响应字段,请参阅 Web 搜索 API 参考 。

4.选择终结点

从...开始 Use 您将获得的内容
问题或搜索查询 Web 搜索 具有与查询相关内容的排名靠前的页面
特定 URL 浏览 从该页中提取的内容
地点或本地业务查询 地点 结构化地点详细信息,如地址和营业时间
需要自动选择答案类型的查询 通过 REST 或 SDK 1.2.1 及更高版本自动 带有结果范围引文的类型化证据

通用地面工作流使用这两个终结点:搜索相关源,选择结果 URL,然后浏览该 URL 以提取与后续问题相关的段落。

5. 从 URL 中提取内容

当您已经知道要阅读哪个页面时,使用“浏览”。 passage设置为contentFormat并提供非空白query,以检索与问题最相关的页面部分。

liveCrawl: "fallback" 请求 Web IQ 在索引中尚不可用时抓取该页面。 实时爬网受发布方限制抓取频率的规则和可用性的约束;fallback 不保证会发生实际抓取行为。

所有示例都请求以查询为中心的段落,这是用于提供依据的推荐格式。 所选内容 query 必须是非空白且不超过 1000 个字符; maxLength 单独控制返回的内容量。 完整文档格式(text、html和markdown)需要完全的文档访问权限。

终结点:POST https://api.microsoft.ai/v3/browse

curl --request POST "https://api.microsoft.ai/v3/browse" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    "query": "How fast is Web IQ",
    "contentFormat": "passage",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

安装 SDK(python -m pip install webiq==1.2.1Python 3.11 或更高版本),然后运行:

import os
from webiq import WebIQClient
from webiq.types import BrowseContentFormat

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    page = client.browse.fetch(
        "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
        query="How fast is Web IQ",
        content_format=BrowseContentFormat.passage,
        max_length=3000,
        live_crawl="fallback",
    )
    print(page.content)

使用 npm install @microsoft/webiq@1.2.1 安装 SDK(22.x 需 Node.js 22.18 或更高版本,或 24+)。 将此示例另存为 browse.mts,并使用 node browse.mts 运行它。

import { WebIQClient, BrowseContentFormat, LiveCrawlMode } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const page = await client.browse.fetch(
      "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
      {
        query: "How fast is Web IQ",
        contentFormat: BrowseContentFormat.PASSAGE,
        maxLength: 3000,
        liveCrawl: LiveCrawlMode.FALLBACK,
      },
    );
    console.log(JSON.stringify(page, null, 2));
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

在 Rust 1.88 或更高版本的项目中,运行 cargo add tokio --features macros,rt-multi-thread 和 cargo add webiq@1.2.1。 将此示例保存为 src/main.rs 并运行 cargo run。

use webiq::{BrowseContentFormat, BrowseOptions, LiveCrawlMode, WebIqClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let page = client.browse().fetch(
        "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
        BrowseOptions::new()
            .query("How fast is Web IQ")
            .content_format(BrowseContentFormat::Passage)
            .max_length(3000)
            .live_crawl(LiveCrawlMode::Fallback),
    ).await?;
    println!("{}", page.content.unwrap_or_default());
    Ok(())
}

在为 Java 11 或更高版本配置的 Maven 项目中,将此依赖项添加到pom.xml:

<dependency>
    <groupId>com.microsoft.webiq</groupId>
    <artifactId>webiq</artifactId>
    <version>1.2.1</version>
</dependency>

将此示例保存为 src/main/java/Browse.java 并运行 mvn compile exec:java -Dexec.mainClass=Browse。

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.BrowseContentFormat;
import com.microsoft.webiq.models.BrowseResponse;
import com.microsoft.webiq.models.LiveCrawlMode;
import com.microsoft.webiq.resources.BrowseFetchOptions;

public class Browse {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            BrowseResponse page = client.browse.fetch(
                    "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
                    BrowseFetchOptions.builder()
                            .query("How fast is Web IQ")
                            .contentFormat(BrowseContentFormat.PASSAGE)
                            .maxLength(3000)
                            .liveCrawl(LiveCrawlMode.FALLBACK)
                            .build());
            System.out.println(page.getContent());
        }
    }
}

在 .NET 8 或更高版本的控制台项目中,运行 dotnet add package Microsoft.WebIQ --version 1.2.1。 将此示例保存为 Program.cs 并运行 dotnet run。

using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var page = await client.Browse.FetchAsync(
    "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    request =>
    {
        request.ContentFormat = BrowseContentFormat.Passage;
        request.Query = "How fast is Web IQ";
        request.MaxLength = 3000;
        request.LiveCrawl = LiveCrawlMode.Fallback;
    });
Console.WriteLine(page.Content);
import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/browse",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
        "query": "How fast is Web IQ",
        "contentFormat": "passage",
        "maxLength": 3000,
        "liveCrawl": "fallback",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

将此示例另存为 browse.mjs,并使用 node browse.mjs 运行它。

const response = await fetch("https://api.microsoft.ai/v3/browse", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    query: "How fast is Web IQ",
    contentFormat: "passage",
    maxLength: 3000,
    liveCrawl: "fallback",
  }),
});

if (!response.ok) {
  throw new Error(`Browse failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

成功的 200 响应包括页面 url、title、提取的 content 和一个 traceId。 实时爬网可以返回带有 retryAfter 的 202,即 ISO 8601 UTC 时间戳;等到该时间,然后再次发送相同的请求。 有关完整的响应约定,请参阅 浏览 API 参考。

6. 搜索地点(可选)

使用“地点搜索”获取有关本地企业和其他地点的结构化信息。 SDK 示例使用步骤 2 中安装的 1.2.1 包。

终结点:POST https://api.microsoft.ai/v3/search/places

curl --request POST "https://api.microsoft.ai/v3/search/places" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "coffee in Seattle",
    "maxResults": 5,
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321"
  }'
import os
from webiq import WebIQClient

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    places = client.places.search(
        "coffee in Seattle",
        max_results=5,
        language="en",
        region="US",
        location="lat:47.6062;long:-122.3321",
    )
    for place in places.placeResults or []:
        print(place.name, place.businessUrl)

将此示例另存为 places.mts,并使用 node places.mts 运行它。

import { WebIQClient } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const places = await client.places.search("coffee in Seattle", {
      maxResults: 5,
      language: "en",
      region: "US",
      location: "lat:47.6062;long:-122.3321",
    });
    for (const place of places.placeResults ?? []) {
      console.log(place.name, place.businessUrl);
    }
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

使用步骤 2 中的 Tokio 设置。 将此示例保存为 src/main.rs 并运行 cargo run。

use webiq::{PlacesSearchOptions, WebIqClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let places = client.places().search(
        "coffee in Seattle",
        PlacesSearchOptions::new()
            .max_results(5)
            .language("en")
            .region("US")
            .location("lat:47.6062;long:-122.3321"),
    ).await?;
    for place in places.place_results.unwrap_or_default() {
        println!("{:?} {:?}", place.name, place.business_url);
    }
    Ok(())
}

在步骤 2 的 Maven 项目中,将此示例保存为 src/main/java/Places.java,并运行 mvn compile exec:java -Dexec.mainClass=Places。

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.PlaceItem;
import com.microsoft.webiq.models.PlacesResponse;
import com.microsoft.webiq.resources.PlacesSearchOptions;

public class Places {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            PlacesResponse places = client.places.search("coffee in Seattle",
                    PlacesSearchOptions.builder().maxResults(5)
                            .language("en").region("US")
                            .location("lat:47.6062;long:-122.3321").build());
            if (places.getPlaceResults() != null) {
                for (PlaceItem place : places.getPlaceResults()) {
                    System.out.println(place.getName() + " " + place.getBusinessUrl());
                }
            }
        }
    }
}

在步骤 2 的 .NET 控制台项目中,将此示例另存为Program.cs并运行dotnet run。

using Microsoft.WebIQ;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var places = await client.Places.SearchAsync("coffee in Seattle", request =>
{
    request.MaxResults = 5;
    request.Language = "en";
    request.Region = "US";
    request.Location = "lat:47.6062;long:-122.3321";
});
foreach (var place in places.PlaceResults ?? [])
    Console.WriteLine($"{place.Name} {place.BusinessUrl}");
import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/search/places",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "coffee in Seattle",
        "maxResults": 5,
        "language": "en",
        "region": "US",
        "location": "lat:47.6062;long:-122.3321",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

将此示例另存为 places.mjs,并使用 node places.mjs 运行它。

const response = await fetch("https://api.microsoft.ai/v3/search/places", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "coffee in Seattle",
    maxResults: 5,
    language: "en",
    region: "US",
    location: "lat:47.6062;long:-122.3321",
  }),
});

if (!response.ok) {
  throw new Error(`Places failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

从 placeResults中读取结果。 列表和单个字段可以不存在,因此在使用地址、营业时间或其他详细信息之前检查缺失值。 请参阅 Places API 参考。

7. 使用 Auto 检索证据

当希望 Web IQ 选择检索源并返回带有支持引文的类型化证据时,请使用“自动”。 提出完整的自然语言问题,保留相关约束,如日期、位置和单位。 这些示例省略了 mode,以使用默认值,并允许每个请求尝试 60 秒。 如果您在处理复杂问题时需要更全面的检索,请将 mode 设置为 advanced,以用于 Auto Advanced。

自动返回供你的应用程序使用的证据,而不是生成的最终答案。 阅读每个证据结果时查看其各自的引文;不要将一个结果中的引文视为对另一个结果的支持。 SDK 示例使用步骤 2 中安装的所有五个 SDK 的版本 1.2.1。

终结点:POST https://api.microsoft.ai/v3/auto

curl --request POST "https://api.microsoft.ai/v3/auto" \
  --max-time 60 \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "What are the latest developments in retrieval-augmented generation?",
    "maxResponseLength": 30000,
    "maxCitations": 5
  }'
import os
from webiq import WebIQClient

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    evidence = client.auto.search(
        "What are the latest developments in retrieval-augmented generation?",
        max_response_length=30000,
        max_citations=5,
        timeout=60.0,
    )
    for result in evidence.results or []:
        print(result.evidence)
        for citation in result.citations or []:
            print(citation.title, citation.url)

将此示例另存为 auto.mts,并使用 node auto.mts 运行它。

import { WebIQClient } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const evidence = await client.auto.search(
      "What are the latest developments in retrieval-augmented generation?",
      { maxResponseLength: 30000, maxCitations: 5, timeout: 60_000 },
    );
    for (const result of evidence.results ?? []) {
      console.log(result.evidence);
      for (const citation of result.citations ?? []) {
        console.log(citation.title, citation.url);
      }
    }
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

使用步骤 2 中的 Tokio 设置。 将此示例保存为 src/main.rs 并运行 cargo run。

use webiq::{AutoSearchOptions, WebIqClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let evidence = client.auto().search(
        "What are the latest developments in retrieval-augmented generation?",
        AutoSearchOptions::new()
            .max_response_length(30000)
            .max_citations(5)
            .timeout(std::time::Duration::from_secs(60)),
    ).await?;
    for result in evidence.results.unwrap_or_default() {
        println!("{:?}", result.evidence);
        for citation in result.citations.unwrap_or_default() {
            println!("{:?} {:?}", citation.title, citation.url);
        }
    }
    Ok(())
}

在步骤 2 的 Maven 项目中,将此示例保存为 src/main/java/Auto.java,并运行 mvn compile exec:java -Dexec.mainClass=Auto。

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.AutoEvidenceCitation;
import com.microsoft.webiq.models.AutoEvidenceResult;
import com.microsoft.webiq.models.SearchAutoEvidenceResponse;
import com.microsoft.webiq.resources.AutoSearchOptions;

public class Auto {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            SearchAutoEvidenceResponse evidence = client.auto.search(
                    "What are the latest developments in retrieval-augmented generation?",
                    AutoSearchOptions.builder()
                            .maxResponseLength(30000).maxCitations(5)
                            .timeout(java.time.Duration.ofSeconds(60)).build());
            if (evidence.getResults() != null) {
                for (AutoEvidenceResult result : evidence.getResults()) {
                    System.out.println(result.getEvidence());
                    if (result.getCitations() != null) {
                        for (AutoEvidenceCitation citation : result.getCitations()) {
                            System.out.println(citation.getTitle() + " " + citation.getUrl());
                        }
                    }
                }
            }
        }
    }
}

在步骤 2 的 .NET 控制台项目中,将此示例另存为Program.cs并运行dotnet run。

using Microsoft.WebIQ;
using System.Text.Json;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var evidence = await client.Auto.SearchAsync(
    "What are the latest developments in retrieval-augmented generation?",
    request =>
    {
        request.MaxResponseLength = 30000;
        request.MaxCitations = 5;
    }, timeout: TimeSpan.FromSeconds(60));
foreach (var result in evidence.Results ?? [])
{
    Console.WriteLine(JsonSerializer.Serialize(result.Evidence));
    foreach (var citation in result.Citations ?? [])
        Console.WriteLine($"{citation.Title} {citation.Url}");
}
import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/auto",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "What are the latest developments in retrieval-augmented generation?",
        "maxResponseLength": 30000,
        "maxCitations": 5,
    },
    timeout=60,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

将此示例另存为 auto.mjs,并使用 node auto.mjs 运行它。

const response = await fetch("https://api.microsoft.ai/v3/auto", {
  method: "POST",
  signal: AbortSignal.timeout(60_000),
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "What are the latest developments in retrieval-augmented generation?",
    maxResponseLength: 30000,
    maxCitations: 5,
  }),
});

if (!response.ok) {
  throw new Error(`Auto failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

成功的响应包含一个 results 数组。 每个结果都将一个类型化的evidence对象与其支持的citations配对。 空的或缺失的 results 数组没有要处理的证据。 有关证据类型、响应示例和请求限制,请参阅 Auto API reference。

Troubleshooting

Status 需要检查的事项
401 Unauthorized 确认 WEBIQ_API_KEY 已设置,请求在 x-apikey 标头中发送它。
415 Unsupported Media Type 发送 content-type: application/json。
429 Too Many Requests 重试前请等待,并降低请求频率。
浏览 404 Not Found 确认该 URL 可公开访问且有效。 当索引内容可能不可用时使用 liveCrawl: "fallback" 。
浏览 202 Accepted 等待直到 retryAfter 中的时间(ISO 8601 UTC 时间戳),然后再次发送相同的请求。
自动 403 Forbidden 检查是否在配置文件管理中的允许的服务下列出了 Auto。 如果不是,请使用 AppID 打开 Web IQ 支持请求 。

对于其他失败,请保存 traceId 并查看 错误处理。 若要联系 Web IQ 支持部门,请提供 traceId 和您的 AppID;如果您没有 AppID,请提供您的公司名称和 Web IQ 资源名称。

后续步骤