Metadata-Version: 2.1
Name: arkitect
Version: 0.1.4
Summary: 
Author: wangsen.0914
Author-email: wangsen.0914@bytedance.com
Requires-Python: >=3.8.1,<3.12.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: aiofiles (==23.2.1)
Requires-Dist: fastapi (>=0.100.0,<1.0.0)
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: langchain (>=0.1.0,<=0.2.0)
Requires-Dist: langchain_core (==0.1.52)
Requires-Dist: opentelemetry-api (>=1.22.0,<2.0.0)
Requires-Dist: opentelemetry-exporter-otlp (>=1.22.0,<2.0.0)
Requires-Dist: opentelemetry-sdk (>=1.22.0,<2.0.0)
Requires-Dist: orjson (<3.10.7)
Requires-Dist: pydantic (>=2.0.0,<3.0.0)
Requires-Dist: pytz (==2020.5)
Requires-Dist: structlog (>=23.1.0,<25.0.0)
Requires-Dist: tenacity (==8.3.0)
Requires-Dist: tos (>=2.8.1,<3.0.0)
Requires-Dist: uvicorn (>=0.22.0,<0.30.0)
Requires-Dist: uvloop (>=0.19.0)
Requires-Dist: volcengine-python-sdk (>=1.0.117)
Requires-Dist: websockets (<=13.1)
Description-Content-Type: text/markdown

# 高代码 Python SDK Arkitect

## SDK 介绍

### 概述

高代码 Python SDK Arkitect，面向具有专业开发能力的企业开发者，提供大模型应用开发需要用到的工具集和流程集。借助高代码 SDK Arkitect 和 AI 原型应用代码示例，您能够快速开发和扩展匹配您业务场景的大模型相关应用。

### 框架优势

- **高度定制化：** 提供高代码智能体应用编排方式，灵活服务客户高度定制化和自定义需求。
- **丰富优质的业务工具：** 面向企业客户提供高质量、有保障的业务工具，包括丰富的业务插件库与工具链，支持与先进的大模型进行组合串联，实现一个端到端解决问题的智能体应用。
- **一站式开发与托管服务：** 简化智能体应用部署和管理的流程，增强系统的稳定性。
- **安全可靠：** 提供方舟的安全加固实践，增强业务数据的安全性和保密性，减小数据泄漏或窃取风险。
- **AI 原型应用代码示例：** 开发者可快速上手和扩展的示例，基于示例您可以按需进行定制化开发。

### 应用场景

面向复杂的企业开发场景，搭建高定制化与自定义的智能体应用，赋能大模型在各行业场景的落地应用，实现企业智能化升级。

- **智能驾舱：** 为汽车行业用户提供车载智能交互, 包括角色扮演、聊天、联网查询（天气、视频、新闻等）、车机能力唤起等多功能的融合编排使用。
- **金融服务：** 为金融行业用户提供智能投顾、风险评估等服务，提升金融服务的效率和客户满意度。
- **电商库存管理：** 为电商行业提供高效的库存管理方案。包括商品库存管理与查询、分析与预测需求，保证供应链运营的流畅性和效率。
- **办公助理：** 支持企业客户在办公场景下文档写作、会议管理、数据分析等需求。
- **行业大模型应用：** 企业可根据业务和目标进行定制和拓展。包括但不限于泛互联网、工业、政务、交通、汽车、金融等各行业场景的大模型落地应用。

### 架构设计

![image](./docs/assets/image1.jpeg)

## 支持特性

| 功能点                | 功能简介                                             |
| --------------------- | ---------------------------------------------------- |
| Prompt 渲染及模型调用 | 简化调用模型时，prompt渲染及模型调用结果处理的流程。 |
| 插件调用              | 支持插件本地注册、插件管理及对接FC模型自动化调用。   |
| Trace 监控            | 支持对接otel协议的trace管理及上报。                  |

## 应用列表

| 应用名称                                                 | 应用简介                                                     |
| -------------------------------------------------------- | ------------------------------------------------------------ |
| [互动双语视频生成器](./demohouse/chat2cartoon/README.md) | 只需输入一个主题，就能为你生成引人入胜且富有含义的双语视频。 |
| [视频实时理解](./demohouse/video_analyser/README.md)     | 多模态洞察，基于豆包-视觉理解模型实时视觉与语音理解。        |
| [语音实时通话-青青](demohouse/live_voice_call/README.md) | 嗨，我是你的朋友乔青青，快来和我语音通话吧！                 |

