Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

docs: Polish model setup doc for better onboarding experience (#1002)

LiangxuanZhao8a2f0b728004
diff --git a/camel/models/openai_compatibility_model.py b/camel/models/openai_compatibility_model.py
index f31a66527..2e43a2ae0 100644
--- a/camel/models/openai_compatibility_model.py
+++ b/camel/models/openai_compatibility_model.py
@@ -12,6 +12,7 @@
# limitations under the License.
# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+import os
from typing import Any, Dict, List, Optional, Union
from openai import OpenAI, Stream
@@ -25,14 +26,14 @@ from camel.utils import (
class OpenAICompatibilityModel:
- r"""Constructor for model backend supporting OpenAI compatibility."""
+ r"""LLM API served by OpenAI-compatible providers."""
def __init__(
self,
model_type: str,
model_config_dict: Dict[str, Any],
- api_key: str,
- url: str,
+ api_key: Optional[str] = None,
+ url: Optional[str] = None,
token_counter: Optional[BaseTokenCounter] = None,
) -> None:
r"""Constructor for model backend.
@@ -51,13 +52,25 @@ class OpenAICompatibilityModel:
"""
self.model_type = model_type
self.model_config_dict = model_config_dict
- self._token_counter = token_counter
+ self._url = url or os.environ.get("OPENAI_COMPATIBILIY_API_BASE_URL")
+ self._api_key = api_key or os.environ.get(
+ "OPENAI_COMPATIBILIY_API_KEY"
+ )
+ if self._url is None:
+ raise ValueError(
+ "For OpenAI-compatible models, you must provide the `url`."
+ )
+ if self._api_key is None:
+ raise ValueError(
+ "For OpenAI-compatible models, you must provide the `api_key`."
+ )
self._client = OpenAI(
timeout=60,
max_retries=3,
- api_key=api_key,
- base_url=url,
+ base_url=self._url,
+ api_key=self._api_key,
)
+ self._token_counter = token_counter
def run(
self,
diff --git a/docs/get_started/installation.md b/docs/get_started/installation.md
new file mode 100644
index 000000000..e2bd5e22e
--- /dev/null
+++ b/docs/get_started/installation.md
@@ -0,0 +1,73 @@
+# Installation
+
+## [Option 1] Install from PyPI
+To install the base CAMEL library:
+```bash
+pip install camel-ai
+```
+Some features require extra dependencies:
+- To install with all dependencies:
+ ```bash
+ pip install 'camel-ai[all]'
+ ```
+- To use the HuggingFace agents:
+ ```bash
+ pip install 'camel-ai[huggingface-agent]'
+ ```
+- To enable RAG or use agent memory:
+ ```bash
+ pip install 'camel-ai[tools]'
+ ```
+
+## [Option 2] Install from Source
+### Install from Source with Poetry
+```bash
+# Make sure your python version is later than 3.10
+# You can use pyenv to manage multiple python verisons in your sytstem
+
+# Clone github repo
+git clone https://github.com/camel-ai/camel.git
+
+# Change directory into project directory
+cd camel
+
+# If you didn't install peotry before
+pip install poetry # (Optional)
+
+# We suggest using python 3.10
+poetry env use python3.10 # (Optional)
+
+# Activate CAMEL virtual environment
+poetry shell
+
+# Install the base CAMEL library
+# It takes about 90 seconds
+poetry install
+
+# Install CAMEL with all dependencies
+poetry install -E all # (Optional)
+
+# Exit the virtual environment
+exit
+```
+
+### Install from Source with Conda and Pip
+```bash
+# Create a conda virtual environment
+conda create --name camel python=3.10
+
+# Activate CAMEL conda environment
+conda activate camel
+
+# Clone github repo
+git clone -b v0.2.1a https://github.com/camel-ai/camel.git
+
+# Change directory into project directory
+cd camel
+
+# Install CAMEL from source
+pip install -e .
+
+# Or if you want to use all other extra packages
+pip install -e '.[all]' # (Optional)
+```
diff --git a/docs/get_started/setup.md b/docs/get_started/setup.md
index 00bad6d15..03d07accf 100644
--- a/docs/get_started/setup.md
+++ b/docs/get_started/setup.md
@@ -1,91 +1,15 @@
-# Installation and Setup
-## 🕹 Installation
-
-### [Option 1] Install from PyPI
-To install the base CAMEL library:
-```bash
-pip install camel-ai
-```
-Some features require extra dependencies:
-- To install with all dependencies:
- ```bash
- pip install 'camel-ai[all]'
- ```
-- To use the HuggingFace agents:
- ```bash
- pip install 'camel-ai[huggingface-agent]'
- ```
-- To enable RAG or use agent memory:
- ```bash
- pip install 'camel-ai[tools]'
- ```
-
-### [Option 2] Install from Source
-#### Install from Source with Poetry
-```bash
-# Make sure your python version is later than 3.10
-# You can use pyenv to manage multiple python verisons in your sytstem
-
-# Clone github repo
-git clone https://github.com/camel-ai/camel.git
-
-# Change directory into project directory
-cd camel
-
-# If you didn't install peotry before
-pip install poetry # (Optional)
-
-# We suggest using python 3.10
-poetry env use python3.10 # (Optional)
-
-# Activate CAMEL virtual environment
-poetry shell
-
-# Install the base CAMEL library
-# It takes about 90 seconds
-poetry install
-
-# Install CAMEL with all dependencies
-poetry install -E all # (Optional)
-
-# Exit the virtual environment
-exit
-```
-
-#### Install from Source with Conda and Pip
-```bash
-# Create a conda virtual environment
-conda create --name camel python=3.10
-
-# Activate CAMEL conda environment
-conda activate camel
-
-# Clone github repo
-git clone -b v0.2.1a https://github.com/camel-ai/camel.git
-
-# Change directory into project directory
-cd camel
-
-# Install CAMEL from source
-pip install -e .
-
-# Or if you want to use all other extra packages
-pip install -e '.[all]' # (Optional)
-```
-
-
-## 🕹 API Setup
+# API Setup
Our agents can be deployed with either OpenAI API or your local models.
-### [Option 1] Using OpenAI API
-Assessing the OpenAI API requires the API key, which you may obtained from [here](https://platform.openai.com/account/api-keys). We here provide instructions for different OS.
+## [Option 1] Using OpenAI API
+Accessing the OpenAI API requires the API key, which you could get from [here](https://platform.openai.com/account/api-keys). We here provide instructions for different OS.
-#### Unix-like System (Linux / MacOS)
+### Unix-like System (Linux / MacOS)
```bash
echo 'export OPENAI_API_KEY="your_api_key"' >> ~/.zshrc
-# If you are using other proxy services like Azure
-echo 'export OPENAI_API_BASE_URL="your_base_url"' >> ~/.zshrc # (Optional)
+# # If you are using other proxy services like Azure [TODO]
+# echo 'export OPENAI_API_BASE_URL="your_base_url"' >> ~/.zshrc # (Optional)
# Let the change take place
source ~/.zshrc
@@ -93,13 +17,13 @@ source ~/.zshrc
Replace `~/.zshrc` with `~/.bashrc` if you are using bash.
-#### Windows
+### Windows
If you are using Command Prompt:
```bash
set OPENAI_API_KEY="your_api_key"
-# If you are using other proxy services like Azure
-set OPENAI_API_BASE_URL="your_base_url" # (Optional)
+# If you are using other proxy services like Azure [TODO]
+# set OPENAI_API_BASE_URL="your_base_url" # (Optional)
```
Or if you are using PowerShell:
```powershell
@@ -110,68 +34,30 @@ $env:OPENAI_API_BASE_URL="your_base_url" # (Optional)
```
These commands on Windows will set the environment variable for the duration of that particular Command Prompt or PowerShell session only. You may use `setx` or change the system properties dialog for the change to take place in all the new sessions.
+### General method
-### [Option 2] Using Local Models
-In the current landscape, for those seeking highly stable content generation, OpenAI's GPT-3.5 turbo, GPT-4o are often recommended. However, the field is rich with many other outstanding open-source models that also yield commendable results. CAMEL can support developers to delve into integrating these open-source large language models (LLMs) to achieve project outputs based on unique input ideas.
-
-#### Example: Using Ollama to set Llama 3 locally
+Create a file named `.env` in your project directory, with the following setting.
-- Download [Ollama](https://ollama.com/download).
-- After setting up Ollama, pull the Llama3 model by typing the following command into the terminal:
```bash
-ollama pull llama3
+OPENAI_API_KEY=<your-openai-api-key>
```
-- Create a ModelFile similar the one below in your project directory.
-```bash
-FROM llama3
-# Set parameters
-PARAMETER temperature 0.8
-PARAMETER stop Result
+Then, load the environment variables in your python script:
-# Sets a custom system message to specify the behavior of the chat assistant
+```python
+from dotenv import load_dotenv
+import os
-# Leaving it blank for now.
+load_dotenv()
-SYSTEM """ """
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
```
-- Create a script to get the base model (llama3) and create a custom model using the ModelFile above. Save this as a .sh file:
-```bash
-#!/bin/zsh
-# variables
-model_name="llama3"
-custom_model_name="camel-llama3"
-#get the base model
-ollama pull $model_name
+## [Option 2] Using other APIs
+
+If you are using other APIs that are not provided by OpenAI, you can refer to [Models/Using Models by API calling](../key_modules/models.md#using-models-by-api-calling)
+
+## [Option 3] Using Local Models
+If you are using local models, you can refer to [Models/Using Local Models](../key_modules/models.md#using-on-device-open-source-models)
-#create the model file
-ollama create $custom_model_name -f ./Llama3ModelFile
-```
-- Navigate to the directory where the script and ModelFile are located and run the script. Enjoy your Llama3 model, enhanced by CAMEL's excellent agents.
-```python
-from camel.agents import ChatAgent
-from camel.messages import BaseMessage
-from camel.models import ModelFactory
-from camel.types import ModelPlatformType
-
-ollama_model = ModelFactory.create(
- model_platform=ModelPlatformType.OLLAMA,
- model_type="llama3",
- url="http://localhost:11434/v1",
- model_config_dict={"temperature": 0.4},
-)
-
-assistant_sys_msg = BaseMessage.make_assistant_message(
- role_name="Assistant",
- content="You are a helpful assistant.",
-)
-agent = ChatAgent(assistant_sys_msg, model=ollama_model, token_limit=4096)
-
-user_msg = BaseMessage.make_user_message(
- role_name="User", content="Say hi to CAMEL"
-)
-assistant_response = agent.step(user_msg)
-print(assistant_response.msg.content)
-```
diff --git a/docs/index.rst b/docs/index.rst
index 80ff86634..e5f178f14 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@ Main Documentation
:caption: Get Started
:name: getting_started
+ get_started/installation.md
get_started/setup.md
.. toctree::
diff --git a/docs/key_modules/models.md b/docs/key_modules/models.md
index ff8703f4a..82863917f 100644
--- a/docs/key_modules/models.md
+++ b/docs/key_modules/models.md
@@ -21,6 +21,7 @@ The following table lists currently supported model platforms by CAMEL.
| Azure OpenAI | gpt-4-turbo | Y |
| Azure OpenAI | gpt-4 | Y |
| Azure OpenAI | gpt-3.5-turbo | Y |
+| OpenAI Compatible | Depends on the provider | ----- |
| Mistral AI | mistral-large-2 | N |
| Mistral AI | open-mistral-nemo | N |
| Mistral AI | codestral | N |
@@ -49,9 +50,9 @@ The following table lists currently supported model platforms by CAMEL.
| Together AI | https://docs.together.ai/docs/chat-models | ----- |
| LiteLLM | https://docs.litellm.ai/docs/providers | ----- |
-## 3. Model Calling Template
+## 3. Using Models by API calling
-Here is the example code to use a chosen model. To utilize a different model, you can simply change three parameters the define your model to be used: `model_platform`, `model_type`, `model_config_dict` .
+Here is an example code to use a specific model (gpt-4o-mini). If you want to use another model, you can simply change these three parameters: `model_platform`, `model_type`, `model_config_dict` .
```python
from camel.models import ModelFactory
@@ -69,15 +70,28 @@ model = ModelFactory.create(
# Define an assitant message
system_msg = BaseMessage.make_assistant_message(
- role_name="Assistant",
- content="You are a helpful assistant.",
+ role_name="Assistant",
+ content="You are a helpful assistant.",
)
# Initialize the agent
ChatAgent(system_msg, model=model)
```
-## 4. Open Source LLMs
+And if you want to use an OpenAI-compatible API, you can replace the `model` with the following code:
+
+```python
+from camel.models.openai_compatibility_model import OpenAICompatibilityModel
+
+model = OpenAICompatibilityModel(
+ model_type="a-string-representing-the-model-type",
+ model_config_dict={"max_tokens": 4096}, # and other parameters you want
+ url=os.environ.get("OPENAI_COMPATIBILIY_API_BASE_URL"),
+ api_key=os.environ.get("OPENAI_COMPATIBILIY_API_KEY"),
+)
+```
+
+## 4. Using On-Device Open Source Models
In the current landscape, for those seeking highly stable content generation, OpenAI’s gpt-4o-mini, gpt-4o are often recommended. However, the field is rich with many other outstanding open-source models that also yield commendable results. CAMEL can support developers to delve into integrating these open-source large language models (LLMs) to achieve project outputs based on unique input ideas.
While proprietary models like gpt-4o-mini and gpt-4o have set high standards for content generation, open-source alternatives offer viable solutions for experimentation and practical use. These models, supported by active communities and continuous improvements, provide flexibility and cost-effectiveness for developers and researchers.