github/autogen
1
1
Fork 0
mirror of https://github.com/microsoft/autogen.git synced 2026-04-20 03:02:16 -04:00
Code Issues Packages Projects Releases Wiki Activity

Docker Documentation (#1251)

Browse Source 
* Updates to the Dockerfiles making them more secure. update to the installation.md file and a start.sh file for the Dockerfile.dev to start the document server. Not ready for pull request.

* updates to the docker documentation

* clean up before commit

* added docker instructions on how to test  documentation prior to commit.

* fixed the title heading in the installation.md

* removed alternate yarn install from Dockerfile.dev

* Update sidebars.js

removed un-related change from website/sidebars.js

* cleaned up the lint errors from the pre-commit-check.

* removed bad edit from sidebars.js

* fixing git conflict with sidebars.js file

* Update Installation.md

added the missing sections back. However, do we still want the docker section under the Optional Dependencies? That looks like it would go better in the Dockerfiles.md file.

* Update Installation.md

Added mount your code back and added mount your directory for better clarity.

* Update Installation.md

Lint cleanup

* Update Installation.md

removed the relative path to samples/dockers/Dockerfiles.md with a proper URL to where it will exist

* fixed bad link to Dockerfiles.md

* Fix trailing whitespace and formatting issues

* Update link to Dockerfiles.md

* somtimes its really hard to find that lost i.

* trailing whitespace and EOF issues resolved

* fixed broken link

* trailing space an broken link

* removed broken links. will update one merged.

* fixed glaring error about building an image from a particular branch Contribute.md

* removed tic mark typo from contribute.md

---------

Co-authored-by: Todd W Bucy <todd.bucy@rackspace>
This commit is contained in:
R3d91ll
2024-01-15 11:15:59 -06:00
committed by GitHub
parent e6325a402a
commit 135bca41de
6 changed files with 343 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
samples/dockers/Dockerfile.base
View File

@@ -1,21 +1,26 @@
FROM python:3.11-slim-bookworm
RUN : \
&& apt-get update \
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
software-properties-common \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
python3-venv \
software-properties-common sudo\
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/* \
&& :
&& rm -rf /var/lib/apt/lists/*
RUN python3 -m venv /venv
ENV PATH=/venv/bin:$PATH
EXPOSE 8081
# Setup a non-root user 'autogen' with sudo access
RUN adduser --disabled-password --gecos '' autogen
RUN adduser autogen sudo
RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
USER autogen
WORKDIR /home/autogen
# Set environment variable if needed
# ENV OPENAI_API_KEY="{OpenAI-API-Key}"
RUN cd /venv; pip install pyautogen
# Pre-load popular packages as per https://learnpython.com/blog/most-popular-python-packages/
RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4
RUN pip install pyautogen numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4
ENTRYPOINT []
# Expose port
# EXPOSE 8081
# Start Command
CMD [ "/bin/bash" ]

41
samples/dockers/Dockerfile.dev
View File

@@ -1,33 +1,42 @@
# basic setup
# Basic setup
FROM python:3.11-slim-bookworm
# Update and install necessary packages
RUN apt-get update && apt-get -y update
RUN apt-get install -y sudo git npm
# added vim and nano for convenience
RUN apt-get install -y sudo git npm vim nano curl
# Setup user to not run as root
RUN adduser --disabled-password --gecos '' autogen-dev
RUN adduser autogen-dev sudo
# Setup a non-root user 'autogen' with sudo access
RUN adduser --disabled-password --gecos '' autogen
RUN adduser autogen sudo
RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
USER autogen-dev
USER autogen
WORKDIR /home/autogen
# Pull repo
RUN cd /home/autogen-dev && git clone https://github.com/microsoft/autogen.git
WORKDIR /home/autogen-dev/autogen
# Set environment variable
# ENV OPENAI_API_KEY="{OpenAI-API-Key}"
# Install autogen in editable mode (Note: extra components can be installed if needed)
# Clone the AutoGen repository
RUN git clone https://github.com/microsoft/autogen.git /home/autogen/autogen
WORKDIR /home/autogen/autogen
# Install AutoGen in editable mode with extra components
RUN sudo pip install -e .[test,teachable,lmm,retrievechat,mathchat,blendsearch]
# Install precommit hooks
# Install pre-commit hooks
RUN pre-commit install
# For docs
# Setup Docusaurus and Yarn for the documentation website
RUN sudo npm install --global yarn
RUN sudo pip install pydoc-markdown
RUN cd website
RUN yarn install --frozen-lockfile --ignore-engines
# Pre-load popular packages as per https://learnpython.com/blog/most-popular-python-packages/
# Exposes the Yarn port for Docusaurus
EXPOSE 3000
# Pre-load popular Python packages
RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4
# override default image starting point
CMD /bin/bash
ENTRYPOINT []
# Set the default command to bash
CMD ["/bin/bash"]

34
samples/dockers/Dockerfile.full
View File

@@ -1,21 +1,29 @@
FROM python:3.11-slim-bookworm
RUN : \
&& apt-get update \
# Update and install dependencies
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
software-properties-common \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
python3-venv \
software-properties-common sudo\
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/* \
&& :
&& rm -rf /var/lib/apt/lists/*
RUN python3 -m venv /venv
ENV PATH=/venv/bin:$PATH
EXPOSE 8081
# Setup a non-root user 'autogen' with sudo access
RUN adduser --disabled-password --gecos '' autogen
RUN adduser autogen sudo
RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
USER autogen
WORKDIR /home/autogen
RUN cd /venv; pip install pyautogen[teachable,lmm,retrievechat,mathchat,blendsearch] autogenra
# Pre-load popular packages as per https://learnpython.com/blog/most-popular-python-packages/
# Set environment variable if needed
# ENV OPENAI_API_KEY="{OpenAI-API-Key}"
# Install Python packages
RUN pip install --upgrade pip
RUN pip install pyautogen[teachable,lmm,retrievechat,mathchat,blendsearch] autogenra
RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4
ENTRYPOINT []
# Expose port
EXPOSE 8081
# Start Command
CMD ["/bin/bash"]

81
samples/dockers/Dockerfiles.md Normal file
View File

@@ -0,0 +1,81 @@
# README for AutoGen Docker Samples
Welcome to the `autogen/samples/dockers` directory! Here you'll find Dockerfiles that are essential for setting up your AutoGen development environment. Each Dockerfile is tailored for different use cases and requirements. Below is a brief overview of each and how you can utilize them effectively.
## Dockerfile Descriptions
### Dockerfile.base
- **Purpose**: This Dockerfile is designed for basic setups. It includes common Python libraries and essential dependencies required for general usage of AutoGen.
- **Usage**: Ideal for those just starting with AutoGen or for general-purpose applications.
- **Building the Image**: Run `docker build -f Dockerfile.base -t autogen_base_img .` in this directory.
### Dockerfile.full
- **Purpose**: This Dockerfile is for advanced features. It includes additional dependencies and is configured for more complex or feature-rich AutoGen applications.
- **Usage**: Suited for advanced users who need the full range of AutoGen's capabilities.
- **Building the Image**: Execute `docker build -f Dockerfile.full -t autogen_full_img .`.
### Dockerfile.dev
- **Purpose**: Tailored for AutoGen project developers, this Dockerfile includes tools and configurations aiding in development and contribution.
- **Usage**: Recommended for developers who are contributing to the AutoGen project.
- **Building the Image**: Run `docker build -f Dockerfile.dev -t autogen_dev_img .`.
- **Before using**: We highly encourage all potential contributors to read the [AutoGen Contributing](https://microsoft.github.io/autogen/docs/Contribute) page prior to submitting any pull requests.
## Customizing Dockerfiles
Feel free to modify these Dockerfiles for your specific project needs. Here are some common customizations:
- **Adding New Dependencies**: If your project requires additional Python packages, you can add them using the `RUN pip install` command.
- **Changing the Base Image**: You may change the base image (e.g., from a Python image to an Ubuntu image) to suit your project's requirements.
- **Changing the Python version**: do you need a different version of python other than 3.11. Just update the first line of each of the Dockerfiles like so:
`FROM python:3.11-slim-bookworm` to `FROM python:3.10-slim-bookworm`
- **Setting Environment Variables**: Add environment variables using the `ENV` command for any application-specific configurations. We have prestaged the line needed to inject your OpenAI_key into the docker environment as a environmental variable. Others can be staged in the same way. Just uncomment the line.
`# ENV OPENAI_API_KEY="{OpenAI-API-Key}"` to `ENV OPENAI_API_KEY="{OpenAI-API-Key}"`
- **Need a less "Advanced" Autogen build**: If the Dockerfile.full is to much but you need more than advanced then update this line in the Dockerfile.full file.
`RUN pip install pyautogen[teachable,lmm,retrievechat,mathchat,blendsearch] autogenra` to install just what you need. `RUN pip install pyautogen[retrievechat,blendsearch] autogenra`
- **Can't Dev without your favorite CLI tool**: if you need particular OS tools to be installed in your Docker container you can add those packages here right after the sudo for the Dockerfile.base and Dockerfile.full files. In the example below we are installing net-tools and vim to the environment.
```code
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
software-properties-common sudo net-tools vim\
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
```
### Managing Your Docker Environment
After customizing your Dockerfile, build the Docker image using the `docker build` command as shown above. To run a container based on your new image, use:
```bash
docker run -it -v $(pwd)/your_app:/app your_image_name
```
Replace `your_app` with your application directory and `your_image_name` with the name of the image you built.
#### Closing for the Day
- **Exit the container**: Type `exit`.
- **Stop the container**: Use `docker stop {application_project_name}`.
#### Resuming Work
- **Restart the container**: Use `docker start {application_project_name}`.
- **Access the container**: Execute `sudo docker exec -it {application_project_name} bash`.
- **Reactivate the environment**: Run `source /usr/src/app/autogen_env/bin/activate`.
### Useful Docker Commands
- **View running containers**: `docker ps -a`.
- **View Docker images**: `docker images`.
- **Restart container setup**: Stop (`docker stop my_container`), remove the container (`docker rm my_container`), and remove the image (`docker rmi my_image:latest`).
#### Troubleshooting Common Issues
- Check Docker daemon, port conflicts, and permissions issues.
#### Additional Resources
For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com).

155
website/docs/Contribute.md
View File

@@ -2,14 +2,13 @@
This project welcomes and encourages all forms of contributions, including but not limited to:
- Pushing patches.
- Code review of pull requests.
- Documentation, examples and test cases.
- Readability improvement, e.g., improvement on docstr and comments.
- Community participation in [issues](https://github.com/microsoft/autogen/issues), [discussions](https://github.com/microsoft/autogen/discussions), [discord](https://discord.gg/pAbnFJrkgZ), and [twitter](https://twitter.com/pyautogen).
- Tutorials, blog posts, talks that promote the project.
- Sharing application scenarios and/or related research.
- Pushing patches.
- Code review of pull requests.
- Documentation, examples and test cases.
- Readability improvement, e.g., improvement on docstr and comments.
- Community participation in [issues](https://github.com/microsoft/autogen/issues), [discussions](https://github.com/microsoft/autogen/discussions), [discord](https://discord.gg/pAbnFJrkgZ), and [twitter](https://twitter.com/pyautogen).
- Tutorials, blog posts, talks that promote the project.
- Sharing application scenarios and/or related research.
Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
@@ -40,6 +39,7 @@ feedback:
- Please include your **operating system type and version number**, as well as
your **Python, autogen, scikit-learn versions**. The version of autogen
can be found by running the following code snippet:
```python
import autogen
print(autogen.__version__)
@@ -49,7 +49,6 @@ print(autogen.__version__)
appropriate code blocks**. See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks)
for more details.
## Becoming a Reviewer
There is currently no formal reviewer solicitation process. Current reviewers identify reviewers from active contributors. If you are willing to become a reviewer, you are welcome to let us know on discord.
@@ -58,57 +57,84 @@ There is currently no formal reviewer solicitation process. Current reviewers id
### General
* Be a member of the community and treat everyone as a member. Be inclusive.
* Help each other and encourage mutual help.
* Actively post and respond.
* Keep open communication.
- Be a member of the community and treat everyone as a member. Be inclusive.
- Help each other and encourage mutual help.
- Actively post and respond.
- Keep open communication.
### Pull Requests
* For new PR, decide whether to close without review. If not, find the right reviewers. The default reviewer is microsoft/autogen. Ask users who can benefit from the PR to review it.
* For old PR, check the blocker: reviewer or PR creator. Try to unblock. Get additional help when needed.
* When requesting changes, make sure you can check back in time because it blocks merging.
* Make sure all the checks are passed.
* For changes that require running OpenAI tests, make sure the OpenAI tests pass too. Running these tests requires approval.
* In general, suggest small PRs instead of a giant PR.
* For documentation change, request snapshot of the compiled website, or compile by yourself to verify the format.
* For new contributors who have not signed the contributing agreement, remind them to sign before reviewing.
* For multiple PRs which may have conflict, coordinate them to figure out the right order.
* Pay special attention to:
- Breaking changes. Don’t make breaking changes unless necessary. Don’t merge to main until enough headsup is provided and a new release is ready.
- Test coverage decrease.
- Changes that may cause performance degradation. Do regression test when test suites are available.
- Discourage **change to the core library** when there is an alternative.
- For new PR, decide whether to close without review. If not, find the right reviewers. The default reviewer is microsoft/autogen. Ask users who can benefit from the PR to review it.
- For old PR, check the blocker: reviewer or PR creator. Try to unblock. Get additional help when needed.
- When requesting changes, make sure you can check back in time because it blocks merging.
- Make sure all the checks are passed.
- For changes that require running OpenAI tests, make sure the OpenAI tests pass too. Running these tests requires approval.
- In general, suggest small PRs instead of a giant PR.
- For documentation change, request snapshot of the compiled website, or compile by yourself to verify the format.
- For new contributors who have not signed the contributing agreement, remind them to sign before reviewing.
- For multiple PRs which may have conflict, coordinate them to figure out the right order.
- Pay special attention to:
- Breaking changes. Don’t make breaking changes unless necessary. Don’t merge to main until enough headsup is provided and a new release is ready.
- Test coverage decrease.
- Changes that may cause performance degradation. Do regression test when test suites are available.
- Discourage **change to the core library** when there is an alternative.
### Issues and Discussions
* For new issues, write a reply, apply a label if relevant. Ask on discord when necessary. For roadmap issues, add to the roadmap project and encourage community discussion. Mention relevant experts when necessary.
* For old issues, provide an update or close. Ask on discord when necessary. Encourage PR creation when relevant.
* Use “good first issue” for easy fix suitable for first-time contributors.
* Use “task list” for issues that require multiple PRs.
* For discussions, create an issue when relevant. Discuss on discord when appropriate.
## Developing
- For new issues, write a reply, apply a label if relevant. Ask on discord when necessary. For roadmap issues, add to the roadmap project and encourage community discussion. Mention relevant experts when necessary.
### Setup
- For old issues, provide an update or close. Ask on discord when necessary. Encourage PR creation when relevant.
- Use “good first issue” for easy fix suitable for first-time contributors.
- Use “task list” for issues that require multiple PRs.
- For discussions, create an issue when relevant. Discuss on discord when appropriate.
## Docker for Development
For developers contributing to the AutoGen project, we offer a specialized Docker environment. This setup is designed to streamline the development process, ensuring that all contributors work within a consistent and well-equipped environment.
### Autogen Developer Image (autogen_dev_img)
- **Purpose**: The `autogen_dev_img` is tailored for contributors to the AutoGen project. It includes a suite of tools and configurations that aid in the development and testing of new features or fixes.
- **Usage**: This image is recommended for developers who intend to contribute code or documentation to AutoGen.
- **Forking the Project**: It's advisable to fork the AutoGen GitHub project to your own repository. This allows you to make changes in a separate environment without affecting the main project.
- **Updating Dockerfile.dev**: Modify your copy of `Dockerfile.dev` as needed for your development work.
- **Submitting Pull Requests**: Once your changes are ready, submit a pull request from your branch to the upstream AutoGen GitHub project for review and integration. For more details on contributing, see the [AutoGen Contributing](https://microsoft.github.io/autogen/docs/Contribute) page.
### Building the Developer Docker Image
- To build the developer Docker image (`autogen_dev_img`), use the following commands:
```bash
docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git
```
- For building the developer image built from a specific Dockerfile in a branch other than main/master
```bash
# clone the branch you want to work out of
git clone --branch {branch-name} https://github.com/microsoft/autogen.git
# cd to your new directory
cd autogen
# build your Docker image
docker build -f samples/dockers/Dockerfile.dev -t autogen_dev-srv_img .
```
### Using the Developer Docker Image
Once you have built the `autogen_dev_img`, you can run it using the standard Docker commands. This will place you inside the containerized development environment where you can run tests, develop code, and ensure everything is functioning as expected before submitting your contributions.
```bash
git clone https://github.com/microsoft/autogen.git
pip install -e autogen
docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash
```
### Docker
We provide [Dockerfiles](https://github.com/microsoft/autogen/blob/main/samples/dockers/Dockerfile.dev) for developers to use.
Use the following command line to build and run a docker image.
- Note that the `pwd` is shorthand for present working directory. Thus, any path after the pwd is relative to that. If you want a more verbose method you could remove the "`pwd`/autogen-newcode" and replace it with the full path to your directory
```bash
docker run -it -p 8081:3000 -v /home/AutoGenDeveloper/autogen-newcode:newstuff/ autogen_dev_img bash
```
docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git#main
docker run -it autogen_dev_img
```
Detailed instructions can be found [here](Installation.md#option-1-install-and-run-autogen-in-docker).
### Develop in Remote Container
@@ -123,6 +149,7 @@ Run `pre-commit install` to install pre-commit into your git hooks. Before you c
### Write tests
Tests are automatically run via GitHub actions. There are two workflows:
1. [build.yml](https://github.com/microsoft/autogen/blob/main/.github/workflows/build.yml)
1. [openai.yml](https://github.com/microsoft/autogen/blob/main/.github/workflows/openai.yml)
@@ -131,14 +158,19 @@ The first workflow is required to pass for all PRs (and it doesn't do any OpenAI
#### Run non-OpenAI tests
To run the subset of the tests not depending on `openai` (and not calling LLMs)):
- Install pytest:
```
``` code
pip install pytest
```
- Run the tests from the `test` folder using the `--skip-openai` flag.
```
``` code
pytest test --skip-openai
```
- Make sure all tests pass, this is required for [build.yml](https://github.com/microsoft/autogen/blob/main/.github/workflows/build.yml) checks to pass
### Coverage
@@ -175,5 +207,28 @@ yarn start
The last command starts a local development server and opens up a browser window.
Most changes are reflected live without having to restart the server.
To build and test documentation within a docker container. Use the Dockerfile.dev as described above to build your image
```bash
docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git
```
Then start the container like so, this will log you in and ensure that Docker port 3000 is mapped to port 8081 on your local machine
```bash
docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash
```
Once at the CLI in Docker run the following commands:
```bash
cd website
yarn install --frozen-lockfile --ignore-engines
pydoc-markdown
yarn start --host 0.0.0.0 --port 3000
```
Once done you should be able to access the documentation at `http://127.0.0.1:8081/autogen`
Note:
some tips in this guide are based off the contributor guide from [flaml](https://microsoft.github.io/FLAML/docs/Contribute).

125
website/docs/Installation.md
View File

@@ -1,44 +1,94 @@
# Installation
AutoGen is a versatile tool that can be installed and run in Docker or locally using a virtual environment. Below are detailed instructions for both methods.
## Option 1: Install and Run AutoGen in Docker
[Docker](https://www.docker.com/) is a containerization platform that simplifies the setup and execution of your code. A properly built docker image could provide isolated and consistent environment to run your code securely across platforms. One option of using AutoGen is to install and run it in a docker container. You can do that in [Github codespace](https://codespaces.new/microsoft/autogen?quickstart=1) or follow the instructions below to do so.
Docker, an indispensable tool in modern software development, offers a compelling solution for AutoGen's setup. Docker allows you to create consistent environments that are portable and isolated from the host OS. With Docker, everything AutoGen needs to run, from the operating system to specific libraries, is encapsulated in a container, ensuring uniform functionality across different systems. The Dockerfiles necessary for AutoGen are conveniently located in the project's GitHub repository at [https://github.com/microsoft/autogen/tree/main/samples/dockers](https://github.com/microsoft/autogen/tree/main/samples/dockers).
#### Step 1. Install Docker.
**Pre-configured DockerFiles**: The AutoGen Project offers pre-configured Dockerfiles for your use. These Dockerfiles will run as is, however they can be modified to suit your development needs. Please see the README.md file in autogen/samples/dockers
Install docker following [this instruction](https://docs.docker.com/get-docker/).
- **autogen_base_img**: For a basic setup, you can use the `autogen_base_img` to run simple scripts or applications. This is ideal for general users or those new to AutoGen.
- **autogen_full_img**: Advanced users or those requiring more features can use `autogen_full_img`. Be aware that this version loads ALL THE THINGS and thus is very large. Take this into consideration if you build your application off of it.
For Mac users, alternatively you may choose to install [colima](https://smallsharpsoftwaretools.com/tutorials/use-colima-to-run-docker-containers-on-macos/) to run docker containers, if there is any issues with starting the docker daemon.
### Step 1: Install Docker
#### Step 2. Build a docker image
- **General Installation**: Follow the [official Docker installation instructions](https://docs.docker.com/get-docker/). This is your first step towards a containerized environment, ensuring a consistent and isolated workspace for AutoGen.
AutoGen provides [dockerfiles](https://github.com/microsoft/autogen/tree/main/samples/dockers/) that could be used to build docker images. Use the following command line to build a docker image named `autogen_img` (or other names you prefer) from one of the provided dockerfiles named `Dockerfile.base`:
- **For Mac Users**: If you encounter issues with the Docker daemon, consider using [colima](https://smallsharpsoftwaretools.com/tutorials/use-colima-to-run-docker-containers-on-macos/). Colima offers a lightweight alternative to manage Docker containers efficiently on macOS.
```
docker build -f samples/dockers/Dockerfile.base -t autogen_img https://github.com/microsoft/autogen.git#main
```
which includes some common python libraries and essential dependencies of AutoGen, or build from `Dockerfile.full` which include additional dependencies for more advanced features of AutoGen with the following command line:
### Step 2: Build a Docker Image
```
docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git
```
Once you build the docker image, you can use `docker images` to check whether it has been created successfully.
AutoGen now provides updated Dockerfiles tailored for different needs. Building a Docker image is akin to setting the foundation for your project's environment:
#### Step 3. Run applications built with AutoGen from a docker image.
- **Autogen Basic (dockerfile.base)**: Ideal for general use, this setup includes common Python libraries and essential dependencies. Perfect for those just starting with AutoGen.
**Mount your code to the docker image and run your application from there:** Now suppose you have your application built with AutoGen in a main script named `twoagent.py` ([example](https://github.com/microsoft/autogen/blob/main/test/twoagent.py)) in a folder named `myapp`. With the command line below, you can mount your folder and run the application in docker.
```bash
docker build -f samples/dockers/Dockerfile.base -t autogen_base_img https://github.com/microsoft/autogen.git
```
```python
# Mount the local folder `myapp` into docker image and run the script named "twoagent.py" in the docker.
docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoagent.py
- **Autogen Advanced (dockerfile.full)**: Advanced users or those requiring all the things that AutoGen has to offer `autogen_full_img`
```bash
docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git
```
### Step 3: Run AutoGen Applications from Docker Image
Here's how you can run an application built with AutoGen, using the Docker image:
1. **Mount Your Directory**: Use the Docker `-v` flag to mount your local application directory to the Docker container. This allows you to develop on your local machine while running the code in a consistent Docker environment. For example:
```bash
docker run -it -v $(pwd)/myapp:/home/autogen/autogen/myapp autogen_base_img:latest python /home/autogen/autogen/myapp/main.py
```
Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located.
2. **Mount your code:** Now suppose you have your application built with AutoGen in a main script named `twoagent.py` ([example](https://github.com/microsoft/autogen/blob/main/test/twoagent.py)) in a folder named `myapp`. With the command line below, you can mount your folder and run the application in Docker.
```python
# Mount the local folder `myapp` into docker image and run the script named "twoagent.py" in the docker.
docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoagent.py
```
3. **Port Mapping**: If your application requires a specific port, use the `-p` flag to map the container's port to your host. For instance, if your app runs on port 3000 inside Docker and you want it accessible on port 8080 on your host machine:
```bash
docker run -it -p 8080:3000 -v $(pwd)/myapp:/myapp autogen_base_img:latest python /myapp
```
In this command, `-p 8080:3000` maps port 3000 from the container to port 8080 on your local machine.
4. **Examples of Running Different Applications**: Here is the basic format of the docker run command.
```bash
docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Docker_DIR} {name_of_the_image} {bash/python} {Docker_path_to_script_to_execute}
```
<!-- You may also run [AutoGen Studio](https://github.com/microsoft/autogen/tree/main/samples/apps/autogen-studio) (assuming that you have built a docker image named `autogen_full_img` with `Dockerfile.full` and you have set the environment variable `OPENAI_API_KEY` to your OpenAI API key) as below:
- *Simple Script*: Run a Python script located in your local `myapp` directory.
```
docker run -it -e OPENAI_API_KEY=$OPENAI_API_KEY -p 8081:8081 autogen_full_img:latest autogenra ui --host 0.0.0.0
```
Then open `http://localhost:8081/` in your browser to use AutoGen Studio. -->
```bash
docker run -it -v `pwd`/myapp:/myapp autogen_base_img:latest python /myapp/my_script.py
```
- *Web Application*: If your application includes a web server running on port 5000.
```bash
docker run -it -p 8080:5000 -v $(pwd)/myapp:/myapp autogen_base_img:latest
```
- *Data Processing*: For tasks that involve processing data stored in a local directory.
```bash
docker run -it -v $(pwd)/data:/data autogen_base_img:latest python /myapp/process_data.py
```
#### Additional Resources
- For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com).
- Details on how to use the Dockerfile.dev version can be found on the [Contributing](Contribute.md#docker)
## Option 2: Install AutoGen Locally Using Virtual Environment
@@ -47,12 +97,14 @@ When installing AutoGen locally, we recommend using a virtual environment for th
### Option a: venv
You can create a virtual environment with `venv` as below:
```bash
python3 -m venv pyautogen
source pyautogen/bin/activate
```
The following command will deactivate the current `venv` environment:
```bash
deactivate
```
@@ -61,12 +113,14 @@ deactivate
Another option is with `Conda`. You can install it by following [this doc](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html),
and then create a virtual environment as below:
```bash
conda create -n pyautogen python=3.10 # python 3.10 is recommended as it's stable and not too old
conda activate pyautogen
```
The following command will deactivate the current `conda` environment:
```bash
conda deactivate
```
@@ -79,6 +133,7 @@ Another option is with `poetry`, which is a dependency manager for Python.
You can install it by following [this doc](https://python-poetry.org/docs/#installation),
and then create a virtual environment as below:
```bash
poetry init
poetry shell
@@ -87,6 +142,7 @@ poetry add pyautogen
```
The following command will deactivate the current `poetry` environment:
```bash
exit
```
@@ -117,30 +173,34 @@ Therefore, some changes are required for users of `pyautogen<0.2`.
- `api_base` -> `base_url`, `request_timeout` -> `timeout` in `llm_config` and `config_list`. `max_retry_period` and `retry_wait_time` are deprecated. `max_retries` can be set for each client.
- MathChat is unsupported until it is tested in future release.
- `autogen.Completion` and `autogen.ChatCompletion` are deprecated. The essential functionalities are moved to `autogen.OpenAIWrapper`:
```python
from autogen import OpenAIWrapper
client = OpenAIWrapper(config_list=config_list)
response = client.create(messages=[{"role": "user", "content": "2+2="}])
print(client.extract_text_or_completion_object(response))
```
- Inference parameter tuning and inference logging features are currently unavailable in `OpenAIWrapper`. Logging will be added in a future release.
Inference parameter tuning can be done via [`flaml.tune`](https://microsoft.github.io/FLAML/docs/Use-Cases/Tune-User-Defined-Function).
- `seed` in autogen is renamed into `cache_seed` to accommodate the newly added `seed` param in openai chat completion api. `use_cache` is removed as a kwarg in `OpenAIWrapper.create()` for being automatically decided by `cache_seed`: int | None. The difference between autogen's `cache_seed` and openai's `seed` is that:
* autogen uses local disk cache to guarantee the exactly same output is produced for the same input and when cache is hit, no openai api call will be made.
* openai's `seed` is a best-effort deterministic sampling with no guarantee of determinism. When using openai's `seed` with `cache_seed` set to None, even for the same input, an openai api call will be made and there is no guarantee for getting exactly the same output.
- autogen uses local disk cache to guarantee the exactly same output is produced for the same input and when cache is hit, no openai api call will be made.
- openai's `seed` is a best-effort deterministic sampling with no guarantee of determinism. When using openai's `seed` with `cache_seed` set to None, even for the same input, an openai api call will be made and there is no guarantee for getting exactly the same output.
### Optional Dependencies
- #### docker
- #### Docker
Even if you install AutoGen locally, we highly recommend using Docker for [code execution](FAQ.md#enable-python-3-docker-image).
To use docker for code execution, you also need to install the python package `docker`:
```bash
pip install docker
```
You might want to override the default docker image used for code execution. To do that set `use_docker` key of `code_execution_config` property to the name of the image. E.g.:
```python
user_proxy = autogen.UserProxyAgent(
name="agent",
@@ -156,6 +216,7 @@ Otherwise, reply CONTINUE, or the reason why the task is not solved yet."""
- #### blendsearch
`pyautogen<0.2` offers a cost-effective hyperparameter optimization technique [EcoOptiGen](https://arxiv.org/abs/2303.04673) for tuning Large Language Models. Please install with the [blendsearch] option to use it.
```bash
pip install "pyautogen[blendsearch]<0.2"
```
@@ -169,6 +230,7 @@ Example notebooks:
- #### retrievechat
`pyautogen` supports retrieval-augmented generation tasks such as question answering and code generation with RAG agents. Please install with the [retrievechat] option to use it.
```bash
pip install "pyautogen[retrievechat]"
```
@@ -190,21 +252,20 @@ Example notebooks:
[Automated Code Generation and Question Answering with Qdrant based Retrieval Augmented Agents](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_qdrant_RetrieveChat.ipynb)
- #### Teachability
To use Teachability, please install AutoGen with the [teachable] option.
```bash
pip install "pyautogen[teachable]"
```
Example notebook: [Chatting with a teachable agent](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_teachability.ipynb)
- #### Large Multimodal Model (LMM) Agents
We offered Multimodal Conversable Agent and LLaVA Agent. Please install with the [lmm] option to use it.
```bash
pip install "pyautogen[lmm]"
```
@@ -213,10 +274,10 @@ Example notebooks:
[LLaVA Agent](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_lmm_llava.ipynb)
- #### mathchat
`pyautogen<0.2` offers an experimental agent for math problem solving. Please install with the [mathchat] option to use it.
```bash
pip install "pyautogen[mathchat]<0.2"
```