阿里云信息查询服务（IQS）对接完全指南：从开通到生产级集成

1. 认识阿里云信息查询服务

阿里云信息查询服务（Information Query Service，简称IQS）是专为AI大模型设计的开放域搜索解决方案，整合了多维数据源，提供毫秒级响应和智能优化的搜索接口。该服务专注服务于大模型的业务查询能力，提供大模型「可理解数据源」和「应用连接器」。简单来说，IQS让大模型应用能够实时获取互联网信息，从而提升问答系统的时效性与准确性，显著降低开发与调优成本。

IQS的核心能力包括通用搜索、多阶段流式搜索、增强搜索、网页解析、医疗问答等多种API。其中通用搜索是基础能力，通过统一搜索接口即可快速接入全网搜索能力。对于需要更高权威性的场景，还可以使用增强搜索（GenericAdvancedSearch），该接口在权威网站召回方面表现更优，最大召回数量可达40条。

需要先登录阿里云控制台，点击：阿里云控制台

2. 服务开通与前置准备

2.1 注册与实名认证

使用IQS服务的第一步是注册阿里云账号并完成实名认证。企业账号需要按照企业账号快速入门完成相关认证流程。建议使用主账号开通服务，后续再通过RAM子账号进行日常调用管理。

2.2 开通服务

登录IQS控制台，点击「免费试用」按钮开通服务。开通后自动获得免费测试额度，5分钟后即可开始试用。需要注意的是，首次使用夸克联网搜索时，默认服务状态为未开通状态，需要单击「前往开通」跳转至服务开通页面进行操作。

开通成功后，新购实例一般需要1到5分钟完成生产，之后即可进入管理控制台进行配置。

2.3 获取访问凭证

IQS提供两种认证方式，开发者可以根据接入方式选择：

• API-KEY方式：适用于HTTP API调用和MCP Skill接入。在IQS控制台的「凭证管理」页面单击「创建API Key」，输入凭证所关联的调用方标识，系统即可生成一个新凭证。调用时在HTTP Header中携带Authorization: Bearer <API-KEY>或X-API-Key: <API-KEY>即可。
• AccessKey（AK/SK）方式：适用于SDK调用。在RAM访问控制台创建AccessKey，获取AccessKey ID和AccessKey Secret。建议使用RAM子账号的AccessKey进行API调用或日常运维。

3. HTTP API调用方式

IQS的HTTP API采用RESTful风格，服务端点为 https://cloud-iqs.aliyuncs.com。以下是几种常用API的调用示例。

3.1 通用搜索（UnifiedSearch）

通用搜索是最基础的搜索接口，通过POST请求调用 /search/unified 路径。以下是一个完整的cURL示例：

curl -X POST https://cloud-iqs.aliyuncs.com/search/unified \\n  --header "Authorization: Bearer $API_KEY" \\n  --header "Content-Type: application/json" \\n  --data '{
    "query": "杭州美食",
    "engineType": "LiteAdvanced",
    "contents": {
      "mainText": true,
      "markdownText": false,
      "summary": false,
      "rerankScore": true
    },
    "advancedParams": {
      "numResults": 5
    }
  }'

请求参数说明：

• query：必填，搜索查询语句
• engineType：选填，搜索引擎类型，可选值包括LiteAdvanced、GenericAdvanced等
• contents：控制返回内容的结构，包括是否返回正文、摘要、重排序分数等
• advancedParams.numResults：控制返回结果数量

3.2 多阶段流式搜索（AiSearch）

对于需要更高质量搜索结果的场景，可以使用多阶段流式API。该接口提供 common_search 和 post_retrieval 两个阶段：

• common_search：搜索的原始结果，覆盖网页标题、动态摘要、正文、来源网站、发布时间等关键字段
• post_retrieval：通过rerank模型对上一阶段结果进行重排序与过滤，相关性mAP指标提升约5%，时延增加约110ms

该API采用GET方式调用，服务地址为华北3（张家口）。请求语法为：

GET /linked-retrieval/linked-retrieval-entry/v3/linkedRetrieval/commands/aiSearch?querystring={query}&timeRange={range}&page={page} HTTP/1.1

