# Web Grounding
<a name="web-grounding"></a>

Web Grounding 使 Amazon Nova 能够在网络上搜索当前信息，并提供带引文的回复。该功能适用于需要获取模型训练数据以外最新信息的查询。

## Web Grounding 的工作原理
<a name="how-web-grounding-works"></a>

为提示启用 Web Grounding 后，将会执行以下步骤：

1. **请求配置**：应用程序向 Amazon Bedrock API 发送一条用户提示，并将 nova\_grounding 作为 `systemTool` 启用。

1. **搜索与分析**：模型确定是否需要进行搜索、一次或多次搜索相关信息、评估是否需要进行额外搜索以扩大理解范围或更深入地研究特定子主题。

1. **回复生成**：Amazon Nova 会自动合成搜索结果中的信息，以生成基于实时信息的最终 API 响应，并附上对相关资料来源的引文。

## 如何使用 Web Grounding
<a name="enable-web-grounding"></a>

如需查看使用 Web Grounding 的完整代码示例，请参阅“代码示例”部分。

要在结果中包含 Web Grounding，请在 toolConfig 块中指定以下 `systemTool` 参数：

```
import boto3
from botocore.config import Config

# Create the Bedrock Runtime client with extended timeout
bedrock = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",
    config=Config(read_timeout=3600)
)

# Define the tool configuration
tool_config = {
    "tools": [{
        "systemTool": {
            "name": "nova_grounding"
        }
    }]
}

# Send the request
response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=[{
        "role": "user",
        "content": [{"text": "What are the latest developments in quantum computing?"}]
    }],
    toolConfig=tool_config
)

# Extract text with interleaved citations
output_with_citations = ""
content_list = response["output"]["message"]["content"]
for content in content_list:
    if "text" in content:
        output_with_citations += content["text"]
    elif "citationsContent" in content:
        citations = content["citationsContent"]["citations"]
        for citation in citations:
            url = citation["location"]["web"]["url"]
            output_with_citations += f" [{url}]"

print(output_with_citations)
```

## 区域可用性
<a name="web-grounding-availability"></a>

Web Grounding 目前仅面向美国区域开放，且仅支持美国 CRIS 配置文件。

## 响应结构
<a name="web-grounding-response-structure"></a>

以下为响应示例。为简便起见，响应已经精简：

```
{
  "output": {
    "message": {
      "content": [
        {
          "text": "Recent quantum computing developments include...",
          "citationsContent": [
            {
              "location": {
                "web": {
                  "url": "https://example.com/quantum-news",
                  "domain": "example.com"
                }
              }
            }
          ]
        }
      ]
    }
  }
}
```

每个引文包含以下内容：
+ `text`：模型生成响应中的一个文本片段。
+ `citationsContent`：与文本片段相关的引文数据的主容器。
+ `citations`：`citationsContent` 内的容器，用于存储引文的来源位置。
+ `location`：`citations` 内的容器，用于存储引文的具体来源。
+ `web`：`location` 内的容器，用于存储网页来源的详细信息。
+ `url`：引文来源的完整网址（URL）。
+ `domain`：来源 URL 的根域。

## Grounding 安全
<a name="web-grounding-safety"></a>

您的数据永远不会离开 AWS 基础设施。模型生成的查询保留在 AWS 服务中，永远不会发送到外部互联网。我们依托大规模内部 Web 搜索索引与知识图谱，优先采用可信、优质的数据来源，并在数据接入阶段过滤恶意内容。最后，我们通过运行时过滤来保护您的应用程序，使其免受间接提示注入和错误信息的侵害（请注意，这种缓解措施对于非英语语言的效果较为有限）。

## 错误处理
<a name="web-grounding-error-handling"></a>

请勿包含名称为 `nova_grounding` 的 `toolSpec` 条目。添加使用此名称的工具将会导致错误。

使用 Web Grounding 时可能出现的潜在错误列表如下：
+ `malformed_tool_use`
+ `max_tokens`
+ `malformed_model_output`

## 内置工具所需的权限
<a name="permissions"></a>

为确保角色可以在 Amazon Bedrock 上访问 Web Grounding，您可以通过两种方式来实现：

1. **为 IAM 角色启用 BedrockFullAccess 权限**：若角色已具备 BedrockFullAccess 权限，将自动获得 Web Grounding 访问权限。

1. **添加特定权限（如果需要）**：如需更精细的访问控制，可将此策略添加到角色的 IAM 策略，并将账户 ID 替换为您的 AWS 账户 账户 ID：

```
{
    "Statement": [ 
        { 
            "Effect": "Allow", 
            "Action": ["bedrock:InvokeTool"], 
            "Resource": ["arn:aws:bedrock::{111122223333}:system-tool/amazon.nova_grounding"] 
        } 
    ] 
}
```

Web Grounding 将 `aws:requestedRegion` 条件键设置为“未指定”。如果您的现有策略或服务控制策略（SCP）强制执行此条件，则可能会出现访问权限问题。将该条件更新为允许“未指定”的 requestedRegion，即可解决此问题。

**注意**  
如果您启用了 Web Grounding 工具，则需要为您自己以及您的最终用户使用的包含所连接信息的输出负责。当您的输出包含来自引用或来源材料链接的连接信息时，系统将会提示您。您必须在提供给最终用户的输出中保留并显示这些引用和链接。

**注意**  
使用 Web Grounding 会产生额外的成本。有关更多信息，请转到 [AWS Bedrock 定价](https://aws.amazon.com/bedrock/pricing/)。