阿里云信息查询服务（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 或X-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：

进入阿里云百炼控制台，选择「组件管理」
创建自定义插件，插件名称填写为「信息查询服务」
插件描述填写为「信息查询服务是一个强大的实时搜索API，可提供来自多种搜索引擎、知识库集合的结构化数据」
插件URL填写为 https://cloud-iqs.aliyuncs.com/search
开启「是否鉴权」开关，鉴权类型选择「服务级鉴权」，位置选择「Header」，Type选择「bearer」
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的实时搜索功能，为模型提供联网搜索能力。关键步骤包括：

部署LLM模型服务（如通过EAS部署DeepSeek-R1）
开通阿里云信息查询服务
在LangStudio中创建LLM服务连接
创建运行时（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个字符以内。可以一个查询改写为多个查询分别进行，以提升召回效果。

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

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

2. 服务开通与前置准备

2.1 注册与实名认证

2.2 开通服务

2.3 获取访问凭证

3. HTTP API调用方式

3.1 通用搜索（UnifiedSearch）

3.2 多阶段流式搜索（AiSearch）

3.3 增强搜索（GenericAdvancedSearch）

3.4 网页解析

4. SDK调用方式

4.1 安装SDK

4.2 同步调用示例

4.3 异步调用示例

5. Agent平台集成

5.1 阿里云百炼集成

5.2 PAI LangStudio集成

5.3 Dify集成

6. CLI工具使用

7. 性能优化与最佳实践

7.1 搜索引擎类型选择

7.2 分页与结果数量控制

7.3 查询词优化

7.4 索引更新时效性

8. 常见问题与故障排查

8.1 认证相关错误

8.2 试用账号与正式账号

8.3 内网访问

8.4 计费与配额

9. 总结

Q&A

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

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

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

2. 服务开通与前置准备

2.1 注册与实名认证

2.2 开通服务

2.3 获取访问凭证

3. HTTP API调用方式

3.1 通用搜索（UnifiedSearch）

3.2 多阶段流式搜索（AiSearch）

3.3 增强搜索（GenericAdvancedSearch）

3.4 网页解析

4. SDK调用方式

4.1 安装SDK

4.2 同步调用示例

4.3 异步调用示例

5. Agent平台集成

5.1 阿里云百炼集成

5.2 PAI LangStudio集成

5.3 Dify集成

6. CLI工具使用

7. 性能优化与最佳实践

7.1 搜索引擎类型选择

7.2 分页与结果数量控制

7.3 查询词优化

7.4 索引更新时效性

8. 常见问题与故障排查

8.1 认证相关错误

8.2 试用账号与正式账号

8.3 内网访问

8.4 计费与配额

9. 总结

Q&A

热门文章

最新文章

相关电子书