BytesRouter

主题

CrewAI 文档版本 跟随上游 源快照 506086c9 更新于 2026-10-18

Portkey 集成

如何将 Portkey 与 CrewAI 一起使用

Portkey CrewAI Header Image

引言

Portkey 通过提供以下能力，以生产就绪特性增强 CrewAI，将你的实验性智能体团队转变为稳健系统：

  • 完整可观测性，覆盖每个智能体步骤、工具使用和交互
  • 内置可靠性，支持回退、重试和负载均衡
  • 成本跟踪与优化，管理你的 AI 支出
  • 访问 200+ LLM，通过单一集成
  • 护栏，确保智能体行为安全合规
  • 版本控制的提示词，确保智能体性能一致

安装与设置

Install the required packages

bash
pip install -U crewai portkey-ai

Generate API Key

从 Portkey 仪表板 创建 Portkey API 密钥，并可选择设置预算/速率限制。你还可以为此密钥附加可靠性、缓存等配置。稍后将详细介绍。

Configure CrewAI with Portkey

集成很简单——你只需更新 CrewAI 设置中的 LLM 配置：

python
from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create an LLM instance with Portkey integration
gpt_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",  # We are using a Virtual key, so this is a placeholder
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_LLM_VIRTUAL_KEY",
        trace_id="unique-trace-id",               # Optional, for request tracing
    )
)

#Use them in your Crew Agents like this:

	@agent
	def lead_market_analyst(self) -> Agent:
		return Agent(
			config=self.agents_config['lead_market_analyst'],
			verbose=True,
			memory=False,
			llm=gpt_llm
		)

INFO

什么是虚拟密钥？ Portkey 中的虚拟密钥会将你的 LLM 服务商 API 密钥（OpenAI、Anthropic 等）安全地存储在加密保险库中。它们使密钥轮换和预算管理更加容易。在此了解更多关于虚拟密钥的信息。

生产特性

1. 增强的可观测性

Portkey 为你的 CrewAI 智能体提供全面的可观测性，帮助你准确了解每次执行期间发生的情况。

追踪提供你的团队执行的分层视图，显示 LLM 调用、工具调用和状态转换的顺序。

python
# Add trace_id to enable hierarchical tracing in Portkey
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        trace_id="unique-session-id"  # Add unique trace ID
    )
)

2. 可靠性——让你的团队平稳运行

在生产环境中运行团队时，可能会出现问题——API 速率限制、网络问题或服务商中断。Portkey 的可靠性特性确保你的智能体即使在出现问题时也能平稳运行。

通过使用 Portkey Config，在你的 CrewAI 设置中启用回退很简单：

python
from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create LLM with fallback configuration
portkey_llm = LLM(
    model="gpt-4o",
    max_tokens=1000,
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        config={
            "strategy": {
                "mode": "fallback"
            },
            "targets": [
                {
                    "provider": "openai",
                    "api_key": "YOUR_OPENAI_API_KEY",
                    "override_params": {"model": "gpt-4o"}
                },
                {
                    "provider": "anthropic",
                    "api_key": "YOUR_ANTHROPIC_API_KEY",
                    "override_params": {"model": "claude-3-opus-20240229"}
                }
            ]
        }
    )
)

# Use this LLM configuration with your agents

如果 GPT-4o 请求失败，此配置将自动尝试 Claude，确保你的团队能够继续运行。

Automatic Retries

自动处理临时故障。如果 LLM 调用失败，Portkey 会按指定次数重试同一请求——非常适合应对速率限制或网络波动。

Request Timeouts

防止你的智能体挂起。设置超时以确保你在要求的时间范围内获得响应（或能够优雅失败）。

Conditional Routing

将不同请求发送到不同服务商。根据你的需求，将复杂推理路由到 GPT-4，将创意任务路由到 Claude，将快速响应路由到 Gemini。

Fallbacks

即使主服务商失败也能继续运行。自动切换到备用服务商以保持可用性。

Load Balancing

将请求分散到多个 API 密钥或服务商。非常适合高流量团队操作并保持在速率限制之内。

3. 在 CrewAI 中进行提示词设计

Portkey 的 Prompt Engineering Studio 帮助你创建、管理和优化 CrewAI 智能体中使用的提示词。无需硬编码提示词或指令，使用 Portkey 的提示词渲染 API 动态获取并应用你带版本的提示词。

提示词 Playground 界面

Manage prompts in Portkey's Prompt Library

提示词游乐场是用于为你的 AI 应用比较、测试和部署完美提示词的地方。你可以在这里试验不同模型、测试变量、比较输出，并在部署到生产环境之前优化你的提示词工程策略。它允许你：

  1. 在智能体中使用提示词之前迭代开发提示词
  2. 使用不同变量和模型测试提示词
  3. 比较不同提示词版本之间的输出
  4. 与团队成员协作开发提示词

这种可视化环境让你更容易为 CrewAI 智能体工作流中的每个步骤编写有效的提示词。

Prompt Engineering Studio

了解更多关于 Portkey 提示词管理功能的信息