3.3 增强搜索（GenericAdvancedSearch）

相比通用搜索，增强搜索在权威网站召回方面表现更优，最大召回数量可达40条，提供更好的权威性和数据多样性。该接口的响应参数和格式与通用搜索保持一致。通过CLI工具调用的方式为：

aliyun iqs generic-advanced-search --querystring "苹果手机" --timeRange OneWeek

3.4 网页解析

IQS还提供了网页解析能力，可以快速抓取并解析指定URL的页面内容：

curl --location 'https://cloud-iqs.aliyuncs.com/readpage/basic' \\n  --header "Authorization: Bearer $API_KEY" \\n  --header 'Content-Type: application/json' \\n  --data '{
    "url": "https://help.aliyun.com/document_detail/2837301.html",
    "maxAge": 0
  }'

此外还有 read-page-scrape 接口，通过浏览器沙箱环境解析网页，在所有资源完全加载后开始解析。该接口的整体耗时受目标站点资源加载性能的显著影响。

4. SDK调用方式

阿里云为IQS提供了官方SDK，支持Python、Java、Node.js等多种语言。以下以Python SDK为例进行详细说明。

4.1 安装SDK

pip3 install alibabacloud_iqs20241111==1.7.3

4.2 同步调用示例

以下是一个完整的同步调用示例：

import os
from Tea.exceptions import TeaException
from alibabacloud_iqs20241111 import models
from alibabacloud_iqs20241111.client import Client
from alibabacloud_tea_openapi import models as open_api_models

class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> Client:
        config = open_api_models.Config(
            # 建议从环境变量加载凭证
            access_key_id='$YOUR_ACCESS_KEY',
            access_key_secret='$YOUR_ACCESS_SECRET'
        )
        config.endpoint = 'iqs.cn-zhangjiakou.aliyuncs.com'
        return Client(config)

    @staticmethod
    def main() -> None:
        client = Sample.create_client()
        
        advanced_params = {
            "startPublishedDate": "2025-10-01",
            "endPublishedDate": "2025-10-10"
        }
        
        request = models.UnifiedSearchRequest(
            body=models.UnifiedSearchInput(
                query='杭州美食',
                time_range='NoLimit',
                contents=models.RequestContents(
                    summary=False,
                    main_text=True
                ),
                advanced_params=advanced_params
            )
        )
        
        try:
            response = client.unified_search(request)
            print(f"请求成功，request_id: {response.body.request_id}")
            print(f"结果数量: {len(response.body.page_items)}")
            print(f"搜索耗时: {response.body.search_information.search_time}")
            
            for index, item in enumerate(response.body.page_items):
                print(f"{index}. {'-' * 20}")
                print(f"标题: {item.title}")
                print(f"摘要: {item.snippet}")
                print(f"发布时间: {item.published_time}")
                print(f"链接: {item.link}")
        except TeaException as e:
            request_id = e.data.get("requestId")
            message = e.data.get("message")
            print(f"API异常，requestId: {request_id}, code: {e.code}, message: {message}")

4.3 异步调用示例

对于高并发场景，可以使用异步调用方式：

import asyncio
from Tea.exceptions import TeaException
from alibabacloud_iqs20241111 import models
from alibabacloud_iqs20241111.client import Client
from alibabacloud_tea_openapi import models as open_api_models

class AsyncSample:
    @staticmethod
    def create_client() -> Client:
        config = open_api_models.Config(
            access_key_id='$YOUR_ACCESS_KEY',
            access_key_secret='$YOUR_ACCESS_SECRET'
        )
        config.endpoint = 'iqs.cn-zhangjiakou.aliyuncs.com'
        return Client(config)

    @staticmethod
    async def async_search():
        client = AsyncSample.create_client()
        request = models.UnifiedSearchRequest(
            body=models.UnifiedSearchInput(
                query='人工智能最新进展',
                time_range='OneWeek'
            )
        )
        try:
            response = await client.unified_search_async(request)
            return response
        except TeaException as e:
            print(f"异步调用异常: {e}")
            return None

5. Agent平台集成

IQS提供了与主流Agent平台的深度集成能力，开发者可以在阿里云百炼、PAI LangStudio、Dify等平台中快速配置和使用。

