{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 模型\n\n在许多情况下，智能体需要访问LLM模型服务，例如OpenAI、Azure OpenAI或本地模型。由于存在众多不同API的供应商，`autogen-core`实现了模型客户端协议，而`autogen-ext`则为流行模型服务实现了一系列模型客户端。AgentChat可以使用这些模型客户端与模型服务交互。\n\n本节快速概述可用的模型客户端。\n有关直接使用它们的更多细节，请参阅核心API文档中的[模型客户端](../../core-user-guide/components/model-clients.ipynb)。\n\n```{note}\n请参阅{py:class}`~autogen_ext.models.cache.ChatCompletionCache`获取可与以下客户端配合使用的缓存包装器。\n```\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 记录模型调用\n\nAutoGen使用标准Python日志模块记录模型调用和响应等事件。\n日志记录器名称为{py:attr}`autogen_core.EVENT_LOGGER_NAME`，事件类型为`LLMCall`。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import logging\n",
        "\n",
        "from autogen_core import EVENT_LOGGER_NAME\n",
        "\n",
        "logging.basicConfig(level=logging.WARNING)\n",
        "logger = logging.getLogger(EVENT_LOGGER_NAME)\n",
        "logger.addHandler(logging.StreamHandler())\n",
        "logger.setLevel(logging.INFO)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## OpenAI\n\n要访问OpenAI模型，请安装`openai`扩展，这将允许您使用{py:class}`~autogen_ext.models.openai.OpenAIChatCompletionClient`。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "vscode": {
          "languageId": "shellscript"
        }
      },
      "outputs": [],
      "source": [
        "pip install \"autogen-ext[openai]\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "您还需要从OpenAI获取[API密钥](https://platform.openai.com/account/api-keys)。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 10,
      "metadata": {},
      "outputs": [],
      "source": [
        "from autogen_ext.models.openai import OpenAIChatCompletionClient\n",
        "\n",
        "openai_model_client = OpenAIChatCompletionClient(\n",
        "    model=\"gpt-4o-2024-08-06\",\n",
        "    # api_key=\"sk-...\", # 可选，如果您已设置OPENAI_API_KEY环境变量\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "要测试模型客户端，可以使用以下代码：\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "CreateResult(finish_reason='stop', content='The capital of France is Paris.', usage=RequestUsage(prompt_tokens=15, completion_tokens=7), cached=False, logprobs=None)\n"
          ]
        }
      ],
      "source": [
        "from autogen_core.models import UserMessage\n",
        "\n",
        "result = await openai_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
        "print(result)\n",
        "await openai_model_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "```{note}\n你可以将此客户端用于托管在OpenAI兼容端点的模型，但我们尚未测试此功能。\n更多信息请参阅 {py:class}`~autogen_ext.models.openai.OpenAIChatCompletionClient`。\n```\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Azure OpenAI\n\n同样地，安装 `azure` 和 `openai` 扩展以使用 {py:class}`~autogen_ext.models.openai.AzureOpenAIChatCompletionClient`。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "vscode": {
          "languageId": "shellscript"
        }
      },
      "outputs": [],
      "source": [
        "pip install \"autogen-ext[openai,azure]\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "使用该客户端时，需要提供部署ID、Azure认知服务端点、API版本和模型能力。\n对于身份验证，可以提供API密钥或Azure Active Directory (AAD)令牌凭证。\n\n以下代码片段展示了如何使用AAD身份验证。\n所使用的身份必须被分配[认知服务OpenAI用户](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control#cognitive-services-openai-user)角色。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from autogen_ext.auth.azure import AzureTokenProvider\n",
        "from autogen_ext.models.openai import AzureOpenAIChatCompletionClient\n",
        "from azure.identity import DefaultAzureCredential\n",
        "\n",
        "# 创建令牌提供程序\n",
        "token_provider = AzureTokenProvider(\n",
        "    DefaultAzureCredential(),\n",
        "    \"https://cognitiveservices.azure.com/.default\",\n",
        ")\n",
        "\n",
        "az_model_client = AzureOpenAIChatCompletionClient(\n",
        "    azure_deployment=\"{your-azure-deployment}\",\n",
        "    model=\"{model-name, such as gpt-4o}\",\n",
        "    api_version=\"2024-06-01\",\n",
        "    azure_endpoint=\"https://{your-custom-endpoint}.openai.azure.com/\",\n",
        "    azure_ad_token_provider=token_provider,  # 如果选择基于密钥的认证，此项为可选。\n",
        "    # api_key=\"sk-...\", # 用于基于密钥的认证\n",
        ")\n",
        "\n",
        "result = await az_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
        "print(result)\n",
        "await az_model_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "如需直接使用Azure客户端或获取更多信息，请参阅[此处](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/managed-identity#chat-completions)。\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Azure AI Foundry\n\n[Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-studio/)（原名为Azure AI Studio）提供托管在Azure上的模型。\n要使用这些模型，您需要使用{py:class}`~autogen_ext.models.azure.AzureAIChatCompletionClient`。\n\n使用此客户端需要安装`azure`扩展包。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "vscode": {
          "languageId": "shellscript"
        }
      },
      "outputs": [],
      "source": [
        "pip install \"autogen-ext[azure]\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "以下是使用该客户端与来自[GitHub Marketplace](https://github.com/marketplace/models)的Phi-4模型的示例。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "finish_reason='stop' content='The capital of France is Paris.' usage=RequestUsage(prompt_tokens=14, completion_tokens=8) cached=False logprobs=None\n"
          ]
        }
      ],
      "source": [
        "import os\n",
        "\n",
        "from autogen_core.models import UserMessage\n",
        "from autogen_ext.models.azure import AzureAIChatCompletionClient\n",
        "from azure.core.credentials import AzureKeyCredential\n",
        "\n",
        "client = AzureAIChatCompletionClient(\n",
        "    model=\"Phi-4\",\n",
        "    endpoint=\"https://models.inference.ai.azure.com\",\n",
        "    # 要与模型进行身份验证， 您需要在 GitHub 设置中生成个人访问令牌(PAT)。 请按照此处的说明创建您的 PAT 令牌：\n",
        "    # https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens\n",
        "    credential=AzureKeyCredential(os.environ[\"GITHUB_TOKEN\"]),\n",
        "    model_info={\n",
        "        \"json_output\": False,\n",
        "        \"function_calling\": False,\n",
        "        \"vision\": False,\n",
        "        \"family\": \"unknown\",\n",
        "        \"structured_output\": False,\n",
        "    },\n",
        ")\n",
        "\n",
        "result = await client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
        "print(result)\n",
        "await client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Anthropic (实验性功能)\n\n要使用 {py:class}`~autogen_ext.models.anthropic.AnthropicChatCompletionClient`，您需要安装 `anthropic` 扩展包。底层实现使用 `anthropic` Python SDK 来访问模型。\n您还需要从 Anthropic 获取 [API密钥](https://console.anthropic.com)。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# !pip install -U \"autogen-ext[anthropic]\""
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "finish_reason='stop' content=\"The capital of France is Paris. It's not only the political and administrative capital but also a major global center for art, fashion, gastronomy, and culture. Paris is known for landmarks such as the Eiffel Tower, the Louvre Museum, Notre-Dame Cathedral, and the Champs-Élysées.\" usage=RequestUsage(prompt_tokens=14, completion_tokens=73) cached=False logprobs=None thought=None\n"
          ]
        }
      ],
      "source": [
        "from autogen_core.models import UserMessage\n",
        "from autogen_ext.models.anthropic import AnthropicChatCompletionClient\n",
        "\n",
        "anthropic_client = AnthropicChatCompletionClient(model=\"claude-3-7-sonnet-20250219\")\n",
        "result = await anthropic_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
        "print(result)\n",
        "await anthropic_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Ollama (实验性功能)\n\n[Ollama](https://ollama.com/) 是一个本地模型服务器，可以在您的机器上本地运行模型。\n\n```{note}\n小型本地模型通常不如云端的大型模型能力强。\n对于某些任务，它们的表现可能不尽如人意，输出结果可能会出人意料。\n```\n\n要使用 Ollama，请安装 `ollama` 扩展并使用 {py:class}`~autogen_ext.models.ollama.OllamaChatCompletionClient`。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "vscode": {
          "languageId": "shellscript"
        }
      },
      "outputs": [],
      "source": [
        "pip install -U \"autogen-ext[ollama]\""
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "finish_reason='unknown' content='The capital of France is Paris.' usage=RequestUsage(prompt_tokens=32, completion_tokens=8) cached=False logprobs=None thought=None\n"
          ]
        }
      ],
      "source": [
        "from autogen_core.models import UserMessage\n",
        "from autogen_ext.models.ollama import OllamaChatCompletionClient\n",
        "\n",
        "# 假设您的 Ollama 服务器在本地 11434 端口运行。\n",
        "ollama_model_client = OllamaChatCompletionClient(model=\"llama3.2\")\n",
        "\n",
        "response = await ollama_model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
        "print(response)\n",
        "await ollama_model_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Gemini (实验性功能)\n\nGemini 目前提供了 [OpenAI 兼容的 API (测试版)](https://ai.google.dev/gemini-api/docs/openai)。\n因此您可以使用 {py:class}`~autogen_ext.models.openai.OpenAIChatCompletionClient` 来连接 Gemini API。\n\n```{note}\n虽然某些模型提供商可能提供 OpenAI 兼容的 API，但仍可能存在细微差异。\n例如，响应中的 `finish_reason` 字段可能有所不同。\n\n```\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "finish_reason='stop' content='Paris\\n' usage=RequestUsage(prompt_tokens=7, completion_tokens=2) cached=False logprobs=None thought=None\n"
          ]
        }
      ],
      "source": [
        "from autogen_core.models import UserMessage\n",
        "from autogen_ext.models.openai import OpenAIChatCompletionClient\n",
        "\n",
        "model_client = OpenAIChatCompletionClient(\n",
        "    model=\"gemini-1.5-flash-8b\",\n",
        "    # api_key=\"GEMINI_API_KEY\",\n",
        ")\n",
        "\n",
        "response = await model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
        "print(response)\n",
        "await model_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "此外，随着 Gemini 新增模型，您可能需要通过 model_info 字段定义模型能力。例如，要使用 `gemini-2.0-flash-lite` 或类似的新模型，可以使用以下代码：\n\n```python \nfrom autogen_core.models import UserMessage\nfrom autogen_ext.models.openai import OpenAIChatCompletionClient\nfrom autogen_core.models import ModelInfo\n\nmodel_client = OpenAIChatCompletionClient(\n    model=\"gemini-2.0-flash-lite\",\n    model_info=ModelInfo(vision=True, function_calling=True, json_output=True, family=\"unknown\", structured_output=True)\n    # api_key=\"GEMINI_API_KEY\",\n)\n\nresponse = await model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\nprint(response)\nawait model_client.close()\n```\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Llama API (实验性功能)\n\n[Llama API](https://llama.developer.meta.com?utm_source=partner-autogen&utm_medium=readme) 是 Meta 官方提供的 API 服务。它目前提供了 [OpenAI 兼容的端点](https://llama.developer.meta.com/docs/features/compatibility)。\n因此您可以使用 {py:class}`~autogen_ext.models.openai.OpenAIChatCompletionClient` 来连接 Llama API。\n\n该端点完全支持以下 OpenAI 客户端库功能：\n* 聊天补全\n* 模型选择\n* 温度/采样控制\n* 流式传输\n* 图像理解\n* 结构化输出 (JSON 模式)\n* 函数调用 (工具)\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from pathlib import Path\n",
        "\n",
        "from autogen_core import Image\n",
        "from autogen_core.models import UserMessage\n",
        "from autogen_ext.models.openai import OpenAIChatCompletionClient\n",
        "\n",
        "# 文本\n",
        "model_client = OpenAIChatCompletionClient(\n",
        "    model=\"Llama-4-Scout-17B-16E-Instruct-FP8\",\n",
        "    # api_key=\"LLAMA_API_KEY\"\n",
        ")\n",
        "\n",
        "response = await model_client.create([UserMessage(content=\"Write me a poem\", source=\"user\")])\n",
        "print(response)\n",
        "await model_client.close()\n",
        "\n",
        "# 图片\n",
        "model_client = OpenAIChatCompletionClient(\n",
        "    model=\"Llama-4-Maverick-17B-128E-Instruct-FP8\",\n",
        "    # api_key=\"LLAMA_API_KEY\"\n",
        ")\n",
        "image = Image.from_file(Path(\"test.png\"))\n",
        "\n",
        "response = await model_client.create([UserMessage(content=[\"What is in this image\", image], source=\"user\")])\n",
        "print(response)\n",
        "await model_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Semantic Kernel 适配器\n\n{py:class}`~autogen_ext.models.semantic_kernel.SKChatCompletionAdapter`\n允许你将 Semantic Kernel 模型客户端适配为\n{py:class}`~autogen_core.models.ChatCompletionClient` 接口使用。\n\n使用此适配器需要安装相关的 provider extras。\n\n可安装的 extras 列表：\n\n- `semantic-kernel-anthropic`: 安装此 extra 以使用 Anthropic 模型\n- `semantic-kernel-google`: 安装此 extra 以使用 Google Gemini 模型\n- `semantic-kernel-ollama`: 安装此 extra 以使用 Ollama 模型\n- `semantic-kernel-mistralai`: 安装此 extra 以使用 MistralAI 模型\n- `semantic-kernel-aws`: 安装此 extra 以使用 AWS 模型\n- `semantic-kernel-hugging-face`: 安装此 extra 以使用 Hugging Face 模型\n\n例如，要使用 Anthropic 模型，需要安装 `semantic-kernel-anthropic`。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "vscode": {
          "languageId": "shellscript"
        }
      },
      "outputs": [],
      "source": [
        "# pip install \"autogen-ext[semantic-kernel-anthropic]\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "要使用此适配器，您需要创建一个Semantic Kernel模型客户端并将其传递给适配器。\n\n例如，要使用Anthropic模型：\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "finish_reason='stop' content='The capital of France is Paris. It is also the largest city in France and one of the most populous metropolitan areas in Europe.' usage=RequestUsage(prompt_tokens=0, completion_tokens=0) cached=False logprobs=None\n"
          ]
        }
      ],
      "source": [
        "import os\n",
        "\n",
        "from autogen_core.models import UserMessage\n",
        "from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter\n",
        "from semantic_kernel import Kernel\n",
        "from semantic_kernel.connectors.ai.anthropic import AnthropicChatCompletion, AnthropicChatPromptExecutionSettings\n",
        "from semantic_kernel.memory.null_memory import NullMemory\n",
        "\n",
        "sk_client = AnthropicChatCompletion(\n",
        "    ai_model_id=\"claude-3-5-sonnet-20241022\",\n",
        "    api_key=os.environ[\"ANTHROPIC_API_KEY\"],\n",
        "    service_id=\"my-service-id\",  # 可选；用于定位Semantic Kernel中的特定服务\n",
        ")\n",
        "settings = AnthropicChatPromptExecutionSettings(\n",
        "    temperature=0.2,\n",
        ")\n",
        "\n",
        "anthropic_model_client = SKChatCompletionAdapter(\n",
        "    sk_client, kernel=Kernel(memory=NullMemory()), prompt_settings=settings\n",
        ")\n",
        "\n",
        "# 直接调用模型。\n",
        "model_result = await anthropic_model_client.create(\n",
        "    messages=[UserMessage(content=\"What is the capital of France?\", source=\"User\")]\n",
        ")\n",
        "print(model_result)\n",
        "await anthropic_model_client.close()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "了解更多关于[Semantic Kernel适配器](../../../reference/python/autogen_ext.models.semantic_kernel.rst)的信息。\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": ".venv",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.11.9"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}