4. 用于安全团队的护栏

护栏确保你的 CrewAI 智能体安全运行，并在所有情况下做出恰当响应。

为什么要使用护栏？

CrewAI 智能体可能会遇到各种故障模式：

  • 生成有害或不适当的内容
  • 泄露 PII 等敏感信息
  • 幻觉生成错误信息
  • 以错误格式生成输出

Portkey 的护栏为输入和输出都增加了保护。

实施护栏

python
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create LLM with guardrails
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "input_guardrails": ["guardrails-id-xxx", "guardrails-id-yyy"],
            "output_guardrails": ["guardrails-id-zzz"]
        }
    )
)

# Create agent with guardrailed LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

Portkey 的护栏可以：

  • 检测并脱敏输入和输出中的 PII
  • 过滤有害或不适当的内容
  • 根据 schema 校验响应格式
  • 对照真实基准检查是否存在幻觉
  • 应用自定义业务逻辑和规则

Learn More About Guardrails

探索 Portkey 的护栏功能，以增强智能体安全性

5. 使用元数据进行用户跟踪

使用 Portkey 的元数据系统，通过你的 CrewAI 智能体跟踪单个用户。

Portkey 中的元数据是什么？

元数据允许你将自定义数据与每个请求关联起来，从而实现筛选、分段和分析。特殊的 _user 字段专为用户跟踪而设计。

python
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLM with user tracking
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        metadata={
            "_user": "user_123",  # Special _user field for user analytics
            "user_tier": "premium",
            "user_company": "Acme Corp",
            "session_id": "abc-123"
        }
    )
)

# Create agent with tracked LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

按用户筛选分析

配置好元数据后，你可以按用户筛选分析，并按用户分析性能指标：

Filter analytics by user

这使你能够：

  • 按用户跟踪成本和预算
  • 个性化用户分析
  • 团队或组织级指标
  • 特定环境监控（暂存环境与生产环境）

Learn More About Metadata

探索如何使用自定义元数据增强你的分析

6. 为高效团队设置缓存

实施缓存，让你的 CrewAI 智能体更高效、更具成本效益：

python
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLM with simple caching
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "cache": {
                "mode": "simple"
            }
        }
    )
)

# Create agent with cached LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

简单缓存会对输入提示词执行精确匹配，缓存相同的请求以避免重复的模型执行。

7. 模型互操作性

CrewAI 支持多个 LLM 服务商，而 Portkey 通过统一接口提供对 200 多个 LLM 的访问，从而扩展了这一能力。你可以轻松切换不同模型，而无需更改核心智能体逻辑：

python
from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Set up LLMs with different providers
openai_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY"
    )
)

anthropic_llm = LLM(
    model="claude-3-5-sonnet-latest",
    max_tokens=1000,
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY"
    )
)

# Choose which LLM to use for each agent based on your needs
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=openai_llm  # Use anthropic_llm for Anthropic
)

Portkey 提供对以下服务商 LLM 的访问：

  • OpenAI（GPT-4o、GPT-4 Turbo 等）
  • Anthropic（Claude 3.5 Sonnet、Claude 3 Opus 等）
  • Mistral AI（Mistral Large、Mistral Medium 等）
  • Google Vertex AI（Gemini 1.5 Pro 等）
  • Cohere（Command、Command-R 等）
  • AWS Bedrock（Claude、Titan 等）
  • 本地/私有模型

Supported Providers

查看 Portkey 支持的 LLM 服务商完整列表

为 CrewAI 设置企业版治理

为什么需要企业版治理？ 如果你在组织内部使用 CrewAI，需要考虑几个治理方面：

  • 成本管理：控制和跟踪各团队的 AI 支出
  • 访问控制：管理哪些团队可以使用特定模型
  • 使用分析：了解 AI 在整个组织中的使用情况
  • 安全与合规：维持企业安全标准
  • 可靠性：确保所有用户获得一致的服务

Portkey 增加了全面的治理层来满足这些企业需求。让我们逐步实施这些控制措施。

Create Virtual Key

Virtual Keys 是 Portkey 安全管理 LLM 服务商 API 密钥的方式。它们提供以下关键控制：

  • API 使用预算限制
  • 限流能力
  • 安全的 API 密钥存储

要创建虚拟密钥： 前往 Portkey App 中的 虚拟密钥。保存并复制虚拟密钥 ID

NOTE

保存你的虚拟密钥 ID——下一步会用到它。

Create Default Config

Portkey 中的配置定义了请求的路由方式，并包含高级路由、回退和重试等功能。

要创建你的配置：

  1. 前往 Portkey 仪表盘中的配置
  2. 创建一个新配置，包含：
    json
    {
    "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1",
   	"override_params": {
      "model": "gpt-4o" // Your preferred model name
    }
}
  3. 保存并记下配置名称，供下一步使用

Configure Portkey API Key

现在创建一个 Portkey API 密钥，并附加你在第 2 步中创建的配置：

  1. 前往 Portkey 中的 API 密钥并创建新的 API 密钥
  2. 从 第 2 步 中选择你的配置
  3. 生成并保存你的 API 密钥

