diff --git a/README.md b/README.md index 7c104ca..e1e6163 100644 --- a/README.md +++ b/README.md @@ -77,54 +77,52 @@ If you wish to use smart devices to access your agents, we provide a smartphone ## 🚀 Quick Start ### Hello World -1. **Adjust Python Path**: The script modifies the Python path to ensure it can locate necessary modules. Verify the path is correct for your setup: +### 1、Configuration - ```python - CURRENT_PATH = Path(__file__).parents[0] - sys.path.append(os.path.abspath(CURRENT_PATH.joinpath('../../'))) +The container.yaml file is a configuration file that manages dependencies and settings for different components of the system. To set up your configuration: + +1. Generate the container.yaml file: + ```bash + cd examples/step2_outfit_with_switch + python compile_container.py ``` - - **CURRENT_PATH**: This is the path to the current directory. - - **sys.path.append**: This adds the path to the current directory to the Python path. This is to allow importing packages from the examples directory later. + This will create a container.yaml file with default settings under `examples/step2_outfit_with_switch`. -2. **Initialize Logging**: The script sets up logging to track application events. You can adjust the logging level (`INFO`, `DEBUG`, etc.) as needed: - ```python - logging.init_logger("omagent", "omagent", level="INFO") - ``` +2. Configure your LLM settings in `configs/llms/gpt.yml` and `configs/llms/text_res.yml`: -3. **Create and Execute Workflow**: The script creates a workflow and adds a task to it. It then starts the agent client to execute the workflow: - - ```python - from examples.step1_simpleVQA.agent.simple_vqa.simple_vqa import SimpleVQA - from examples.step1_simpleVQA.agent.input_interface.input_interface import InputIterface - - workflow = ConductorWorkflow(name='example1') - task1 = simple_task(task_def_name='InputIterface', task_reference_name='input_task') - task2 = simple_task(task_def_name='SimpleVQA', task_reference_name='simple_vqa', inputs={'user_instruction': task1.output('user_instruction')}) - workflow >> task1 >> task2 - - - workflow.register(True) - - agent_client = DefaultClient(interactor=workflow, config_path='examples/step1_simpleVQA/configs', workers=[InputIterface()]) - agent_client.start_interactor() + - Set your OpenAI API key or compatible endpoint through environment variable or by directly modifying the yml file + ```bash + export custom_openai_key="your_openai_api_key" + export custom_openai_endpoint="your_openai_endpoint" ``` - - **Workflow**: Defines the sequence of tasks. 'name' is the name of the workflow， please make sure it is unique. - - **Task**: Represents a unit of work, in this case, we use SimpleVQA from the examples. 'task_def_name' represents the corresponding class name, 'task_reference_name' represents the name in the conductor. - - **AppClient**: Starts the agent client to execute the workflow. Here we use AppClient, if you want to use CLI, please use DefaultClient. - - **agent_client.start_interactor()**: This will start the worker corresponding to the registered task, in this case, it will start SimpleVQA and wait for the conductor's scheduling. +3. Update settings in the generated `container.yaml`: + - Configure Redis connection settings, including host, port, credentials, and both `redis_stream_client` and `redis_stm_client` sections. + - Update the Conductor server URL under conductor_config section + - Adjust any other component settings as needed + +For more information about the container.yaml configuration, please refer to the [container module](./docs/concepts/container.md) + +### 2、Running the Example -4. **Run the Script** - Execute the script using Python: +1. Run the outfit with switch example: + + For terminal/CLI usage: Input and output are in the terminal window ```bash + cd examples/step2_outfit_with_switch + python run_cli.py + ``` + + For app/GUI usage: Input and output are in the app + ```bash + cd examples/step2_outfit_with_switch python run_app.py - ``` - **Ensure the workflow engine is running before executing the script.** + ``` -### 🏗 Architecture +## 🏗 Architecture The design architecture of OmAgent adheres to three fundamental principles: 1. Graph-based workflow orchestration; 2. Native multimodality; diff --git a/README_ZH.md b/README_ZH.md index 27627ad..de18c50 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -75,53 +75,49 @@ docker compose -f docker/conductor/docker-compose.yml up -d ## 🚀 快速开始 ### Hello World -1. **调整Python路径**：该脚本修改Python路径，以确保可以定位必要的模块。请验证路径对于您的设置是否正确： +### 1、配置 - ```python - CURRENT_PATH = Path(__file__).parents[0] - sys.path.append(os.path.abspath(CURRENT_PATH.joinpath('../../'))) +`container.yaml` 文件是一个管理系统中不同组件的依赖和设置的配置文件。按以下步骤设置您的配置： + +1. 生成 `container.yaml` 文件： + ```bash + cd examples/step2_outfit_with_switch + python compile_container.py ``` - - **CURRENT_PATH**：这是当前目录的路径。 - - **sys.path.append**：这将当前目录的路径添加到Python路径中。这是为了允许稍后从示例目录导入包。 + 这将在 `examples/step2_outfit_with_switch` 下创建一个具有默认设置的 `container.yaml` 文件。 -2. **初始化日志记录**：该脚本设置日志记录以跟踪应用程序事件。您可以根据需要调整日志记录级别（`INFO`，`DEBUG`等）： +2. 在 `configs/llms/gpt.yml` 和 `configs/llms/text_res.yml` 中配置您的 LLM 设置： - ```python - logging.init_logger("omagent", "omagent", level="INFO") + - 通过环境变量或直接修改 yml 文件来设置您的 OpenAI API 密钥或兼容的 endpoint + ```bash + export custom_openai_key="your_openai_api_key" + export custom_openai_endpoint="your_openai_endpoint" ``` -3. **创建和执行工作流**：该脚本创建一个工作流并向其中添加一个任务。然后启动代理客户端以执行工作流： - - ```python - from examples.step1_simpleVQA.agent.simple_vqa.simple_vqa import SimpleVQA - from examples.step1_simpleVQA.agent.input_interface.input_interface import InputIterface - - workflow = ConductorWorkflow(name='example1') - task1 = simple_task(task_def_name='InputIterface', task_reference_name='input_task') - task2 = simple_task(task_def_name='SimpleVQA', task_reference_name='simple_vqa', inputs={'user_instruction': task1.output('user_instruction')}) - workflow >> task1 >> task2 - - - workflow.register(True) - - agent_client = DefaultClient(interactor=workflow, config_path='examples/step1_simpleVQA/configs', workers=[InputIterface()]) - agent_client.start_interactor() - ``` +3. 更新生成的 `container.yaml` 中的设置： + - 配置 Redis 连接设置，主要是主机地址、端口、密码凭证，包括 `redis_stream_client` 和 `redis_stm_client` 部分都要进行设置。 + - 在 `conductor_config` 下更新 Conductor 服务器的 URL + - 根据需要调整其他组件设置 + +有关 `container.yaml` 配置的更多信息，请参阅 [container 模块](./docs/concepts/container.md) - - **Workflow**：定义任务序列。'name'是工作流的名称， 请保证唯一性。 - - **Task**：表示工作单元，在本例中，我们使用来自示例的SimpleVQA。'task_def_name'表示对应的类名，'task_reference_name'表示在conductor中的名称。 - - **AppClient**：启动代理客户端以执行工作流。这里我们使用AppClient，如果您想使用CLI，请使用DefaultClient。 - - **agent_client.start_interactor()**：这将启动与注册任务对应的工作器，在本例中，它将启动SimpleVQA并等待conductor的调度。 +### 2、运行示例 + +1. 运行 outfit with switch 示例： + + 对于终端/CLI 使用：输入和输出在终端窗口中 + ```bash + cd examples/step2_outfit_with_switch + python run_cli.py + ``` -4. 配置参数 - TODO:修改配置文件或设置环境变量 -5. **运行脚本** - 使用Python执行脚本： + 对于app/GUI 使用：输入和输出在应用程序中 ```bash + cd examples/step2_outfit_with_switch python run_app.py ``` - **在执行脚本之前，请确保工作流引擎已经部署并正在运行。** +## 🏗 架构 OmAgent的设计架构遵循三项基本原则： 1. 基于图的工作流编排； 2. 本地多模态； diff --git a/examples/step2_outfit_with_switch/configs/tools/websearch.yml b/examples/step2_outfit_with_switch/configs/tools/websearch.yml index bc83430..5544864 100644 --- a/examples/step2_outfit_with_switch/configs/tools/websearch.yml +++ b/examples/step2_outfit_with_switch/configs/tools/websearch.yml @@ -1,5 +1,5 @@ llm: ${sub| text_res} tools: - name: WebSearch - bing_api_key: ${env| bing_api_key, your_bing_api_key} + bing_api_key: ${env| bing_api_key, null} llm: ${sub|text_res} \ No newline at end of file diff --git a/examples/step3_outfit_with_loop/configs/tools/websearch.yml b/examples/step3_outfit_with_loop/configs/tools/websearch.yml index bc83430..5544864 100644 --- a/examples/step3_outfit_with_loop/configs/tools/websearch.yml +++ b/examples/step3_outfit_with_loop/configs/tools/websearch.yml @@ -1,5 +1,5 @@ llm: ${sub| text_res} tools: - name: WebSearch - bing_api_key: ${env| bing_api_key, your_bing_api_key} + bing_api_key: ${env| bing_api_key, null} llm: ${sub|text_res} \ No newline at end of file diff --git a/examples/step4_outfit_with_ltm/outfit_from_storage/configs/tools/websearch.yml b/examples/step4_outfit_with_ltm/outfit_from_storage/configs/tools/websearch.yml index 73cc0c0..e33325e 100644 --- a/examples/step4_outfit_with_ltm/outfit_from_storage/configs/tools/websearch.yml +++ b/examples/step4_outfit_with_ltm/outfit_from_storage/configs/tools/websearch.yml @@ -1,5 +1,5 @@ llm: ${sub| text_res} tools: - name: WebSearch - bing_api_key: ${env| bing_api_key, bing_api_key} + bing_api_key: ${env| bing_api_key, null} llm: ${sub| text_res} \ No newline at end of file diff --git a/omagent-core/src/omagent_core/utils/build.py b/omagent-core/src/omagent_core/utils/build.py index c0ec770..a68c93e 100644 --- a/omagent-core/src/omagent_core/utils/build.py +++ b/omagent-core/src/omagent_core/utils/build.py @@ -82,8 +82,11 @@ def prep_config(sub_config: dict, config: dict, forbid_keys: list): sub_config[key] = env_value elif not env_value and default_value: sub_config[key] =default_value.strip() + if sub_config[key] == "null" or sub_config[key] == "~": + sub_config[key] = None else: raise ValueError(f'Environmental variable {env_key} need to be set.') + elif isinstance(conf, dict): prep_config(sub_config[key], config, forbid_keys)