Rewrite and consolidate configuration docs (microsoft#1581)

* Rewrite and consolidate configuration docs * add link to filtering * updates based on comments * update lockfile * update redirect * spelling mistake * update the noqa * update links * fix broken links * lint fixes * address comments * update wording about model selection * update cache_seed and json pattern * add periods * Update the config json func and other small changes * update wording of json string * update intro * update description of caching * fix link * spelling mistake * fix llm config * Update website/docs/llm_configuration.ipynb Co-authored-by: gagb <[email protected]> * Add examples back as notebook --------- Co-authored-by: gagb <[email protected]> Co-authored-by: Aaron <[email protected]>
gunnarku · Feb 11, 2024 · b4a2c6e · b4a2c6e
1 parent e83de5d
commit b4a2c6e
Show file tree

Hide file tree

Showing 30 changed files with 605 additions and 434 deletions.
diff --git a/notebook/agentchat_RetrieveChat.ipynb b/notebook/agentchat_RetrieveChat.ipynb
@@ -103,7 +103,7 @@
    "source": [
     "\\:\\:\\:tip\n",
     "\n",
-    "Learn more about the various ways to configure LLM endpoints [here](/docs/llm_endpoint_configuration).\n",
+    "Learn more about the various ways to configure LLM endpoints [here](/docs/llm_configuration).\n",
     "\n",
     "\\:\\:\\:"
    ]

diff --git a/notebook/agentchat_auto_feedback_from_code_execution.ipynb b/notebook/agentchat_auto_feedback_from_code_execution.ipynb
@@ -61,7 +61,7 @@
    "source": [
     "\\:\\:\\:tip\n",
     "\n",
-    "Learn more about the various ways to configure LLM endpoints [here](/docs/llm_endpoint_configuration).\n",
+    "Learn more about the various ways to configure LLM endpoints [here](/docs/llm_configuration).\n",
     "\n",
     "\\:\\:\\:"
    ]

diff --git a/notebook/agentchat_cost_token_tracking.ipynb b/notebook/agentchat_cost_token_tracking.ipynb
@@ -102,7 +102,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_function_call.ipynb b/notebook/agentchat_function_call.ipynb
@@ -103,7 +103,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_function_call_async.ipynb b/notebook/agentchat_function_call_async.ipynb
@@ -61,7 +61,7 @@
    "source": [
     "\\:\\:\\:tip\n",
     "\n",
-    "Learn more about the various ways to configure LLM endpoints [here](/docs/llm_endpoint_configuration).\n",
+    "Learn more about the various ways to configure LLM endpoints [here](/docs/llm_configuration).\n",
     "\n",
     "\\:\\:\\:"
    ]

diff --git a/notebook/agentchat_function_call_currency_calculator.ipynb b/notebook/agentchat_function_call_currency_calculator.ipynb
@@ -106,7 +106,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_groupchat.ipynb b/notebook/agentchat_groupchat.ipynb
@@ -107,7 +107,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_groupchat_RAG.ipynb b/notebook/agentchat_groupchat_RAG.ipynb
@@ -101,7 +101,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_groupchat_research.ipynb b/notebook/agentchat_groupchat_research.ipynb
@@ -93,7 +93,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_groupchat_vis.ipynb b/notebook/agentchat_groupchat_vis.ipynb
@@ -110,7 +110,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_human_feedback.ipynb b/notebook/agentchat_human_feedback.ipynb
@@ -102,7 +102,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_langchain.ipynb b/notebook/agentchat_langchain.ipynb
@@ -139,7 +139,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_oai_assistant_groupchat.ipynb b/notebook/agentchat_oai_assistant_groupchat.ipynb
@@ -62,7 +62,7 @@
     "]\n",
     "```\n",
     "\n",
-    "Currently Azure OpenAI does not support assistant api. You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "Currently Azure OpenAI does not support assistant api. You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_stream.ipynb b/notebook/agentchat_stream.ipynb
@@ -102,7 +102,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/notebook/agentchat_two_users.ipynb b/notebook/agentchat_two_users.ipynb
@@ -82,7 +82,7 @@
     "]\n",
     "```\n",
     "\n",
-    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
    ]
   },
   {

diff --git a/...ite/docs/llm_endpoint_configuration.ipynb → ...ook/config_loader_utility_functions.ipynb b/...ite/docs/llm_endpoint_configuration.ipynb → ...ook/config_loader_utility_functions.ipynb
@@ -4,100 +4,36 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "---\n",
-    "custom_edit_url: https://github.com/microsoft/autogen/edit/main/website/docs/llm_endpoint_configuration.ipynb\n",
-    "---\n",
+    "# Config loader utility functions\n",
     "\n",
-    "# LLM Endpoint Configuration\n",
-    "\n",
-    "## TL;DR\n",
-    "\n",
-    "For just getting started with AutoGen you can use the following to define your LLM endpoint configuration:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import autogen\n",
-    "\n",
-    "config_list = [{\"model\": \"gpt-4\", \"api_key\": \"YOUR_OPENAI_API_KEY\"}]"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "\\:\\:\\:danger \n",
-    "\n",
-    "Never commit secrets into your code. Before committing, change the code to use a different way of providing your API keys as described below.\n",
-    "\n",
-    "\\:\\:\\:"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "\n",
-    "\n",
-    "## In-depth\n",
+    "For an introduction to configuring LLMs, refer to the [main configuration docs](https://microsoft.github.io/autogen/docs/llm_configuration). This guide will run through examples of the more advanced utility functions for managing API configurations.\n",
     "\n",
     "Managing API configurations can be tricky, especially when dealing with multiple models and API versions. The provided utility functions assist users in managing these configurations effectively. Ensure your API keys and other sensitive data are stored securely. You might store keys in `.txt` or `.env` files or environment variables for local development. Never expose your API keys publicly. If you insist on storing your key files locally on your repo (you shouldn't), ensure the key file path is added to the `.gitignore` file.\n",
     "\n",
-    "### Steps:\n",
+    "## Storing API keys\n",
+    "\n",
     "1. Obtain API keys from OpenAI and optionally from Azure OpenAI (or other provider).\n",
     "2. Store them securely using either:\n",
     "    - Environment Variables: `export OPENAI_API_KEY='your-key'` in your shell.\n",
     "    - Text File: Save the key in a `key_openai.txt` file.\n",
     "    - Env File: Save the key to a `.env` file eg: `OPENAI_API_KEY=sk-********************`\n",
-    "3. [Ensure `pyautogen` is installed](./installation/Installation.mdx)\n",
-    "\n",
-    "There are many ways to generate a `config_list` depending on your use case:\n",
-    "\n",
-    "- `get_config_list`: Generates configurations for API calls, primarily from provided API keys.\n",
-    "- `config_list_openai_aoai`: Constructs a list of configurations using both Azure OpenAI and OpenAI endpoints, sourcing API keys from environment variables or local files.\n",
-    "- `config_list_from_json`: Loads configurations from a JSON structure, either from an environment variable or a local JSON file, with the flexibility of filtering configurations based on given criteria.\n",
-    "- `config_list_from_models`: Creates configurations based on a provided list of models, useful when targeting specific models without manually specifying each configuration.\n",
-    "- `config_list_from_dotenv`: Constructs a configuration list from a `.env` file, offering a consolidated way to manage multiple API configurations and keys from a single file.\n",
-    "\n",
-    "If multiple models are provided, the Autogen client (`OpenAIWrapper`) and agents don't choose the \"best model\" on any criteria - inference is done through the very first model and the next one is used only if the current model fails (e.g. API throttling by the provider or a filter condition is unsatisfied)."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### What is a `config_list`?\n",
-    "When instantiating an assistant, such as the example below, it is passed a `config_list`. This is used to tell the `AssistantAgent` which models or configurations it has access to:\n",
-    "```python\n",
     "\n",
-    "assistant = AssistantAgent(\n",
-    "    name=\"assistant\",\n",
-    "    llm_config={\n",
-    "        \"timeout\": 600,\n",
-    "        \"cache_seed\": 42,\n",
-    "        \"config_list\": config_list,\n",
-    "        \"temperature\": 0,\n",
-    "    },\n",
-    ")\n",
-    "```\n",
-    "\n",
-    "Consider an intelligent assistant that utilizes OpenAI's GPT models. Depending on user requests, it might need to:\n",
+    "## Utility functions\n",
     "\n",
-    "- Generate creative content (using gpt-4).\n",
-    "- Answer general queries (using gpt-3.5-turbo).\n",
+    "There are several utility functions for loading LLM config lists that may be useful depending on the situation.\n",
     "\n",
-    "Different tasks may require different models, and the `config_list` aids in dynamically selecting the appropriate model configuration, managing API keys, endpoints, and versions for efficient operation of the intelligent assistant. In summary, the `config_list` helps the agents work efficiently, reliably, and optimally by managing various configurations and interactions with the OpenAI API - enhancing the adaptability and functionality of the agents."
+    "- [`get_config_list`](#get_config_list): Generates configurations for API calls, primarily from provided API keys.\n",
+    "- [`config_list_openai_aoai`](#config_list_openai_aoai): Constructs a list of configurations using both Azure OpenAI and OpenAI endpoints, sourcing API keys from environment variables or local files.\n",
+    "- [`config_list_from_json`](#config_list_from_json): Loads configurations from a JSON structure, either from an environment variable or a local JSON file, with the flexibility of filtering configurations based on given criteria.\n",
+    "- [`config_list_from_models`](#config_list_from_models): Creates configurations based on a provided list of models, useful when targeting specific models without manually specifying each configuration.\n",
+    "- [`config_list_from_dotenv`](#config_list_from_dotenv): Constructs a configuration list from a `.env` file, offering a consolidated way to manage multiple API configurations and keys from a single file."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## get_config_list\n",
+    "### get_config_list\n",
     "\n",
     "Used to generate configurations for API calls."
    ]