## 快速入门

### 基础聊天

1. 安装 arkitect

   ```bash
   pip install arkitect --index-url https://pypi.org/simple
   ```

2. 登录[方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint?projectName=default)，创建一个推理接入点（Endpoint），推荐使用Doubao-pro-32k [参考文档](https://www.volcengine.com/docs/82379/1399008#_2-%E5%88%9B%E5%BB%BA%E5%9C%A8%E7%BA%BF%E6%8E%A8%E7%90%86%E6%8E%A5%E5%85%A5%E7%82%B9%EF%BC%88endpoint%EF%BC%89)

3. 登录[方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint?projectName=default)，创建一个 API KEY [参考文档](https://www.volcengine.com/docs/82379/1399008#_1-%E8%8E%B7%E5%8F%96%E5%B9%B6%E9%85%8D%E7%BD%AE-api-key)

4. 创建`main.py`，修改文件中的 endpoint_id 为您新创建的推理接入点 ID。

```python
"""
默认llm逻辑
"""
import os
from typing import AsyncIterable, Union

from arkitect.core.component.llm import BaseChatLanguageModel

from arkitect.core.component.llm.model import (
    ArkChatCompletionChunk,
    ArkChatParameters,
    ArkChatRequest,
    ArkChatResponse,
    Response,
)
from arkitect.launcher.local.serve import launch_serve
from arkitect.telemetry.trace import task

endpoint_id = "<YOUR ENDPOINT ID>"

@task()
async def default_model_calling(
    request: ArkChatRequest,
) -> AsyncIterable[Union[ArkChatCompletionChunk, ArkChatResponse]]:
    parameters = ArkChatParameters(**request.__dict__)
    llm = BaseChatLanguageModel(
        endpoint_id=endpoint_id,
        messages=request.messages,
        parameters=parameters,
    )
    if request.stream:
        async for resp in llm.astream():
            yield resp
    else:
        yield await llm.arun()

@task()
async def main(request: ArkChatRequest) -> AsyncIterable[Response]:
    async for resp in default_model_calling(request):
        yield resp

if __name__ == "__main__":
    port = os.getenv("_FAAS_RUNTIME_PORT")
    launch_serve(
        package_path="main",
        port=int(port) if port else 8080,
        health_check_path="/v1/ping",
        endpoint_path="/api/v3/bots/chat/completions",
        clients={},
    )

```

5. 设置 APIKEY 并启动后端

```bash
export ARK_API_KEY=<YOUR APIKEY>
python3 main.py
```

6. 发起请求

```shell
curl --location 'http://localhost:8080/api/v3/bots/chat/completions' \
--header 'Content-Type: application/json' \
--data '{
    "model": "my-bot",
    "messages": [
        {
            "role": "user",
            "content": "介绍你自己啊"
        }
    ]
}'
```

预期返回如下：

```json
{
    "error": null,
    "id": "02173*************************************",
    "choices": [
        {
            "finish_reason": "stop",
            "moderation_hit_type": null,
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "我是豆包，由字节跳动公司开发。我能陪你谈天说地，无论是解答各种知识疑问，比如科学原理、历史事件；还是探讨文化艺术、娱乐八卦；亦或是在生活问题上给你提供建议和思路，像制定旅行计划、规划健身安排、分享美食烹饪方法等，我都很在行。随时都可以和我交流，我时刻准备着为你排忧解难、畅聊想法！  ",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null,
                "audio": null
            }
        }
    ],
    "created": 1736847939,
    "model": "doubao-pro-32k-241215",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 95,
        "prompt_tokens": 12,
        "total_tokens": 107,
        "prompt_tokens_details": {
            "cached_tokens": 0
        }
    },
    "metadata": null
}
```

### 插件调用

1. 安装 arkitect

   ```bash
   pip install arkitect --index-url https://pypi.org/simple
   ```

2. 登录[方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint?projectName=default)，创建一个推理接入点（Endpoint），请选择带 Function-call 能力的模型，推荐使用doubao-pro-32k functioncall-241028 [参考文档](https://www.volcengine.com/docs/82379/1399008#_2-%E5%88%9B%E5%BB%BA%E5%9C%A8%E7%BA%BF%E6%8E%A8%E7%90%86%E6%8E%A5%E5%85%A5%E7%82%B9%EF%BC%88endpoint%EF%BC%89)

3. 登录[方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint?projectName=default)，创建一个 API KEY [参考文档](https://www.volcengine.com/docs/82379/1399008#_1-%E8%8E%B7%E5%8F%96%E5%B9%B6%E9%85%8D%E7%BD%AE-api-key)

4. 创建`main.py`，修改文件中的 endpoint_id 为您新创建的推理接入点 ID。

```python
"""
fc+llm
"""

import os
from typing import AsyncIterable, Union

from arkitect.core.component.llm import BaseChatLanguageModel

from arkitect.core.component.llm.model import (
    ArkChatCompletionChunk,
    ArkChatParameters,
    ArkChatRequest,
    ArkChatResponse,
    Response,
)
from arkitect.core.component.tool import Calculator, ToolPool
from arkitect.launcher.local.serve import launch_serve
from arkitect.telemetry.trace import task

endpoint_id = "<YOUR ENDPOINT ID>"

@task()
async def default_model_calling(
    request: ArkChatRequest,
) -> AsyncIterable[Union[ArkChatCompletionChunk, ArkChatResponse]]:
    parameters = ArkChatParameters(**request.__dict__)
    ToolPool.register(Calculator())

    llm = BaseChatLanguageModel(
        endpoint_id=endpoint_id,
        messages=request.messages,
        parameters=parameters,
    )
    if request.stream:
        async for resp in llm.astream(functions=ToolPool.all()):
            yield resp
    else:
        yield await llm.arun(functions=ToolPool.all())


@task()
async def main(request: ArkChatRequest) -> AsyncIterable[Response]:
    async for resp in default_model_calling(request):
        yield resp


if __name__ == "__main__":
    port = os.getenv("_FAAS_RUNTIME_PORT")
    launch_serve(
        package_path="main",
        port=int(port) if port else 8080,
        health_check_path="/v1/ping",
        endpoint_path="/api/v3/bots/chat/completions",
        clients={},
    )

```

5. 设置 APIKEY 并启动后端

```bash
export ARK_API_KEY=<YOUR APIKEY>
python3 main.py
```

6. 发起请求

```shell
curl --location 'http://localhost:8080/api/v3/bots/chat/completions' \
--header 'Content-Type: application/json' \
--data '{
    "model": "my-bot",
    "messages": [
        {
            "role": "user",
            "content": "老王要养马,他有这样一池水:如果养马30匹,8天可可以把水喝光;如果养马25匹,12天把水喝光。老王要养马23匹,那么几天后他要为马找水喝?"
        }
    ]
}'
```

预期返回如下：

```json
{
    "error": null,
    "id": "0xxxxxxxxx",
    "choices": [
        {
            "finish_reason": "stop",
            "moderation_hit_type": null,
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "\n首先计算出每天新增的水量，再算出池中原有的水量，最后根据养马数量计算水可以喝的天数，调用 `Calculator/Calculator` 工具进行计算。\n\n假设每匹马每天的饮水量为\\(1\\)份，我们先来求出每天新增的水量。\n\n\n\n假设每匹马每天的饮水量为1份。30匹马8天的饮水量为$30\\times8=240$份，25匹马12天的饮水量为$25\\times12=300$份。那么12天的总饮水量比8天的总饮水量多了$300-240=60$份，这60份水是$12-8=4$天新增加的水量，所以每天新增加的水量为$60\\div4=15$份。则水池原有的水量为$30\\times8-15\\times8=120$份。如果养23匹马，每天实际消耗原水池的水量为$23-15=8$份，所以喝完水池里的水需要$120\\div8=15$天\n15天后他要为马找水喝。",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null,
                "audio": null
            }
        }
    ],
    "created": 1737022804,
    "model": "doubao-pro-32k-241215",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 558,
        "prompt_tokens": 1361,
        "total_tokens": 1919,
        "prompt_tokens_details": {
            "cached_tokens": 0
        }
    },
    "metadata": null
}
```

## 常见问题

### arkitect 和 volcenginesdkarkruntime 的区别?

- arkitect 是方舟高代码智能体 SDK，面向具有专业开发能力的企业开发者，提供智能体开发需要用到的工具集和流程集。
- volcenginesdkarkruntime 是对方舟的 API 进行封装，方便用户通过 API 创建、管理和调用大模型相关服务。

## LICENSE说明
- ```./arkitect``` 目录下代码遵循 [Apache 2.0](./APACHE_LICENSE) 许可.
- ```./demohouse``` 目录下代码遵循[【火山方舟】原型应用软件自用许可协议](ARK_LICENSE.md) 许可。