Connect to CrewAI

设置好附带了配置的 Portkey API 密钥后，将其连接到你的 CrewAI 智能体：

python
from crewai import Agent, LLM
from portkey_ai import PORTKEY_GATEWAY_URL

# Configure LLM with your API key
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="YOUR_PORTKEY_API_KEY"
)

# Create agent with Portkey-enabled LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)
第 1 步：实施预算控制与限流

第 1 步：实施预算控制与限流

虚拟密钥可在团队/部门级别对 LLM 访问进行细粒度控制。这有助于你：

  • 设置预算限制
  • 使用限流防止意外用量激增
  • 跟踪部门支出

设置部门专属控制：

  1. 前往 Portkey 仪表盘中的虚拟密钥
  2. 为每个部门创建新的虚拟密钥，并设置预算限制和限流
  3. 配置部门专属限制
第 2 步：定义模型访问规则

第 2 步：定义模型访问规则

随着 AI 使用规模扩大，控制哪些团队可以访问特定模型变得至关重要。Portkey 配置通过以下功能提供这一控制层：

访问控制功能：

  • 模型限制：限制对特定模型的访问
  • 数据保护：为敏感数据实施护栏
  • 可靠性控制：添加回退和重试逻辑

示例配置：

以下是一个将请求路由到 OpenAI（特别是使用 GPT-4o）的基础配置：

json
{
	"strategy": {
		"mode": "single"
	},
	"targets": [
		{
			"virtual_key": "YOUR_OPENAI_VIRTUAL_KEY",
			"override_params": {
				"model": "gpt-4o"
			}
		}
	]
}

在 Portkey 仪表盘的配置页面上创建你的配置。

NOTE

配置可以随时更新，以调整控制措施而不影响正在运行的应用。

第 3 步：实现访问控制

第 3 步：实现访问控制

创建用户专属 API 密钥，使其自动：

  • 借助虚拟密钥按用户/团队跟踪用量
  • 应用合适的配置来路由请求
  • 收集相关元数据以筛选日志
  • 强制执行访问权限

通过 Portkey App 创建 API 密钥

使用 Python SDK 的示例：

python
from portkey_ai import Portkey

portkey = Portkey(api_key="YOUR_ADMIN_API_KEY")

api_key = portkey.api_keys.create(
    name="engineering-team",
    type="organisation",
    workspace_id="YOUR_WORKSPACE_ID",
    defaults={
        "config_id": "your-config-id",
        "metadata": {
            "environment": "production",
            "department": "engineering"
        }
    },
    scopes=["logs.view", "configs.read"]
)

有关详细的密钥管理说明，请参阅 Portkey 文档。

第 4 步：部署与监控

第 4 步：部署与监控

将 API 密钥分发给团队成员后，你企业版就绪的 CrewAI 设置即可使用。每位团队成员现在都可以使用其指定的 API 密钥，并具备适当的访问级别和预算控制。

在 Portkey 仪表板中监控用量：

  • 按部门进行成本跟踪
  • 模型使用模式
  • 请求量
  • 错误率

NOTE

企业版功能现已可用

你的 CrewAI 集成现在具备：

  • 部门预算控制
  • 模型访问治理
  • 用量跟踪与归因
  • 安全护栏
  • 可靠性功能

常见问题

Portkey 如何增强 CrewAI？

Portkey 通过全面的可观测性（追踪、日志、指标）、可靠性功能（回退、重试、缓存），以及通过统一接口访问 200+ LLM，为 CrewAI 增加生产就绪能力。这使你更容易调试、优化和扩展智能体应用。

我可以将 Portkey 与现有的 CrewAI 应用一起使用吗？

可以！Portkey 可与现有 CrewAI 应用无缝集成。你只需将 LLM 配置代码更新为启用 Portkey 的版本。其余智能体和团队代码保持不变。

Portkey 是否适用于所有 CrewAI 功能？

Portkey 支持所有 CrewAI 功能，包括智能体、工具、人在回路工作流，以及所有任务流程类型（顺序流程、层级流程等）。它增加可观测性和可靠性，同时不会限制框架的任何功能。

我可以跟踪一个团队中多个智能体的用量吗？

可以，Portkey 允许你在一个团队的多个智能体之间使用一致的 trace_id 来跟踪整个工作流。这对于复杂团队尤其有用，因为你想了解跨多个智能体的完整执行路径。

如何针对特定团队运行筛选日志和追踪？

Portkey 允许你向 LLM 配置添加自定义元数据，然后可将其用于筛选。添加 crew_name、crew_type 或 session_id 等字段，即可轻松查找和分析特定团队执行。

我可以将自有 API 密钥与 Portkey 一起使用吗？

可以！Portkey 会针对各种 LLM 服务商使用你的自有 API 密钥。它将这些密钥安全地存储为虚拟密钥，使你无需更改代码即可轻松管理和轮换密钥。

资源

CrewAI Docs

官方 CrewAI 文档

Book a Demo

获取关于实现此集成的个性化指导

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可