path: root/data/zh_cn/maasaisearchproxy/2026-04-24/api-docs.php

<?php return [
    'version' => '1.0',
    'info' => ['style' => 'ROA', 'product' => 'MaasAISearchProxy', 'version' => '2026-04-24'],
    'directories' => ['QaChat', 'WebSearch'],
    'components' => [
        'schemas' => [],
    ],
    'apis' => [
        'QaChat' => [
            'summary' => '联网问答（OpenAI 兼容，支持多轮上下文与追问推荐，SSE 流式 / JSON 非流式）',
            'path' => '/qa/chat',
            'methods' => ['post'],
            'schemes' => ['https', 'sse'],
            'security' => [
                [
                    'AK' => [],
                ],
                [
                    'ApiKey' => [],
                ],
            ],
            'consumes' => ['application/json'],
            'produces' => ['text/event-stream', 'application/json'],
            'operationType' => 'write',
            'deprecated' => false,
            'systemTags' => ['operationType' => 'none', 'riskType' => 'none', 'chargeType' => 'free', 'autoTest' => true, 'tenantRelevance' => 'publicInformation'],
            'parameters' => [
                [
                    'name' => 'body',
                    'in' => 'body',
                    'style' => 'json',
                    'schema' => [
                        'title' => '请求体参数',
                        'description' => '请求体参数',
                        'type' => 'object',
                        'properties' => [
                            'appId' => ['title' => '应用 ID', 'description' => '应用 ID', 'type' => 'string', 'required' => false, 'example' => '2052929167853146113'],
                            'sessionId' => ['title' => '会话 ID', 'description' => '会话 ID', 'type' => 'string', 'required' => false, 'example' => 'chat-abc123'],
                            'message' => [
                                'title' => '用户消息',
                                'description' => '用户消息',
                                'type' => 'object',
                                'properties' => [
                                    'role' => [
                                        'title' => '消息角色',
                                        'description' => '消息角色',
                                        'type' => 'string',
                                        'required' => false,
                                        'example' => 'user',
                                        'enum' => ['user'],
                                    ],
                                    'parts' => [
                                        'title' => '消息内容',
                                        'description' => '消息内容',
                                        'type' => 'array',
                                        'items' => [
                                            'title' => '内容块',
                                            'description' => '内容块',
                                            'type' => 'object',
                                            'properties' => [
                                                'type' => [
                                                    'title' => '内容块类型',
                                                    'description' => '内容块类型',
                                                    'type' => 'string',
                                                    'required' => false,
                                                    'example' => 'text',
                                                    'enum' => ['text', 'file'],
                                                ],
                                                'text' => ['title' => '文本内容', 'description' => '文本内容', 'type' => 'string', 'required' => false, 'example' => '今天杭州天气怎么样？'],
                                                'url' => ['title' => '图片地址', 'description' => '图片地址', 'type' => 'string', 'required' => false, 'example' => 'https://example.com/img.jpg'],
                                                'mediaType' => ['title' => '媒体类型', 'description' => '媒体类型', 'type' => 'string', 'required' => false, 'example' => 'image/jpeg'],
                                            ],
                                            'required' => false,
                                        ],
                                        'required' => false,
                                    ],
                                ],
                                'required' => false,
                            ],
                            'stream' => ['title' => '是否流式', 'description' => '是否流式', 'type' => 'boolean', 'required' => false, 'example' => 'true'],
                            'options' => [
                                'title' => '业务参数',
                                'description' => '业务参数',
                                'type' => 'object',
                                'properties' => [
                                    'searchMode' => [
                                        'title' => '联网搜索模式',
                                        'description' => '联网搜索模式',
                                        'type' => 'string',
                                        'required' => false,
                                        'example' => 'force',
                                        'enum' => ['force', 'auto'],
                                    ],
                                    'enableRewrite' => ['title' => 'Query 改写', 'description' => 'Query 改写', 'type' => 'boolean', 'required' => false, 'example' => 'true'],
                                    'enableCitation' => ['title' => '引用角标', 'description' => '引用角标', 'type' => 'boolean', 'required' => false, 'example' => 'false'],
                                    'enableFollowUp' => ['title' => '追问推荐', 'description' => '追问推荐', 'type' => 'boolean', 'required' => false, 'example' => 'false'],
                                    'enableImages' => ['title' => '答案图文混排', 'description' => '答案图文混排', 'type' => 'boolean', 'required' => false, 'example' => 'false'],
                                    'followUpPrompt' => ['title' => '追问引导', 'description' => '追问引导', 'type' => 'string', 'required' => false, 'example' => '从旅游攻略和历史文化两个角度推荐追问'],
                                    'systemPrompt' => ['title' => '系统提示词', 'description' => '系统提示词', 'type' => 'string', 'required' => false, 'example' => '你是专业旅游向导，回答简洁，不超过200字，使用中文。'],
                                ],
                                'required' => false,
                            ],
                        ],
                        'required' => false,
                    ],
                ],
            ],
            'responses' => [
                200 => [
                    'schema' => [
                        'type' => 'object',
                        'properties' => [
                            'event' => ['title' => '事件类型（stream=true 时 SSE 单帧 type 字段；与 data.type 一致）：'."\n"
                                ."\n"
                                .'1. 生命周期'."\n"
                                .'   - start / finish'."\n"
                                .'   - 标记消息开始与结束；start 携带 messageId'."\n"
                                ."\n"
                                .'2. 文本内容'."\n"
                                .'   - text-start / text-delta / text-end'."\n"
                                .'   - Markdown 正文流式输出；同一文本块共享 id'."\n"
                                ."\n"
                                .'3. 召回中间结果（仅 action=search）'."\n"
                                .'   - data-recall'."\n"
                                .'   - 去重后召回 items，供前端「思考过程」展示'."\n"
                                ."\n"
                                .'4. 信源引用（仅 action=search）'."\n"
                                .'   - data-reference'."\n"
                                .'   - web 信源列表，items[].sourceType=web'."\n"
                                ."\n"
                                .'5. 追问推荐（enableFollowUp=true 且有结果）'."\n"
                                .'   - data-follow-up'."\n"
                                .'   - questions 数组'."\n"
                                ."\n"
                                .'6. 阶段耗时（所有分支）'."\n"
                                .'   - data-usage'."\n"
                                .'   - qp_ms / recall_rank_ms / first_token_ms / answer_ms / follow_up_ms / grand_total_ms / input_tokens / output_tokens / total_tokens（按分支取舍）'."\n"
                                ."\n"
                                .'7. 异常'."\n"
                                .'   - error（errorText / errorCode / retryable）→ finish(finishReason=error) → [DONE]'."\n"
                                ."\n"
                                .'典型序列：'."\n"
                                .'- search: start → data-recall → text-* → data-reference → [data-follow-up] → data-usage → finish → [DONE]'."\n"
                                .'- answer: start → text-* → [data-follow-up] → data-usage → finish → [DONE]'."\n"
                                .'- clarify: start → text-* → data-usage → finish → [DONE]'."\n"
                                ."\n"
                                .'注：不含 data-qp / data-ranked / data-image-info / data-video-info / json-* 等图文视频模板事件。'."\n", 'description' => '事件类型（stream=true 时 SSE 单帧 type 字段；与 data.type 一致）：'."\n"
                                ."\n"
                                .'1. 生命周期'."\n"
                                .'   - start / finish'."\n"
                                .'   - 标记消息开始与结束；start 携带 messageId'."\n"
                                ."\n"
                                .'2. 文本内容'."\n"
                                .'   - text-start / text-delta / text-end'."\n"
                                .'   - Markdown 正文流式输出；同一文本块共享 id'."\n"
                                ."\n"
                                .'3. 召回中间结果（仅 action=search）'."\n"
                                .'   - data-recall'."\n"
                                .'   - 去重后召回 items，供前端「思考过程」展示'."\n"
                                ."\n"
                                .'4. 信源引用（仅 action=search）'."\n"
                                .'   - data-reference'."\n"
                                .'   - web 信源列表，items[].sourceType=web'."\n"
                                ."\n"
                                .'5. 追问推荐（enableFollowUp=true 且有结果）'."\n"
                                .'   - data-follow-up'."\n"
                                .'   - questions 数组'."\n"
                                ."\n"
                                .'6. 阶段耗时（所有分支）'."\n"
                                .'   - data-usage'."\n"
                                .'   - qp_ms / recall_rank_ms / first_token_ms / answer_ms / follow_up_ms / grand_total_ms / input_tokens / output_tokens / total_tokens（按分支取舍）'."\n"
                                ."\n"
                                .'7. 异常'."\n"
                                .'   - error（errorText / errorCode / retryable）→ finish(finishReason=error) → [DONE]'."\n"
                                ."\n"
                                .'典型序列：'."\n"
                                .'- search: start → data-recall → text-* → data-reference → [data-follow-up] → data-usage → finish → [DONE]'."\n"
                                .'- answer: start → text-* → [data-follow-up] → data-usage → finish → [DONE]'."\n"
                                .'- clarify: start → text-* → data-usage → finish → [DONE]'."\n"
                                ."\n"
                                .'注：不含 data-qp / data-ranked / data-image-info / data-video-info / json-* 等图文视频模板事件。'."\n", 'type' => 'string', 'example' => 'start'],
                            'data' => [
                                'title' => '协议数据',
                                'description' => '协议数据',
                                'type' => 'object',
                                'properties' => [
                                    'type' => ['title' => '事件类型，同event', 'description' => '事件类型，同event', 'type' => 'string', 'example' => 'start'],
                                    'requestId' => ['title' => '请求 ID', 'description' => '请求 ID', 'type' => 'string', 'example' => '2a127bc9-9474-405d-916d-8bc4475fa459'],
                                    'id' => ['title' => '请求 id，同 requestId', 'description' => '请求 id，同 requestId', 'type' => 'string', 'example' => '2a127bc9-9474-405d-916d-8bc4475fa459'],
                                    'delta' => ['title' => '文本增量', 'description' => '文本增量', 'type' => 'string', 'example' => '杭州今天多云，气温 18～25℃。'],
                                    'data' => ['title' => '结构化载荷', 'description' => '结构化载荷', 'type' => 'string', 'example' => '{'."\n"
                                        .'  "items": ['."\n"
                                        .'    {'."\n"
                                        .'      "sourceType": "web",'."\n"
                                        .'      "index": 1,'."\n"
                                        .'      "title": "杭州天气预报",'."\n"
                                        .'      "url": "https://example.com/weather",'."\n"
                                        .'      "snippet": "今日杭州多云...",'."\n"
                                        .'      "score": 0.95,'."\n"
                                        .'      "favicon": "https://example.com/favicon.ico"'."\n"
                                        .'    }'."\n"
                                        .'  ]'."\n"
                                        .'}'."\n"],
                                    'finishReason' => [
                                        'title' => '完成原因',
                                        'description' => '完成原因',
                                        'type' => 'string',
                                        'example' => 'stop',
                                        'enum' => ['stop', 'error'],
                                    ],
                                    'errorCode' => ['title' => '错误码', 'description' => '错误码', 'type' => 'string', 'example' => 'INTERNAL_ERROR'],
                                    'errorText' => ['title' => '错误描述', 'description' => '错误描述', 'type' => 'string', 'example' => '模型服务暂时不可用'],
                                    'retryable' => ['title' => '是否可重试', 'description' => '是否可重试', 'type' => 'boolean', 'example' => 'true'],
                                ],
                            ],
                            'id' => ['title' => '请求 ID', 'description' => '请求 ID', 'type' => 'string', 'example' => '2a127bc9-9474-405d-916d-8bc4475fa459'],
                        ],
                        'description' => 'stream=true（默认）：Content-Type text/event-stream，每帧 data: {json}\\n\\n，结束 data: [DONE]\\n\\n。'."\n"
                            .'下方 schema 对齐 ais-engine 震元出参结构（event + data + id），data 内字段对应 SSE JSON 载荷。'."\n"
                            ."\n"
                            .'stream=false：Content-Type application/json;charset=UTF-8，返回一次性汇总对象（非 event/data/id 包装）：'."\n"
                            .'requestId, messageId, finishReason, content, action,'."\n"
                            .'recall(仅 action=search), references, follow_up, usage；'."\n"
                            .'finishReason=error 时含 error{errorText,errorCode,retryable}。'."\n"
                            .'qp / ranked 内部管线数据不下发。'."\n",
                    ],
                ],
            ],
            'staticInfo' => ['returnType' => 'synchronous'],
            'title' => '联网问答',
            'requestParamsDescription' => '- `sessionId` 与 `message` 为必填参数。`stream` 为可选参数，缺省为 `true`（SSE 流式）；设为 `false` 时返回一次性 JSON 汇总。'."\n"
                .'- 本接口采用 Chat UI 协议：每次请求仅发送当前一条 `message`，多轮历史由服务端按 `sessionId` 管理，**无需在请求体中回传历史消息**。复用同一 `sessionId` 即可续多轮上下文。'."\n"
                .'- `appId` 为可选参数。传入后 proxy 加载控制台已发布策略并合并进 `options`；请求体 `options` 中非 null 字段可覆盖策略值。`appId` 由 proxy 消费，不透传上游。'."\n"
                .'- `message.parts` 中所有 `type=text` 的文本按顺序拼接为当前问题；`type=file` 且 `mediaType` 为 `image/*`（或未声明）时作为图片输入。'."\n"
                .'- 图片 `url` 支持 HTTPS URL、`data:image/*;base64,...` 或裸 base64；单张 base64 不超过 10MB；非 `image/*` 的 file 会被忽略。'."\n"
                .'- ApiKey 调用时 Body 传扁平 JSON，不要外包 `body` 字段。字段统一使用驼峰命名。',
            'responseParamsDescription' => '- 关于响应形态：stream=true（默认）时 Content-Type 为 text/event-stream，以 SSE 逐帧推送，最后一帧为 data: [DONE]；stream=false 时 Content-Type 为 application/json，返回一次性汇总对象。'."\n"
                .'- 关于流式帧结构：SSE 单帧包含 event、data、id 三个顶层字段，data.type 与 event 一致。'."\n"
                .'- 关于 requestId：除 [DONE] 外，每个 SSE 事件均携带 requestId，用于全链路排障。'."\n"
                .'- 关于引用角标：enableCitation=true 时，正文含 [[cite:n]] 角标，n 与 references.items[].index 一一对应。'."\n"
                .'- 关于 snippet 的使用：recall、references 中的 snippet 为搜索引擎返回的短摘要，内容可能被截断，不代表网页全文。如需完整正文，请自行抓取对应 url 的页面内容。'."\n"
                .'- 关于内部数据：qp、ranked 为服务端内部管线数据，不下发至客户端。'."\n"
                ."\n"
                .'---'."\n"
                ."\n"
                .'#### 成功响应（stream=false）'."\n"
                ."\n"
                .'```json'."\n"
                .'{'."\n"
                .'  "requestId": "2a127bc9-9474-405d-916d-8bc4475fa459",'."\n"
                .'  "messageId": "msg-2a127bc9-9474-405d-916d-8bc4475fa459",'."\n"
                .'  "finishReason": "stop",'."\n"
                .'  "content": "杭州今天多云，气温 18～25℃。[[cite:1]]",'."\n"
                .'  "action": "search",'."\n"
                .'  "recall": {'."\n"
                .'    "total": 2,'."\n"
                .'    "items": ['."\n"
                .'      {'."\n"
                .'        "title": "杭州天气预报",'."\n"
                .'        "link": "https://example.com/weather",'."\n"
                .'        "snippet": "今日杭州多云，气温 18～25℃...",'."\n"
                .'        "date": "2026-06-23T08:00:00Z",'."\n"
                .'        "rank_score": 0.95,'."\n"
                .'        "source": {'."\n"
                .'          "name": "中国天气网",'."\n"
                .'          "domain": "weather.com.cn",'."\n"
                .'          "favicon": "https://example.com/favicon.ico"'."\n"
                .'        }'."\n"
                .'      }'."\n"
                .'    ]'."\n"
                .'  },'."\n"
                .'  "references": {'."\n"
                .'    "items": ['."\n"
                .'      {'."\n"
                .'        "sourceType": "web",'."\n"
                .'        "index": 1,'."\n"
                .'        "title": "杭州天气预报",'."\n"
                .'        "url": "https://example.com/weather",'."\n"
                .'        "snippet": "今日杭州多云...",'."\n"
                .'        "score": 0.95,'."\n"
                .'        "favicon": "https://example.com/favicon.ico"'."\n"
                .'      }'."\n"
                .'    ]'."\n"
                .'  },'."\n"
                .'  "follow_up": {'."\n"
                .'    "questions": ["杭州明天天气怎么样？", "杭州近期适合出游吗？"]'."\n"
                .'  },'."\n"
                .'  "usage": {'."\n"
                .'    "qp_ms": 120.5,'."\n"
                .'    "recall_rank_ms": 350.2,'."\n"
                .'    "answer_ms": 1500.0,'."\n"
                .'    "follow_up_ms": 856.2,'."\n"
                .'    "grand_total_ms": 9716.0,'."\n"
                .'    "input_tokens": 2480,'."\n"
                .'    "output_tokens": 356,'."\n"
                .'    "total_tokens": 2836'."\n"
                .'  }'."\n"
                .'}'."\n"
                .'```'."\n"
                ."\n"
                .'#### 成功响应（stream=true，SSE 单帧示例）'."\n"
                ."\n"
                .'```json'."\n"
                .'{'."\n"
                .'  "event": "text-delta",'."\n"
                .'  "data": {'."\n"
                .'    "type": "text-delta",'."\n"
                .'    "requestId": "2a127bc9-9474-405d-916d-8bc4475fa459",'."\n"
                .'    "id": "txt-2a127bc9-9474-405d-916d-8bc4475fa459",'."\n"
                .'    "delta": "杭州今天多云，气温 18～25℃。"'."\n"
                .'  },'."\n"
                .'  "id": "2a127bc9-9474-405d-916d-8bc4475fa459"'."\n"
                .'}'."\n"
                .'```'."\n"
                ."\n"
                .'#### 失败响应（stream=false）'."\n"
                ."\n"
                .'```json'."\n"
                .'{'."\n"
                .'  "requestId": "2a127bc9-9474-405d-916d-8bc4475fa459",'."\n"
                .'  "messageId": "msg-2a127bc9-9474-405d-916d-8bc4475fa459",'."\n"
                .'  "finishReason": "error",'."\n"
                .'  "error": {'."\n"
                .'    "errorText": "模型服务暂时不可用",'."\n"
                .'    "errorCode": "INTERNAL_ERROR",'."\n"
                .'    "retryable": true'."\n"
                .'  }'."\n"
                .'}'."\n"
                .'```'."\n"
                ."\n"
                .'#### 失败响应（网关层 / 流式）'."\n"
                ."\n"
                .'```json'."\n"
                .'{'."\n"
                .'  "error": {'."\n"
                .'    "message": "userId不能为空",'."\n"
                .'    "code": "403"'."\n"
                .'  }'."\n"
                .'}'."\n"
                .'```'."\n"
                ."\n"
                .'#### 错误码'."\n"
                ."\n"
                .'| 错误码 | message | 说明 | 建议处理方式 |'."\n"
                .'| --- | --- | --- | --- |'."\n"
                .'| `INVALID_PARAM` | query 不能为空 / 图片超过 10MB | 请求参数不合法 | 检查 `message.parts` 是否包含有效文本或图片，修改后重新发起请求。 |'."\n"
                .'| `INTERNAL_ERROR` | 模型服务暂时不可用 | 服务内部错误 | 稍后重试；若持续出现，请联系技术支持并提供 `requestId` 和请求参数。 |'."\n"
                .'| `403` | Account not in whitelist | 账号未开通联网问答权限 | 联系开通内测白名单后重试。 |'."\n"
                .'| `400` | userId不能为空 | 缺少调用账号信息 | 确认 ApiKey 已绑定有效主账号。 |'."\n"
                .'| `400` | request body is empty | 请求体为空 | 检查请求体格式与 Content-Type。 |'."\n"
                .'| `400` | Request was denied due to user flow control | 请求过于频繁，超出 QPS 阈值 | 降低调用频率。 |'."\n"
                .'| `NoPermission` | — | 缺少 RAM 权限 | 授权 `maasaisearchproxy:QaChat` 及 `maasaisearchproxy:CallWithBearerToken`。 |'."\n"
                .'| `InvalidApiKey` | — | ApiKey 无效 | 检查密钥是否为创建时的长串密钥。 |'."\n"
                .'| `503` | The request has failed due to a temporary failure of the server | 服务器繁忙或正在维护 | 稍等片刻后重试；若问题持续存在，请联系技术支持。 |',
            'changeSet' => [],
            'ramActions' => [],
            'responseDemo' => '[{"errorExample":"","example":"{\\n  \\"event\\": \\"start\\",\\n  \\"data\\": {\\n    \\"type\\": \\"start\\",\\n    \\"requestId\\": \\"2a127bc9-9474-405d-916d-8bc4475fa459\\",\\n    \\"id\\": \\"2a127bc9-9474-405d-916d-8bc4475fa459\\",\\n    \\"delta\\": \\"杭州今天多云，气温 18～25℃。\\",\\n    \\"data\\": \\"{\\\\n  \\\\\\"items\\\\\\": [\\\\n    {\\\\n      \\\\\\"sourceType\\\\\\": \\\\\\"web\\\\\\",\\\\n      \\\\\\"index\\\\\\": 1,\\\\n      \\\\\\"title\\\\\\": \\\\\\"杭州天气预报\\\\\\",\\\\n      \\\\\\"url\\\\\\": \\\\\\"https://example.com/weather\\\\\\",\\\\n      \\\\\\"snippet\\\\\\": \\\\\\"今日杭州多云...\\\\\\",\\\\n      \\\\\\"score\\\\\\": 0.95,\\\\n      \\\\\\"favicon\\\\\\": \\\\\\"https://example.com/favicon.ico\\\\\\"\\\\n    }\\\\n  ]\\\\n}\\\\n\\",\\n    \\"finishReason\\": \\"stop\\",\\n    \\"errorCode\\": \\"INTERNAL_ERROR\\",\\n    \\"errorText\\": \\"模型服务暂时不可用\\",\\n    \\"retryable\\": true\\n  },\\n  \\"id\\": \\"2a127bc9-9474-405d-916d-8bc4475fa459\\"\\n}","type":"json"}]',
        ],
        'WebSearch' => [
            'summary' => '联网搜索 API 允许您向互联网发起实时搜索，并获取结构化的网页结果列表。您可以将其集成到 AI 问答、内容聚合、舆情监控、知识增强等场景中，为您的应用提供实时、多源的外部知识支撑。'."\n"
                ."\n"
                .'提供 2 种搜索模式：'."\n"
                .'1. Pro 版，适合复杂问题搜索，提供更相关、更权威的结果，支持搜索全球信源'."\n"
                .'2. Lite 版，适合日常问题搜索，响应更快、成本更低',
            'path' => '/api/web-search',
            'methods' => ['post'],
            'schemes' => ['https'],
            'security' => [
                [
                    'AK' => [],
                ],
                [
                    'ApiKey' => [],
                ],
            ],
            'consumes' => ['application/json'],
            'produces' => ['application/json'],
            'operationType' => 'read',
            'deprecated' => false,
            'systemTags' => ['operationType' => 'none', 'riskType' => 'none', 'chargeType' => 'free', 'autoTest' => true, 'tenantRelevance' => 'publicInformation'],
            'parameters' => [
                [
                    'name' => 'body',
                    'in' => 'body',
                    'style' => 'json',
                    'schema' => [
                        'description' => '请求体参数',
                        'type' => 'object',
                        'properties' => [
                            'query' => ['description' => '查询词，支持自然语言表达。建议长度不超过 100 个字符。', 'type' => 'string', 'required' => false, 'example' => 'Alibaba Cloud Latest News'],
                            'limit' => ['description' => '返回结果的最大条数。支持 1 至 10，默认值为 10。', 'type' => 'integer', 'format' => 'int32', 'required' => false, 'example' => '10'],
                            'includeDomain' => [
                                'description' => '白名单站点，配置后、将仅返回指定域名范围内的结果。单次请求最多支持 30 个站点。注意：仅 region 参数设置为 global 时生效',
                                'type' => 'array',
                                'items' => ['description' => 'url', 'type' => 'string', 'required' => false, 'example' => 'www.aliyun.com'],
                                'required' => false,
                            ],
                            'excludeDomain' => [
                                'description' => '黑名单站点，配置后、将排除指定域名范围内的结果。单次请求最多支持 30 个站点',
                                'type' => 'array',
                                'items' => ['description' => 'url', 'type' => 'string', 'required' => false, 'example' => 'example.com'],
                                'required' => false,
                            ],
                            'startTime' => ['description' => '返回该日期后（包含当天）的搜索结果，格式为 `YYYY-MM-DD`，例如 `2024-01-01`。不填则不限制起始时间。', 'type' => 'string', 'required' => false, 'example' => '2026-03-06'],
                            'endTime' => ['description' => '返回该日期前（包含当天）的搜索结果，格式为 `YYYY-MM-DD`，例如 `2026-01-01`。不填则不限制截止时间。', 'type' => 'string', 'required' => false, 'example' => '2026-03-06'],
                            'region' => [
                                'description' => '搜索信源范围。当前支持 mainland_china（中国大陆）、 global（全球）。默认值为 mainland_china。'."\n"
                                    ."\n"
                                    .'注意：如您选择global（全球），您的数据可能出境，请您自行评估相关风险。如继续操作视为您已完成评估且相关数据出境的风险和责任由您自行承担。',
                                'type' => 'string',
                                'required' => false,
                                'enumValueTitles' => ['global' => '全球', 'mainland_china' => '中国大陆'],
                                'example' => 'mainland_china',
                            ],
                            'searchType' => [
                                'description' => '搜索模式。当前支持 pro、lite 两种搜索模式。默认值为 pro。'."\n"
                                    ."\n"
                                    .'注意：lite 模式下，不支持传入 region、excludeDomain、includeDomain 参数',
                                'type' => 'string',
                                'required' => false,
                                'enumValueTitles' => ['pro' => 'pro', 'lite' => 'lite'],
                                'example' => 'pro',
                            ],
                        ],
                        'required' => false,
                    ],
                ],
            ],
            'responses' => [
                200 => [
                    'schema' => [
                        'title' => 'Result<WebSearchRsp>',
                        'description' => 'Result<WebSearchRsp>',
                        'type' => 'object',
                        'properties' => [
                            'code' => ['title' => 'code', 'description' => '业务状态码。`200` 表示请求成功，其他值表示异常，详见文档「错误码」部分。', 'type' => 'integer', 'format' => 'int32', 'example' => '200'],
                            'message' => ['title' => '消息', 'description' => '状态描述。成功时为 `"successful"`，失败时为具体的错误信息。', 'type' => 'string', 'example' => 'successful'],
                            'data' => [
                                'description' => '搜索结果数据，仅在 `code` 为 `200` 时存在。',
                                'type' => 'object',
                                'properties' => [
                                    'total' => ['title' => '总结果数', 'description' => '本次搜索命中的结果总条数', 'type' => 'integer', 'format' => 'int32', 'example' => '10'],
                                    'result' => [
                                        'description' => '搜索结果列表',
                                        'type' => 'array',
                                        'items' => [
                                            'description' => 'Result 对象',
                                            'type' => 'object',
                                            'properties' => [
                                                'title' => ['title' => '标题', 'description' => '网页标题', 'type' => 'string', 'example' => 'Alibaba Cloud: AI and Cloud Computing Services'],
                                                'url' => ['title' => 'url链接', 'description' => '网页原始链接', 'type' => 'string', 'example' => 'https://www.alibabacloud.com/'],
                                                'snippet' => ['title' => '摘要', 'description' => '网页摘要片段', 'type' => 'string', 'example' => 'Everything You Need in One Powerful AI Cloud Platform For AI Builders shaping the future and Enterprises scaling AI securely.'."\n"
                                                    .'Redefining AI economics with unmatched speed, intelligence and affordability.'],
                                                'date' => ['title' => '网页时间', 'description' => '网页发布时间，格式为 ISO 8601。', 'type' => 'string', 'example' => '2026-05-06T00:25:35Z'],
                                                'source' => [
                                                    'title' => '来源',
                                                    'description' => '网页来源信息，包含 favicon、domain、name 字段。',
                                                    'type' => 'object',
                                                    'properties' => [
                                                        'name' => ['title' => '来源名称', 'description' => '网站的名称，通常与域名一致 或 为网站的中文名称。', 'type' => 'string', 'example' => 'www.aliyun.com'],
                                                        'domain' => ['title' => '来源域名', 'description' => '网站的域名。', 'type' => 'string', 'example' => 'www.aliyun.com'],
                                                        'favicon' => ['title' => '来源favicon', 'description' => '网站的图标链接。', 'type' => 'string', 'example' => 'https://domain.com/sample_favicon.webp'],
                                                    ],
                                                ],
                                            ],
                                        ],
                                    ],
                                ],
                            ],
                        ],
                    ],
                ],
            ],
            'staticInfo' => ['returnType' => 'synchronous'],
            'title' => '联网搜',
            'requestParamsDescription' => '- `start_date` 与 `end_date` 均为可选参数，可单独使用，也可组合使用以限定时间区间。时间过滤基于网页的发布时间（date），若网页未标注发布时间，则该条结果不受时间参数约束。',
            'responseParamsDescription' => '- 关于时间过滤精度：start_date和 end_date 的过滤粒度为天（精确到日期），且依赖于网页自身标注的发布时间。对于未标注发布时间的网页，时间过滤不生效。'."\n"
                .'- 关于结果去重：同一 URL 在单次请求中不会重复出现，但不同请求之间不保证结果集完全不同。'."\n"
                .'- 关于 snippet 的使用：snippet 为搜索引擎返回的短摘要，内容可能被截断，不代表网页全文。如需完整正文，请自行抓取对应 url 的页面内容。'."\n"
                ."\n"
                .'#### 成功响应'."\n"
                .'```'."\n"
                .'{'."\n"
                .'  "code": 200,'."\n"
                .'  "message": "successful",'."\n"
                .'  "data": {'."\n"
                .'    "total": 2,'."\n"
                .'    "result": ['."\n"
                .'      {'."\n"
                .'        "snippet": "阿里云—阿里巴巴集团旗下全球领先的云计算及人工智能科技公司之一...",'."\n"
                .'        "date": "2025-12-10T16: 00: 00Z",'."\n"
                .'        "source": {'."\n"
                .'          "favicon": "https://domain.com/sample_img_1.png",'."\n"
                .'          "domain": "www.aliyun.com",'."\n"
                .'          "name": "阿里云"'."\n"
                .'        },'."\n"
                .'        "title": "阿里云-计算，为了无法计算的价值",'."\n"
                .'        "url": "http://www.aliyun.com/"'."\n"
                .'      },'."\n"
                .'      {'."\n"
                .'        "snippet": "云计算服务和云解决方案...",'."\n"
                .'        "date": "2025-12-10T16: 00: 00Z",'."\n"
                .'        "source": {'."\n"
                .'          "favicon": "https://domain.com/sample_img_2.webp",'."\n"
                .'          "domain": "www.alibabacloud.com",'."\n"
                .'          "name": "www.alibabacloud.com"'."\n"
                .'        },'."\n"
                .'        "title": "云计算服务和云解决方案 - 阿里云",'."\n"
                .'        "url": "https://www.alibabacloud.com/zh/iat/homepage-new-test?_p_lc=1"'."\n"
                .'      }'."\n"
                .'    ]'."\n"
                .'  }'."\n"
                .'}'."\n"
                ."\n"
                .'```'."\n"
                ."\n"
                .'#### 失败响应'."\n"
                .'```'."\n"
                .'{'."\n"
                .'  "code": 401,'."\n"
                .'  "message": "Invalid parameter format"'."\n"
                .'}'."\n"
                ."\n"
                .'```'."\n"
                ."\n"
                .'#### 错误码'."\n"
                ."\n"
                .'| 错误码 | message | 说明 | 建议处理方式 |'."\n"
                .'| --- | --- | --- | --- |'."\n"
                .'|`201` | Partial results returned due to compliance restrictions | 部分搜索结果因合规要求被拦截 | 检查 Query 是否合规，或忽略被拦截的内容、直接使用当前返回的结果。 |'."\n"
                .'| `301` | Request blocked due to legal and regulatory requirements | 基于安全考虑，请求被拦截。本次请求不计费 | 检查 Query 参数内容是否合法合规，修改后可重新发起请求。 |'."\n"
                .'| `400` | Request was denied due to user flow control | 请求过于频繁，超出 QPS 阈值 | 降低调用频率。 |'."\n"
                .'| `401` | Invalid request parameters | 请求参数不合法 | 检查请求参数格式和长度，修改后重新发起请求。|'."\n"
                .'| `500` | Internal server error | 服务内部错误 | 稍后重试；若持续出现，请联系技术支持并提供请求时间和参数。 |'."\n"
                .'| `503` | The request has failed due to a temporary failure of the server | 服务器繁忙或正在维护，当前请求无法完成。 | 建议您稍等片刻后刷新页面重试，若问题持续存在，请联系技术支持。 |',
            'changeSet' => [],
            'ramActions' => [
                [
                    'operationType' => 'none',
                    'ramAction' => [
                        'action' => 'maasaisearchproxy:WebSearch',
                        'authLevel' => 'operate',
                        'actionConditions' => [],
                        'resources' => [
                            ['validationType' => 'always', 'product' => 'MaasAISearchProxy', 'resourceType' => '全部资源', 'arn' => '*'],
                        ],
                    ],
                    'additionalActions' => [
                        ['action' => 'maasaisearchproxy:CallWithBearerToken', 'validationType' => 'conditional'],
                    ],
                ],
            ],
            'responseDemo' => '[{"errorExample":"","example":"{\\n  \\"code\\": 200,\\n  \\"message\\": \\"successful\\",\\n  \\"data\\": {\\n    \\"total\\": 10,\\n    \\"result\\": [\\n      {\\n        \\"title\\": \\"Alibaba Cloud: AI and Cloud Computing Services\\",\\n        \\"url\\": \\"https://www.alibabacloud.com/\\",\\n        \\"snippet\\": \\"Everything You Need in One Powerful AI Cloud Platform For AI Builders shaping the future and Enterprises scaling AI securely.\\\\nRedefining AI economics with unmatched speed, intelligence and affordability.\\",\\n        \\"date\\": \\"2026-05-06T00:25:35Z\\",\\n        \\"source\\": {\\n          \\"name\\": \\"www.aliyun.com\\",\\n          \\"domain\\": \\"www.aliyun.com\\",\\n          \\"favicon\\": \\"https://domain.com/sample_favicon.webp\\"\\n        }\\n      }\\n    ]\\n  }\\n}","type":"json"}]',
        ],
    ],
    'endpoints' => [
        ['regionId' => 'public', 'regionName' => '公网', 'areaId' => 'other', 'areaName' => '其它', 'public' => 'maasaisearchproxy.aliyuncs.com', 'endpoint' => 'maasaisearchproxy.aliyuncs.com', 'vpc' => ''],
    ],
    'errorCodes' => [],
    'changeSet' => [],
    'ram' => [
        'productCode' => 'MaasAISearchProxy',
        'productName' => 'AI Search Proxy',
        'ramCodes' => ['maasaisearchproxy'],
        'ramLevel' => '操作级',
        'ramConditions' => [],
        'ramActions' => [
            [
                'apiName' => 'WebSearch',
                'description' => '联网搜',
                'operationType' => 'none',
                'additionalActions' => [
                    ['action' => 'maasaisearchproxy:CallWithBearerToken', 'validationType' => 'conditional'],
                ],
                'ramAction' => [
                    'action' => 'maasaisearchproxy:WebSearch',
                    'authLevel' => 'operate',
                    'actionConditions' => [],
                    'resources' => [
                        ['validationType' => 'always', 'product' => 'MaasAISearchProxy', 'resourceType' => '全部资源', 'arn' => '*'],
                    ],
                ],
            ],
        ],
        'resourceTypes' => [],
    ],
];