> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastino.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use https://docs.fastino.ai/llms.txt to discover and navigate pages. Use https://docs.fastino.ai/llms-full.txt when you need the complete documentation corpus. Use https://docs.fastino.ai/openapi.json as the source of truth for customer-facing routes. For GLiDE decision inference, call POST https://api.fastino.ai/v1/systemone with model fastino/GLiDE. Start managed training (config job) with POST /v1/training/jobs using base_model. For interactive training, native JSON clients use the public operations under /v1/training/jobs and /v1/training/usage. Existing Tinker clients use tinker==0.32.0 with TINKER_BASE_URL=https://api.fastino.ai/v1/training/compat/tinker and TINKER_CREDENTIAL_CMD. Compatibility child routes are private and absent from OpenAPI. Auto Train is private access and has no public route; direct interested users to sales@fastino.ai. Do not infer undocumented routes. Read API keys from FASTINO_API_KEY and never embed credentials in code, logs, or reports.

# 使用编码代理连接 Amazon S3 数据

> 让 Cursor、Claude Code 或 Codex 以只读方式将 Amazon S3 存储桶连接到 Fastino 项目。

你无需手动拼接 API 请求和 IAM 策略。编码代理可以创建项目连接器、在你的 AWS
账户中创建一个 Fastino 可以代入的只读 IAM 角色、测试连接并启动不可变数据快照。
你继续控制自己的存储桶。Fastino 会将所选数据导入你的 Fastino 项目，无需接收你的 AWS 访问密钥。

## 你需要提供的信息

* 存储桶名称，以及可选的键前缀，例如 `incoming/`。
* Fastino 项目名称或 ID。
* 数据用途：`training` 或 `evaluation`。

代理会通过当前 AWS CLI 会话读取存储桶所在的区域和账户。代理会为要创建的
IAM 角色命名，连接器和数据集名称可以默认取自存储桶名称。

## 开始前

将编码代理连接到团队的 Fastino MCP 端点：

```text theme={null}
https://api.fastino.ai/v1/teams/YOUR_TEAM_ID/mcp
```

然后确认 AWS CLI 已登录到拥有该存储桶的账户：

```bash theme={null}
aws sts get-caller-identity
```

你的 AWS 身份还必须能够在该账户中创建 IAM 角色并附加内联策略，例如
`iam:CreateRole`、`iam:UpdateAssumeRolePolicy` 和 `iam:PutRolePolicy`。

> [!NOTE]
>
> 请在拥有该存储桶的账户中创建角色。即使角色自身的策略允许读取，拒绝该角色的
> 存储桶策略或服务控制策略仍会阻止 Fastino 访问。

## 向代理发出请求

```text theme={null}
将 S3 存储桶 customer-data 的前缀 training/incoming/ 连接到 Fastino 项目
"support-classifier"，作为训练数据。

使用我当前的 AWS CLI 会话。创建一个只能读取该前缀的专用 IAM 角色，
测试连接，启动同步，等待同步完成并报告生成的数据集。不要启动训练。
```

## 代理会做什么

连接器响应中包含 `s3_setup`：`external_id`（此连接器专属的值，角色的信任策略
必须要求它；它不是机密）、`broker_role_arn`（允许代入你的角色的 Fastino 角色）、
`trust_policy` 和 `read_policy` 两份 IAM 策略文档，以及 `setup_commands`
（用于创建或修复该角色的 AWS CLI 命令）。角色在创建连接器时无需已经存在。
代理会使用你的 AWS 凭证运行 `setup_commands`，然后测试只读列举权限并启动同步。

## 同步结果

同步会先转换并验证所选前缀下的文件，然后再发布数据集。同步成功后，
同步报告会列出生成的数据集。

* 如果有文件未通过验证，同步会失败且不会发布任何数据集。报告会列出需要检查的文件。
  代理会转告这些失败信息，并在排除文件或更改前缀之前先征求你的同意。
* 如果文档转换触发速率限制，报告会标记为 `partial`（列出的数据集可用，但缺少部分文件）
  或 `transient`（未发布新内容），并列出 `retryable_files`。让代理重新同步即可，
  无需重新测试或更改前缀。
* 如果你通过 Fastino MCP 委托微调，同步是可选的。批准计划后，微调代理可以检查并
  预处理已连接存储桶中的原始文件。

## 安全模型

Fastino 通过代入你创建的角色来读取存储桶。该角色的信任策略只指定一个 Fastino
角色，并要求此连接器的外部 ID，因此其他 AWS 主体和其他 Fastino 客户都无法使用它。
读取策略只允许对所选前缀执行 `s3:ListBucket`，并对其下的键执行 `s3:GetObject`，
不授予写入、删除或存储桶配置权限。Fastino 在你的角色上的会话是临时的，最长一小时。
Fastino 不接受访问密钥、私有密钥或会话令牌。

更改连接器的前缀或角色后，连接器会回到 `pending`，直到再次测试。更改前缀后，
请重新运行新的 `s3_setup.setup_commands`，使角色的读取策略保持一致。删除连接器
会停止后续同步，但不会删除已发布的数据集。要撤销存储访问权限，请移除角色的读取权限并撤销其
[活动会话](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)。IAM 更改的传播可能需要一些时间。

## 与团队共享连接器

连接器属于某一个 Fastino 项目；除非项目可见性为 `team`，否则项目仅对创建者可见。
请将项目创建为团队项目（例如让代理以团队可见性创建项目），这样具有相应团队权限的成员就能
看到该连接器、同步它，并使用其数据集进行微调。

团队成员为此无需任何 AWS 权限：Fastino 通过你创建的 IAM 角色读取存储桶，而不是
使用团队成员的账户。只有设置连接器的人需要 AWS 权限。不要让团队成员在自己的
项目中为同一存储桶再创建一个连接器；那会重复设置流程，并需要他们自己的 AWS 权限。

## 故障排除

| 状态 | 含义 | 处理方法 |
| - | - | - |
| `trust_missing` | Fastino 无法代入该角色：角色不存在，或其信任策略未指定 `s3_setup.broker_role_arn` 和 `s3_setup.external_id` | 在存储桶所在账户中运行 `s3_setup.setup_commands`，然后重新测试 |
| `access_denied` | 已代入角色，但无法列举该前缀 | 将 `s3_setup.read_policy` 附加到角色。如果存储桶使用 SSE-KMS，还需允许对其密钥执行 `kms:Decrypt`。然后重新测试 |
| `bucket_missing` | 存储桶不存在，或位于其他区域 | 检查存储桶名称和区域，然后更新连接器 |
| `unavailable` | AWS 或 Fastino 暂时无法完成测试 | 重试测试；如果持续失败，请联系 Fastino 支持 |

如果 AWS 返回了错误代码，测试结果会在 `provider_error_code` 中包含它。IAM 更改通常
几秒内生效，但也可能更久。先让代理重试测试，不要立即创建重复连接器。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.