5.1 阿里云百炼集成

在阿里云百炼控制台中，可以通过创建自定义插件的方式集成IQS：

1. 进入阿里云百炼控制台，选择「组件管理」
2. 创建自定义插件，插件名称填写为「信息查询服务」
3. 插件描述填写为「信息查询服务是一个强大的实时搜索API，可提供来自多种搜索引擎、知识库集合的结构化数据」
4. 插件URL填写为 https://cloud-iqs.aliyuncs.com/search
5. 开启「是否鉴权」开关，鉴权类型选择「服务级鉴权」，位置选择「Header」，Type选择「bearer」
6. Token字段填写您的IQS API Key

然后参考联网搜索API创建工具：

• 工具名称：common-search
• 工具路径：https://cloud-iqs.aliyuncs.com/search/unified
• 输入参数：query为必填查询语句，engineType为选填搜索引擎类型
• 请求方法：POST，Content-Type为application/json

测试完成后发布插件，即可在百炼应用中使用。在应用配置页面的技能区域，单击插件右侧的+按钮添加所需插件。在应用调试界面单击「入参变量配置」，找到common-search插件的engineType字段，填入 GenericAdvanced 后确认。

5.2 PAI LangStudio集成

PAI LangStudio是阿里云专为开发者打造的一站式机器学习平台，通过直观的交互式环境简化企业级大模型应用的开发流程。

开发者可以参考《基于LangStudio&阿里云信息查询服务搭建DeepSeek联网搜索应用流》文档，快速构建具备联网搜索能力的Agent。该应用流通过集成IQS的实时搜索功能，为模型提供联网搜索能力。关键步骤包括：

1. 部署LLM模型服务（如通过EAS部署DeepSeek-R1）
2. 开通阿里云信息查询服务
3. 在LangStudio中创建LLM服务连接
4. 创建运行时（PAI-DSW实例）提供运行环境

需要注意的是，如果使用PAI默认角色，需要通过api_key使用IQS联网搜索功能（经公网，数据安全性较低），推荐选择自定义角色。

5.3 Dify集成

在Dify中集成IQS有两种方式：

方式一：自定义工具

使用OpenAPI Specification中的API定义创建自定义工具。单击「创建自定义工具」，在弹窗中填写工具名称，在Schema区域粘贴OpenAPI 3.1.0格式的JSON定义。鉴权方法选择API Key，鉴权头部前缀选择Custom，Key填写 X-API-Key，Value填写对应的API密钥。在自定义工具列表中选择目标工具，填写参数（如query）后单击测试，即可返回JSON格式的结构化搜索结果。

方式二：工作流

在Dify工作流中直接调用IQS的HTTP API节点，配置相应的认证信息和请求参数。

6. CLI工具使用

阿里云CLI工具提供了对IQS服务的命令行支持，适合快速测试和脚本化调用。安装并配置好阿里云CLI后，可以使用以下命令：

• aliyun iqs unified-search：通晓统一搜索API
• aliyun iqs generic-search：通用搜索
• aliyun iqs generic-advanced-search：增强搜索
• aliyun iqs ai-search：多阶段流式搜索V3
• aliyun iqs multimodal-search：多模态搜索
• aliyun iqs medical-answer：医疗问答
• aliyun iqs read-page-basic：快速网页解析
• aliyun iqs read-page-scrape：完整网页解析
• aliyun iqs get-iqs-usage：查询每日用量

CLI工具的使用方式与OpenAPI SDK保持一致，适合在自动化脚本和CI/CD流程中集成。

7. 性能优化与最佳实践

7.1 搜索引擎类型选择

IQS提供了多种搜索引擎类型：

• LiteAdvanced：轻量级增强版，适合大多数通用搜索场景
• GenericAdvanced：增强版，提供更好的权威网站召回
• 不同的引擎类型在召回数量、响应时间和结果质量上有所差异，开发者应根据业务场景选择

7.2 分页与结果数量控制

搜索结果支持通过 page 参数进行分页。每页结果数量不可调整，如果需要获取更多结果，可以通过多次API调用并递增 page 参数来实现。

需要注意的是，返回结果有时可能多于或少于10条：