@@ -116,6 +52,8 @@
     }
    ],
    "source": [
+    "import autogen\n",
+    "\n",
     "api_keys = [\"YOUR_OPENAI_API_KEY\"]\n",
     "base_urls = None  # You can specify API base URLs if needed. eg: localhost:8000\n",
     "api_type = \"openai\"  # Type of API, e.g., \"openai\" or \"aoai\".\n",
@@ -130,7 +68,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## config_list_openai_aoai\n",
+    "### config_list_openai_aoai\n",
     "\n",
     "This method creates a list of configurations using Azure OpenAI endpoints and OpenAI endpoints. It tries to extract API keys and bases from environment variables or local text files.\n",
     "\n",
@@ -165,7 +103,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## config_list_from_json\n",
+    "### config_list_from_json\n",
     "\n",
     "This method loads configurations from an environment variable or a JSON file. It provides flexibility by allowing users to filter configurations based on certain criteria.\n",
     "\n",
@@ -215,86 +153,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### What is `filter_dict`?\n",
-    "\n",
-    "The z parameter in `autogen.config_list_from_json` function is used to selectively filter the configurations loaded from the environment variable or JSON file based on specified criteria. It allows you to define criteria to select only those configurations that match the defined conditions.\n",
-    "\n",
-    "let's say you want to configure an assistant agent to only LLM type. Take the below example: even though we have \"gpt-3.5-turbo\" and \"gpt-4\" in our `OAI_CONFIG_LIST`, this agent would only be configured to use"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "cheap_config_list = autogen.config_list_from_json(\n",
-    "    env_or_file=\"OAI_CONFIG_LIST\",\n",
-    "    filter_dict={\n",
-    "        \"model\": {\n",
-    "            \"gpt-3.5-turbo\",\n",
-    "        }\n",
-    "    },\n",
-    ")\n",
-    "\n",
-    "costly_config_list = autogen.config_list_from_json(\n",
-    "    env_or_file=\"OAI_CONFIG_LIST\",\n",
-    "    filter_dict={\n",
-    "        \"model\": {\n",
-    "            \"gpt-4\",\n",
-    "        }\n",
-    "    },\n",
-    ")\n",
-    "\n",
-    "# Assistant using GPT 3.5 Turbo\n",
-    "assistant_one = autogen.AssistantAgent(\n",
-    "    name=\"3.5-assistant\",\n",
-    "    llm_config={\n",
-    "        \"timeout\": 600,\n",
-    "        \"cache_seed\": 42,\n",
-    "        \"config_list\": cheap_config_list,\n",
-    "        \"temperature\": 0,\n",
-    "    },\n",
-    ")\n",
-    "\n",
-    "# Assistant using GPT 4\n",
-    "assistant_two = autogen.AssistantAgent(\n",
-    "    name=\"4-assistant\",\n",
-    "    llm_config={\n",
-    "        \"timeout\": 600,\n",
-    "        \"cache_seed\": 42,\n",
-    "        \"config_list\": costly_config_list,\n",
-    "        \"temperature\": 0,\n",
-    "    },\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "With the `OAI_CONFIG_LIST` we set earlier, there isn't much to filter on. But when the complexity of a project grows and you're managing multiple models for various purposes, you can see how `filter_dict` can be useful. \n",
-    "\n",
-    "A more complex filtering criteria could be the following: Assuming we have an `OAI_CONFIG_LIST` several models used to create various agents - Let's say we want to load configurations for `gpt-4` using API version `\"2023-03-01-preview\"` and we want the `api_type` to be `aoai`, we can set up `filter_dict` as follows:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "config_list = autogen.config_list_from_json(\n",
-    "    env_or_file=\"OAI_CONFIG_LIST\",\n",
-    "    filter_dict={\"model\": {\"gpt-4\"}, \"api_version\": {\"2023-03-01-preview\"}, \"api_type\": [\"aoai\"]},\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## config_list_from_models\n",
+    "### config_list_from_models\n",
     "\n",
     "This method creates configurations based on a provided list of models. It's useful when you have specific models in mind and don't want to manually specify each configuration. The [`config_list_from_models`](/docs/reference/oai/openai_utils#config_list_from_models) function tries to create a list of configurations using Azure OpenAI endpoints and OpenAI endpoints for the provided list of models. It assumes the api keys and api bases are stored in the corresponding environment variables or local txt files. It's okay to only have the OpenAI API key, OR only the Azure OpenAI API key + base. For Azure the model name refers to the OpenAI Studio deployment name.\n",
     "\n",
@@ -322,7 +181,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## config_list_from_dotenv\n",
+    "### config_list_from_dotenv\n",
     "\n",
     "If you are interested in keeping all of your keys in a single location like a `.env` file rather than using a configuration specifically for OpenAI, you can use `config_list_from_dotenv`. This allows you to conveniently create a config list without creating a complex `OAI_CONFIG_LIST` file.\n",
     "\n",
@@ -499,13 +358,6 @@
     "\n",
     "config_list"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

diff --git a/notebook/contributing.md b/notebook/contributing.md
@@ -52,7 +52,7 @@ Then after the code cell where this is used, include the following markdown snip
 ```
 \:\:\:tip
 
-Learn more about the various ways to configure LLM endpoints [here](/docs/llm_endpoint_configuration).
+Learn more about the various ways to configure LLM endpoints [here](/docs/llm_configuration).
 
 \:\:\:
 ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -102,7 +102,7 @@ @@
         "]\n",
         "```\n",
         "\n",
-        "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_endpoint_configuration.ipynb) for full code examples of the different methods."
+        "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/website/docs/llm_configuration.ipynb) for full code examples of the different methods."
        ]
       },
       {
@@ Expand Down @@