Skip to content

docs: enhance README documentation with multilingual support #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: enhance README documentation with multilingual support #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 15 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
[中文](./README_CN.md)

# Bedrock Access Gateway

OpenAI-compatible RESTful APIs for Amazon Bedrock

[繁體中文](./README_TW.md) | [簡體中文](./README_CN.md)

## What's New 🔥

This project supports reasoning for both **Claude 3.7 Sonnet** and **DeepSeek R1**, check [How to Use](./docs/Usage.md#reasoning) for more details. You need to first run the Models API to refresh the model list.
Expand All @@ -30,7 +30,6 @@ If you find this GitHub repository useful, please consider giving it a free star

Please check [Usage Guide](./docs/Usage.md) for more details about how to use the new APIs.


## Get Started

### Prerequisites
Expand All @@ -57,41 +56,44 @@ Please follow the steps below to deploy the Bedrock Proxy APIs into your AWS acc

**Step 1: Create your own API key in Secrets Manager (MUST)**


> **Note:** This step is to use any string (without spaces) you like to create a custom API Key (credential) that will be used to access the proxy API later. This key does not have to match your actual OpenAI key, and you don't need to have an OpenAI API key. please keep the key safe and private.

1. Open the AWS Management Console and navigate to the AWS Secrets Manager service.
2. Click on "Store a new secret" button.
2. Click on "Store a new secret" button.
3. In the "Choose secret type" page, select:

Secret type: Other type of secret
Key/value pairs:

- Key: api_key
- Value: Enter your API key value

Click "Next"

4. In the "Configure secret" page:
Secret name: Enter a name (e.g., "BedrockProxyAPIKey")
Description: (Optional) Add a description of your secret
5. Click "Next" and review all your settings and click "Store"

After creation, you'll see your secret in the Secrets Manager console. Make note of the secret ARN.

After creation, you'll see your secret in the Secrets Manager console. Make note of the secret ARN.

**Step 2: Deploy the CloudFormation stack**

1. Sign in to AWS Management Console, switch to the region to deploy the CloudFormation Stack to.
2. Click the following button to launch the CloudFormation Stack in that region. Choose one of the following:

[<kbd> <br> ALB + Lambda 1-Click Deploy 🚀 <br> </kbd>](https://console.aws.amazon.com/cloudformation/home?#/stacks/quickcreate?templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxy.template&stackName=BedrockProxyAPI)
[<kbd> <br> ALB + Lambda 1-Click Deploy 🚀 <br> </kbd>](https://console.aws.amazon.com/cloudformation/home?#/stacks/quickcreate?templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxy.template&stackName=BedrockProxyAPI)

[<kbd> <br> ALB + Fargate 1-Click Deploy 🚀 <br> </kbd>](https://console.aws.amazon.com/cloudformation/home?#/stacks/quickcreate?templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxyFargate.template&stackName=BedrockProxyAPI)

[<kbd> <br> ALB + Fargate 1-Click Deploy 🚀 <br> </kbd>](https://console.aws.amazon.com/cloudformation/home?#/stacks/quickcreate?templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxyFargate.template&stackName=BedrockProxyAPI)
3. Click "Next".
4. On the "Specify stack details" page, provide the following information:
- Stack name: Change the stack name if needed.
- ApiKeySecretArn: Enter the secret ARN you used for storing the API key.


- Stack name: Change the stack name if needed.
- ApiKeySecretArn: Enter the secret ARN you used for storing the API key.

Click "Next".

5. On the "Configure stack options" page, you can leave the default settings or customize them according to your needs. Click "Next".
6. On the "Review" page, review the details of the stack you're about to create. Check the "I acknowledge that AWS CloudFormation might create IAM resources" checkbox at the bottom. Click "Create stack".

Expand Down Expand Up @@ -148,8 +150,6 @@ print(completion.choices[0].message.content)

Please check [Usage Guide](./docs/Usage.md) for more details about how to use embedding API, multimodal API and tool call.



## Other Examples

### LangChain
Expand Down Expand Up @@ -243,7 +243,6 @@ To do so, depends on which version you deployed:
- **Lambda version**: Go to AWS Lambda console, find the Lambda function, then find and click the `Deploy new image` button and click save.
- **Fargate version**: Go to ECS console, click the ECS cluster, go the `Tasks` tab, select the only task that is running and simply click `Stop selected` menu. A new task with latest image will start automatically.


## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
Expand Down
99 changes: 49 additions & 50 deletions README_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,20 @@
[English](./README.md)

# Bedrock Access Gateway

使用兼容OpenAI的API访问Amazon Bedrock
使用兼容 OpenAI 的 API 访问 Amazon Bedrock

## 新功能 🔥
[English](./README.md) | [繁體中文](./README_TW.md)

本项目支持 **Claude 3.7 Sonnet** 和 **DeepSeek R1** 的推理（Reasoning）功能，查看[使用方法](./docs/Usage_CN.md#reasoning) 获取更多详情。首次使用你需要先运行下Models API 来刷新model列表。
## 新功能 🔥

本项目支持 **Claude 3.7 Sonnet** 和 **DeepSeek R1** 的推理（Reasoning）功能，查看[使用方法](./docs/Usage_CN.md#reasoning) 获取更多详情。首次使用你需要先运行下 Models API 来刷新 model 列表。

## 概述

Amazon Bedrock提供了广泛的基础模型(如Claude 3 Opus/Sonnet/Haiku、Llama 2/3、Mistral/Mixtral等),以及构建生成式AI应用程序的多种功能。更多详细信息,请查看[Amazon
Amazon Bedrock 提供了广泛的基础模型(如 Claude 3 Opus/Sonnet/Haiku、Llama 2/3、Mistral/Mixtral 等),以及构建生成式 AI 应用程序的多种功能。更多详细信息,请查看[Amazon
Bedrock](https://aws.amazon.com/bedrock)。

有时,您可能已经使用OpenAI的API或SDK构建了应用程序,并希望在不修改代码的情况下试用Amazon
Bedrock的模型。或者,您可能只是希望在AutoGen等工具中评估这些基础模型的功能。 好消息是, 这里提供了一种方便的途径,让您可以使用
有时,您可能已经使用 OpenAI 的 API 或 SDK 构建了应用程序,并希望在不修改代码的情况下试用 Amazon
Bedrock 的模型。或者,您可能只是希望在 AutoGen 等工具中评估这些基础模型的功能。 好消息是, 这里提供了一种方便的途径,让您可以使用
OpenAI 的 API 或 SDK 无缝集成并试用 Amazon Bedrock 的模型,而无需对现有代码进行修改。

如果您觉得这个项目有用,请考虑给它点个一个免费的小星星 ⭐。
Expand All @@ -31,15 +30,15 @@ OpenAI 的 API 或 SDK 无缝集成并试用 Amazon Bedrock 的模型,而无需
- [x] 支持 Cross-Region Inference
- [x] 支持 Reasoning Mode (**new**)

请查看[使用指南](./docs/Usage_CN.md)以获取有关如何使用新API的更多详细信息。
请查看[使用指南](./docs/Usage_CN.md)以获取有关如何使用新 API 的更多详细信息。

## 使用指南

### 前提条件

请确保您已满足以下先决条件:

- 可以访问Amazon Bedrock基础模型。
- 可以访问 Amazon Bedrock 基础模型。

如果您还没有获得模型访问权限,请参考[配置](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)指南。

Expand All @@ -49,61 +48,63 @@ OpenAI 的 API 或 SDK 无缝集成并试用 Amazon Bedrock 的模型,而无需

![Architecture](assets/arch.png)

您也可以选择在 ALB 后面接 [AWS Fargate](https://aws.amazon.com/fargate/) 而不是 [AWS Lambda](https://aws.amazon.com/lambda/)，主要区别在于流响应的首字节延迟（Fargate更低）。
您也可以选择在 ALB 后面接 [AWS Fargate](https://aws.amazon.com/fargate/) 而不是 [AWS Lambda](https://aws.amazon.com/lambda/)，主要区别在于流响应的首字节延迟（Fargate 更低）。

或者,您可以使用 Lambda Function URL 来代替 ALB,请参阅[示例](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/fastapi-response-streaming)

### 部署

请按以下步骤将Bedrock代理API部署到您的AWS账户中。仅支持Amazon Bedrock可用的区域(如us-west-2)。 部署预计用时**3-5分钟** 🕒。
请按以下步骤将 Bedrock 代理 API 部署到您的 AWS 账户中。仅支持 Amazon Bedrock 可用的区域(如 us-west-2)。 部署预计用时**3-5 分钟** 🕒。

**第一步: 在 Secrets Manager 中创建您的 API 密钥（必须）**

> 注意:这一步是使用任意字符串（不带空格）创建一个自定义的API Key(凭证),将用于后续访问代理API。此API Key不必与您实际的OpenAI
> Key一致,您甚至无需拥有OpenAI API Key。请确保保管好此API Key。
> 注意:这一步是使用任意字符串（不带空格）创建一个自定义的 API Key(凭证),将用于后续访问代理 API。此 API Key 不必与您实际的 OpenAI
> Key 一致,您甚至无需拥有 OpenAI API Key。请确保保管好此 API Key。

1. 打开 AWS 管理控制台并导航至 AWS Secrets Manager 服务。
2. 点击 "存储新密钥" 按钮。
3. 在 "选择密钥类型" 页面，选择：

密钥类型：其他类型的密钥 键/值对：

- 键：api_key
- 值：输入您的 API 密钥值
点击 "下一步"
点击 "下一步"

4. 在 "配置密钥" 页面： 密钥名称：输入一个名称（例如："BedrockProxyAPIKey"） 描述：（可选）添加密钥的描述
5. 点击 "下一步"，检查所有设置后点击 "存储"

创建完成后，您将在 Secrets Manager 控制台中看到您的密钥。请记下密钥的 ARN。

**第二步: 部署CloudFormation堆栈**
**第二步: 部署 CloudFormation 堆栈**

1. 登录 AWS 管理控制台,切换到要部署 CloudFormation 堆栈的区域。
2. 单击以下按钮在该区域启动 CloudFormation 堆栈，选择一种方式部署。

1. 登录AWS管理控制台,切换到要部署CloudFormation堆栈的区域。
2. 单击以下按钮在该区域启动CloudFormation堆栈，选择一种方式部署。
- **ALB + Lambda**

[![Launch Stack](assets/launch-stack.png)](https://console.aws.amazon.com/cloudformation/home#/stacks/create/template?stackName=BedrockProxyAPI&templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxy.template)
[![Launch Stack](assets/launch-stack.png)](https://console.aws.amazon.com/cloudformation/home#/stacks/create/template?stackName=BedrockProxyAPI&templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxy.template)

- **ALB + Fargate**

[![Launch Stack](assets/launch-stack.png)](https://console.aws.amazon.com/cloudformation/home#/stacks/create/template?stackName=BedrockProxyAPI&templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxyFargate.template)
[![Launch Stack](assets/launch-stack.png)](https://console.aws.amazon.com/cloudformation/home#/stacks/create/template?stackName=BedrockProxyAPI&templateURL=https://aws-gcr-solutions.s3.amazonaws.com/bedrock-access-gateway/latest/BedrockProxyFargate.template)

3. 单击"下一步"。
4. 在"指定堆栈详细信息"页面,提供以下信息:
- 堆栈名称: 可以根据需要更改名称。
- ApiKeySecretArn:输入您用于存储API 密钥的ARN。

单击"下一步"。
- 堆栈名称: 可以根据需要更改名称。
- ApiKeySecretArn:输入您用于存储 API 密钥的 ARN。
单击"下一步"。
5. 在"配置堆栈选项"页面,您可以保留默认设置或根据需要进行自定义。 单击"下一步"。
6. 在"审核"页面,查看您即将创建的堆栈详细信息。勾选底部的"我确认，AWS CloudFormation 可能创建 IAM 资源。"复选框。 单击"创建堆栈"。

仅此而已 🎉 。部署完成后,点击CloudFormation堆栈,进入"输出"选项卡,你可以从"APIBaseUrl"
中找到API Base URL,它应该类似于`http://xxxx.xxx.elb.amazonaws.com/api/v1` 这样的格式。
仅此而已 🎉 。部署完成后,点击 CloudFormation 堆栈,进入"输出"选项卡,你可以从"APIBaseUrl"
中找到 API Base URL,它应该类似于`http://xxxx.xxx.elb.amazonaws.com/api/v1` 这样的格式。

### SDK/API使用
### SDK/API 使用

你只需要API Key和API Base URL。如果你没有设置自己的密钥,那么默认将使用API Key `bedrock`。
你只需要 API Key 和 API Base URL。如果你没有设置自己的密钥,那么默认将使用 API Key `bedrock`。

现在,你可以尝试使用代理API了。假设你想测试Claude 3 Sonnet模型,那么使用"anthropic.claude-3-sonnet-20240229-v1:0"作为模型ID。
现在,你可以尝试使用代理 API 了。假设你想测试 Claude 3 Sonnet 模型,那么使用"anthropic.claude-3-sonnet-20240229-v1:0"作为模型 ID。

- **API 使用示例**

Expand Down Expand Up @@ -144,9 +145,7 @@ completion = client.chat.completions.create(
print(completion.choices[0].message.content)
```

请查看[使用指南](./docs/Usage_CN.md)以获取有关如何使用Embedding API、多模态API和Tool Call的更多详细信息。


请查看[使用指南](./docs/Usage_CN.md)以获取有关如何使用 Embedding API、多模态 API 和 Tool Call 的更多详细信息。

## 其他例子

Expand Down Expand Up @@ -188,25 +187,25 @@ print(response)

这个方案不会收集您的任何数据。而且,它默认情况下也不会记录任何请求或响应。

### 为什么没有使用API Gateway 而是使用了Application Load Balancer?
### 为什么没有使用 API Gateway 而是使用了 Application Load Balancer?

简单的答案是API Gateway不支持 server-sent events (SSE) 用于流式响应。
简单的答案是 API Gateway 不支持 server-sent events (SSE) 用于流式响应。

### 支持哪些区域?

通常来说，所有Amazon Bedrock支持的区域都支持，如果不支持，请提个Github Issue。
通常来说，所有 Amazon Bedrock 支持的区域都支持，如果不支持，请提个 Github Issue。

注意，并非所有模型都在上面区可用。

### 支持哪些模型?

你可以通过[Model API](./docs/Usage_CN.md#models-api) 获取（或更新）当前区支持的模型列表。
你可以通过[Model API](./docs/Usage_CN.md#models-api) 获取（或更新）当前区支持的模型列表。

### 我可以构建并使用自己的ECR镜像吗?
### 我可以构建并使用自己的 ECR 镜像吗?

是的,你可以克隆repo并自行构建容器镜像(src/Dockerfile),然后推送到你自己的ECR仓库。 脚本可以参考`scripts/push-to-ecr.sh`。
是的,你可以克隆 repo 并自行构建容器镜像(src/Dockerfile),然后推送到你自己的 ECR 仓库。 脚本可以参考`scripts/push-to-ecr.sh`。

在部署之前,请在CloudFormation模板中替换镜像仓库URL。
在部署之前,请在 CloudFormation 模板中替换镜像仓库 URL。

### 我可以在本地运行吗?

Expand All @@ -216,37 +215,37 @@ print(response)
uvicorn api.app:app --host 0.0.0.0 --port 8000
```

那么API Base URL应该类似于`http://localhost:8000/api/v1`
那么 API Base URL 应该类似于`http://localhost:8000/api/v1`

### 使用代理API会有任何性能牺牲或延迟增加吗?
### 使用代理 API 会有任何性能牺牲或延迟增加吗?

与 AWS SDK 调用相比,本方案参考架构会在响应上会有额外的延迟,你可以自己部署并测试。

另外,你也可以使用 Lambda Web Adapter + Function URL (
参见 [示例](https://github.com/awslabs/aws-lambda-web-adapter/tree/main/examples/fastapi-response-streaming))来代替 ALB
或使用 AWS Fargate 来代替 Lambda,以获得更好的流响应性能。

### 有计划支持SageMaker模型吗?
### 有计划支持 SageMaker 模型吗?

目前没有支持SageMaker模型的计划。这取决于是否有客户需求。
目前没有支持 SageMaker 模型的计划。这取决于是否有客户需求。

### 有计划支持Bedrock自定义模型吗?
### 有计划支持 Bedrock 自定义模型吗?

不支持微调模型和设置了已预配吞吐量的模型。如有需要,你可以克隆repo并进行自定义。
不支持微调模型和设置了已预配吞吐量的模型。如有需要,你可以克隆 repo 并进行自定义。

### 如何升级?

要使用最新功能,您无需重新部署CloudFormation堆栈。您只需拉取最新的镜像即可。
要使用最新功能,您无需重新部署 CloudFormation 堆栈。您只需拉取最新的镜像即可。

具体操作方式取决于您部署的版本:

- **Lambda版本**: 进入AWS Lambda控制台,找到Lambda 函数，然后找到并单击`部署新映像`按钮,然后单击保存。
- **Fargate版本**: 进入ECS控制台,单击ECS集群,转到`任务`选项卡,选择正在运行的唯一任务,然后点击`停止所选`菜单, ECS会自动启动新任务并且使用最新镜像。
- **Lambda 版本**: 进入 AWS Lambda 控制台,找到 Lambda 函数，然后找到并单击`部署新映像`按钮,然后单击保存。
- **Fargate 版本**: 进入 ECS 控制台,单击 ECS 集群,转到`任务`选项卡,选择正在运行的唯一任务,然后点击`停止所选`菜单, ECS 会自动启动新任务并且使用最新镜像。

## 安全

更多信息,请参阅[CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications)。

## 许可证

本项目根据MIT-0许可证获得许可。请参阅LICENSE文件。
本项目根据 MIT-0 许可证获得许可。请参阅 LICENSE 文件。
Loading