• 少于10条：部分召回站点被过滤，或rerank过程移除了相关性评分低于0.3的站点
• 多于10条：当召回新闻卡片（news_uchq）时，单个卡片包含10条结果，展开后总数可达19条

7.3 查询词优化

开放域搜索引擎针对关键词搜索进行了优化，长查询会降低搜索精度。最佳实践包括：

• 使用模型将复杂问题改写为1到4个关键词
• 将一个查询改写为多个查询分别进行
• 保持查询长度在15个字符以内，以提升响应时间和相关性

7.4 索引更新时效性

网页的更新频率各不相同：

• 大多数页面每日更新
• 新闻资讯页面每隔几分钟更新
• 热门话题通过垂直API（SceneItem）检索
• 部分页面仅每周或每月更新

8. 常见问题与故障排查

8.1 认证相关错误

当运行Python示例代码时遇到 AttributeError: 'NoneType' object has no attribute 'get_credential' 错误，是因为配置中的 access_key_id 或 access_key_secret 为空，请确保环境变量正确设置。

遇到 [SSL: CERTIFICATE_VERIFY_FAILED] 错误，是因为本地SSL证书过期，可以删除旧证书并重新安装最新版本的 certifi 包。

8.2 试用账号与正式账号

下单后控制台显示「激活中」状态是正常现象。下单后默认激活15天试用账号，控制台显示的是正式账号状态而非试用账号状态。在此期间可以正常调用API进行测试。如需转为正式账号，可通过信息查询服务控制台「开通正式」按钮提交申请，默认1工作日完成开通。

8.3 内网访问

如果客户端部署在阿里云VPC内，可以使用VPC终端节点访问服务。这可以显著降低网络延迟并提高安全性。

8.4 计费与配额

IQS提供15天免费试用，每日调用上限1000次，性能限制为5 QPS。正式账号的配额和计费方式可通过控制台「账单」页面查看。搜索接口的响应时间受功能配置、机房位置、查询长度等因素影响。开发者应合理规划资源使用，关注QPS规格与限流机制。

9. 总结

阿里云信息查询服务为AI大模型应用提供了强大的联网搜索能力。通过本文的介绍，开发者可以从零开始完成服务开通、凭证获取、API调用、SDK集成以及主流Agent平台的配置。无论是简单的HTTP API调用，还是复杂的Agent平台集成，IQS都提供了完善的工具链和支持文档。

在实际生产中，建议开发者根据业务场景选择合适的搜索引擎类型，优化查询词策略，合理利用分页机制，并关注试用账号到正式账号的转换流程。通过合理的性能优化和成本管理，IQS可以成为大模型应用中不可或缺的数据源组件。

Q&A

Q1：IQS支持哪些认证方式？

IQS提供两种认证方式：API-KEY方式适用于HTTP API调用和MCP Skill接入，在控制台创建API Key后在Header中携带Authorization: Bearer 即可；AccessKey方式适用于SDK调用，在RAM控制台创建AccessKey后配置到SDK中。

Q2：如何获取更多的搜索结果？

通过page参数进行分页获取。每页结果数量固定，需要多次调用API并递增page参数。也可以使用增强搜索（GenericAdvancedSearch），最大召回数量可达40条。

Q3：试用账号和正式账号有什么区别？

开通服务后默认激活15天试用账号，每日调用上限1000次，QPS限制为5。试用期间控制台显示的是正式账号状态而非试用账号状态。如需转为正式账号，可通过控制台提交申请。

Q4：Python SDK调用时报错AttributeError怎么办？

该错误通常是因为access_key_id或access_key_secret配置为空。请检查环境变量是否正确设置，或直接在代码中填入正确的AccessKey（生产环境建议从环境变量加载）。

Q5：IQS可以在VPC内网访问吗？

可以。如果客户端部署在阿里云VPC内，可以使用VPC终端节点访问服务，这样可以显著降低网络延迟并提高安全性。

Q6：查询词有什么优化建议？

开放域搜索引擎针对关键词优化，建议将复杂问题改写为1到4个关键词，保持查询长度在15个字符以内。可以一个查询改写为多个查询分别进行，以提升召回效果。