From 008848968dd46c29d7d835281e9478336abf5903 Mon Sep 17 00:00:00 2001 From: Aiden Dai Date: Mon, 8 Apr 2024 13:24:24 +0800 Subject: [PATCH] Add usage guide --- docs/Usage.md | 257 +++++++++++++++++++++++++++++++++++++++++++++++ docs/Usage_CN.md | 256 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 513 insertions(+) create mode 100644 docs/Usage.md create mode 100644 docs/Usage_CN.md diff --git a/docs/Usage.md b/docs/Usage.md new file mode 100644 index 0000000..18a04e5 --- /dev/null +++ b/docs/Usage.md @@ -0,0 +1,257 @@ +[中文](./Usage_CN.md) + +# Usage Guide + +Assuming you have set up below environment variables after deployed: + +```bash +export OPENAI_API_KEY= +export OPENAI_BASE_URL= +``` + +## Embedding API + +**Important Notice**: Please carefully review the following points before using this proxy API for embedding. + +1. If you have previously used OpenAI embedding models to create vectors, be aware that switching to a new model may not be straightforward. Different models have varying dimensions (e.g., embed-multilingual-v3.0 has 1024 dimensions), and even for the same text, they may produce different results. +2. If you are using OpenAI embedding models for encoded integers (such as with LangChain), this solution will attempt to decode the integers using `tiktoken` to retrieve the original text. However, there is no guarantee that the decoded text will be accurate. +3. If you are using OpenAI embedding models for long texts, you should verify the maximum number of tokens supported for Bedrock models, e.g. for optimal performance, Bedrock recommends limiting the text length to less than 512 tokens. + + +**Example Request** + +```bash +curl $OPENAI_BASE_URL/embeddings \ +-H "Authorization: Bearer $OPENAI_API_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "input": "The food was delicious and the waiter...", + "model": "text-embedding-ada-002", + "encoding_format": "float" + }' +``` + +**Example Response** + +```json +{ + "object": "list", + "data": [ + { + "object": "embedding", + "embedding": [ + -0.02279663, + -0.024612427, + 0.012863159, + ... + 0.01612854, + 0.0038928986 + ], + "index": 0 + } + ], + "model": "cohere.embed-multilingual-v3", + "usage": { + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` + +Alternatively, you can use the OpenAI SDK + +```python +from openai import OpenAI + +client = OpenAI() + +def get_embedding(text, model="text-embedding-3-small"): + text = text.replace("\n", " ") + return client.embeddings.create(input=[text], model=model).data[0].embedding + +text = "hello" +# will output like [0.003578186, 0.028717041, 0.031021118, -0.0014066696,...] +print(get_embedding(text)) +``` + +Or LangChain + +```python +from langchain_openai import OpenAIEmbeddings + +embeddings = OpenAIEmbeddings( + model="text-embedding-3-large", +) +text = "This is a test document." +query_result = embeddings.embed_query(text) +print(query_result[:5]) +doc_result = embeddings.embed_documents([text]) +print(doc_result[0][:5]) +``` + +## Multimodal API + +**Important Notice**: Please carefully review the following points before using this proxy API for Multimodal. + +1. This API is only supported by Claude 3 model. +2. You should ensure the image url can be publicly accessible in the Lambda/Fargate. + +**Example Request** + +```bash +curl $OPENAI_BASE_URL/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "please identify and count all the objects in this images, list all the names" + }, + { + "type": "image_url", + "image_url": { + "url": "https://github.com/aws-samples/bedrock-access-gateway/blob/main/assets/obj-detect.png?raw=true" + } + } + ] + } + ] +}' +``` + +**Example Response** + +```json +{ + "id": "msg_01BY3wcz41x7XrKhxY3VzWke", + "created": 1712543069, + "model": "anthropic.claude-3-sonnet-20240229-v1:0", + "system_fingerprint": "fp", + "choices": [ + { + "index": 0, + "finish_reason": "stop", + "message": { + "role": "assistant", + "content": "The image contains the following objects:\n\n1. A peach-colored short-sleeve button-up shirt\n2. An olive green plaid long coat/jacket\n3. A pair of white sneakers or canvas shoes\n4. A brown shoulder bag or purse\n5. A makeup brush or cosmetic applicator\n6. A tube or container (possibly lipstick or lip balm)\n7. A pair of sunglasses\n8. A thought bubble icon\n9. A footprint icon\n10. A leaf or plant icon\n11. A flower icon\n12. A cloud icon\n\nIn total, there are 12 distinct objects depicted in the illustrated scene." + } + } + ], + "object": "chat.completion", + "usage": { + "prompt_tokens": 197, + "completion_tokens": 147, + "total_tokens": 344 + } +} +``` + + +## Tool Call + +**Important Notice**: Please carefully review the following points before using this Tool Call for Chat completion API. + +1. Function Call is now deprecated in favor of Tool Call by OpenAI, hence it's not supported here, you should use Tool Call instead. +2. This API is only supported by Claude 3 model. + +**Example Request** + +```bash +curl $OPENAI_BASE_URL/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [ + { + "role": "user", + "content": "What is the weather like in Shanghai today?" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city or state which is required." + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location" + ] + } + } + }, + { + "type": "function", + "function": { + "name": "get_current_location", + "description": "Use this tool to get the current location if user does not provide a location", + "parameters": { + "type": "object", + "properties": {} + } + } + } + ], + "tool_choice": "auto" +}' +``` + +**Example Response** + +```json +{ + "id": "msg_01PjrKDWhYGsrTNdeqzWd6D9", + "created": 1712543689, + "model": "anthropic.claude-3-sonnet-20240229-v1:0", + "system_fingerprint": "fp", + "choices": [ + { + "index": 0, + "finish_reason": "stop", + "message": { + "role": "assistant", + "tool_calls": [ + { + "id": "0", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\"location\": \"Shanghai\", \"unit\": \"celsius\"}" + } + } + ] + } + } + ], + "object": "chat.completion", + "usage": { + "prompt_tokens": 256, + "completion_tokens": 64, + "total_tokens": 320 + } +} +``` + +You can try it with different questions, such as: +1. Hello, who are you? (No tools are needed) +2. What is the weather like today? (Should use get_current_location tool first) \ No newline at end of file diff --git a/docs/Usage_CN.md b/docs/Usage_CN.md new file mode 100644 index 0000000..27d1a30 --- /dev/null +++ b/docs/Usage_CN.md @@ -0,0 +1,256 @@ +[English](./Usage.md) + +# Usage Guide + +假设您在部署后已设置以下环境变量: + +```bash +export OPENAI_API_KEY= +export OPENAI_BASE_URL= +``` + +## Embedding API + +**重要**: 在使用此代理 API 之前,请仔细阅读以下几点: + +1. 如果您之前使用 OpenAI Embedding模型来创建向量,请注意切换到新模型可能没有那么直接。不同模型具有不同的维度(例如,embed-multilingual-v3.0 有 1024 个维度),即使对于相同的文本,它们也可能产生不同的结果。 +2. 如果您使用 OpenAI Embedding模型传入的是整数编码(例如与 LangChain 一起使用),此方案将尝试使用 `tiktoken` 进行解码以检索原始文本。但是,无法保证解码后的文本准确无误。 +3. 如果您对长文本使用 OpenAI Embedding,您应该验证 Bedrock 模型支持的最大Token数,例如为获得最佳性能,Bedrock 建议将文本长度限制在少于 512 个Token。 + +**Request 示例** + +```bash +curl $OPENAI_BASE_URL/embeddings \ +-H "Authorization: Bearer $OPENAI_API_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "input": "The food was delicious and the waiter...", + "model": "text-embedding-ada-002", + "encoding_format": "float" + }' +``` + +**Response 示例** + +```json +{ + "object": "list", + "data": [ + { + "object": "embedding", + "embedding": [ + -0.02279663, + -0.024612427, + 0.012863159, + ... + 0.01612854, + 0.0038928986 + ], + "index": 0 + } + ], + "model": "cohere.embed-multilingual-v3", + "usage": { + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` + +或者你可以使用OpenAI 的SDK + +```python +from openai import OpenAI + +client = OpenAI() + +def get_embedding(text, model="text-embedding-3-small"): + text = text.replace("\n", " ") + return client.embeddings.create(input=[text], model=model).data[0].embedding + +text = "hello" +# will output like [0.003578186, 0.028717041, 0.031021118, -0.0014066696,...] +print(get_embedding(text)) +``` + +或者 LangChain + +```python +from langchain_openai import OpenAIEmbeddings + +embeddings = OpenAIEmbeddings( + model="text-embedding-3-large", +) +text = "This is a test document." +query_result = embeddings.embed_query(text) +print(query_result[:5]) +doc_result = embeddings.embed_documents([text]) +print(doc_result[0][:5]) +``` + +## Multimodal API + +**重要**:在使用此代理API进行多模态处理之前,请仔细阅读以下几点: + +1. 此API 仅支持Claude 3模型。 +2. 您应确保 Lambda/Fargate 可以公开访问该图片URL。 + +**Request 示例** + +```bash +curl $OPENAI_BASE_URL/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "please identify and count all the objects in this images, list all the names" + }, + { + "type": "image_url", + "image_url": { + "url": "https://github.com/aws-samples/bedrock-access-gateway/blob/main/assets/obj-detect.png?raw=true" + } + } + ] + } + ] +}' +``` + +**Response 示例** + +```json +{ + "id": "msg_01BY3wcz41x7XrKhxY3VzWke", + "created": 1712543069, + "model": "anthropic.claude-3-sonnet-20240229-v1:0", + "system_fingerprint": "fp", + "choices": [ + { + "index": 0, + "finish_reason": "stop", + "message": { + "role": "assistant", + "content": "The image contains the following objects:\n\n1. A peach-colored short-sleeve button-up shirt\n2. An olive green plaid long coat/jacket\n3. A pair of white sneakers or canvas shoes\n4. A brown shoulder bag or purse\n5. A makeup brush or cosmetic applicator\n6. A tube or container (possibly lipstick or lip balm)\n7. A pair of sunglasses\n8. A thought bubble icon\n9. A footprint icon\n10. A leaf or plant icon\n11. A flower icon\n12. A cloud icon\n\nIn total, there are 12 distinct objects depicted in the illustrated scene." + } + } + ], + "object": "chat.completion", + "usage": { + "prompt_tokens": 197, + "completion_tokens": 147, + "total_tokens": 344 + } +} +``` + + +## Tool Call + +**重要**:在使用此代理API进行Tool Call之前,请仔细阅读以下几点: + +1. OpenAI 已经废弃使用Function Call,而推荐使用Tool Call,因此Function Call在此处不受支持,您应该改为Tool Call。 +1. 此API 仅支持Claude 3模型。 + +**Request 示例** + +```bash +curl $OPENAI_BASE_URL/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [ + { + "role": "user", + "content": "What is the weather like in Shanghai today?" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city or state which is required." + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location" + ] + } + } + }, + { + "type": "function", + "function": { + "name": "get_current_location", + "description": "Use this tool to get the current location if user does not provide a location", + "parameters": { + "type": "object", + "properties": {} + } + } + } + ], + "tool_choice": "auto" +}' +``` + +**Response 示例** + +```json +{ + "id": "msg_01PjrKDWhYGsrTNdeqzWd6D9", + "created": 1712543689, + "model": "anthropic.claude-3-sonnet-20240229-v1:0", + "system_fingerprint": "fp", + "choices": [ + { + "index": 0, + "finish_reason": "stop", + "message": { + "role": "assistant", + "tool_calls": [ + { + "id": "0", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\"location\": \"Shanghai\", \"unit\": \"celsius\"}" + } + } + ] + } + } + ], + "object": "chat.completion", + "usage": { + "prompt_tokens": 256, + "completion_tokens": 64, + "total_tokens": 320 + } +} +``` + +You can try it with different questions, such as: +1. Hello, who are you? (No tools are needed) +2. What is the weather like today? (Should use get_current_location tool first) \ No newline at end of file