跳转到主要内容

文档索引

获取完整文档索引： https://docs.crewai.com.cn/llms.txt

在深入了解之前，请使用此文件来浏览所有可用页面。

Portkey CrewAI Header Image

​
简介

Portkey 通过提供以下功能，为 CrewAI 带来了生产就绪特性，将您的实验性智能体团队转化为稳健的系统：
  • 全面的可观测性：涵盖每个智能体步骤、工具使用和交互
  • 内置可靠性：支持回退（fallback）、重试和负载均衡
  • 成本跟踪与优化：有效管理您的 AI 支出
  • 访问 200 多种大语言模型 (LLM)：通过单一集成即可实现
  • 护栏 (Guardrails)：确保智能体行为安全且合规
  • 版本控制提示词：确保智能体性能的一致性

​
安装与设置

1

安装必要的软件包

pip install -U crewai portkey-ai

生成 API Key

从 Portkey 控制面板创建一个带有可选预算/速率限制的 Portkey API Key。您还可以为此密钥附加用于可靠性、缓存等功能的配置。稍后将详细介绍。
3

将 CrewAI 配置为使用 Portkey

集成非常简单 - 您只需更新 CrewAI 设置中的 LLM 配置即可。
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
		)
什么是虚拟密钥 (Virtual Keys)？ Portkey 中的虚拟密钥将您的 LLM 提供商 API 密钥（如 OpenAI、Anthropic 等）安全地存储在加密保险库中。它们支持更简便的密钥轮换和预算管理。点击此处了解有关虚拟密钥的更多信息。

​
生产级功能

​
1. 增强的可观测性

Portkey 为您的 CrewAI 智能体提供全面的可观测性，帮助您确切了解每次执行期间发生的情况。
追踪功能提供团队执行的分层视图，显示 LLM 调用、工具调用和状态转换的顺序。
# 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 配置，在 CrewAI 设置中启用回退功能非常简单：
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 即可动态获取并应用您的版本化提示词。
Prompt Playground Interface
提示词沙盒是一个用于比较、测试和部署 AI 应用提示词的场所。您可以在此试验不同的模型、测试变量、比较输出，并在部署到生产环境之前优化您的提示词工程策略。它允许您：
  1. 在智能体中使用前进行迭代开发提示词
  2. 使用不同的变量和模型测试提示词
  3. 比较不同提示词版本之间的输出
  4. 与团队成员协作开发提示词
这种可视化环境使得为 CrewAI 智能体工作流的每个步骤打造有效的提示词变得更加容易。

提示词工程工作室

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

​
4. 安全智能体的护栏 (Guardrails)

护栏可确保您的 CrewAI 智能体安全运行，并在所有情况下做出适当的响应。 为什么要使用护栏？ CrewAI 智能体可能会遇到各种失败模式：
  • 生成有害或不当内容
  • 泄露敏感信息（如 PII）
  • 幻觉产生错误信息
  • 生成格式不正确的输出
Portkey 的护栏为输入和输出增加了保护措施。 实现护栏
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
  • 过滤有害或不当内容
  • 针对架构验证响应格式
  • 根据事实依据检查幻觉
  • 应用自定义业务逻辑和规则

了解更多关于护栏的信息

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

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

通过 Portkey 的元数据系统跟踪 CrewAI 智能体中的个人用户。 Portkey 中的元数据是什么？ 元数据允许您将自定义数据与每个请求相关联，从而实现过滤、细分和分析。特殊的 _user 字段专为用户跟踪而设计。
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
)
按用户过滤分析 有了元数据，您可以按用户过滤分析，并基于每个用户分析性能指标：
这实现了：
  • 按用户计算成本和预算
  • 个性化用户分析
  • 团队或组织层面的指标
  • 特定环境监控（分段环境 vs. 生产环境）

了解更多关于元数据的信息

探索如何使用自定义元数据来增强您的分析能力

​
6. 缓存以提高效率

实现缓存以使您的 CrewAI 智能体更高效且更具成本效益。 
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 的访问，扩展了这一能力。您可以轻松切换不同的模型，而无需更改核心智能体逻辑。 
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 等)
  • 本地/私有模型

支持的提供商

查看 Portkey 支持的 LLM 提供商完整列表

​
为 CrewAI 设置企业治理

为什么要进行企业治理？ 如果您在组织内使用 CrewAI，则需要考虑几个治理方面：
  • 成本管理：控制和跟踪跨团队的 AI 支出
  • 访问控制：管理哪些团队可以使用特定模型
  • 使用分析：了解组织内如何使用 AI
  • 安全与合规：维护企业安全标准
  • 可靠性：确保所有用户的服务一致性
Portkey 添加了一个全面的治理层来满足这些企业需求。让我们一步步实现这些控制。
1

创建虚拟密钥

虚拟密钥是 Portkey 管理 LLM 提供商 API 密钥的安全方式。它们提供关键控制，例如：
  • API 使用预算限制
  • 速率限制能力
  • 安全 API 密钥存储
创建虚拟密钥：转到 Portkey 应用中的虚拟密钥页面。保存并复制虚拟密钥 ID。
保存您的虚拟密钥 ID——下一步需要使用它。
2

创建默认配置

Portkey 中的配置定义了请求的路由方式，包含高级路由、回退和重试等功能。创建配置：
  1. 转到 Portkey 控制面板中的配置 (Configs)
  2. 创建新配置，包含： 
    {
    "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1",
   	"override_params": {
      "model": "gpt-4o" // Your preferred model name
    }
}
  3. 保存并记录配置名称以供下一步使用
3

配置 Portkey API Key

现在创建一个 Portkey API Key 并附加您在第 2 步中创建的配置。
  1. 转到 Portkey 中的API 密钥 (API Keys)并创建一个新的 API 密钥。
  2. 从 第 2 步 中选择您的配置。
  3. 生成并保存您的 API 密钥。
4

连接到 CrewAI

设置好带有附加配置的 Portkey API Key 后，将其连接到您的 CrewAI 智能体。
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 步：实施预算控制和速率限制

虚拟密钥能够在团队/部门级别实现对 LLM 访问的细粒度控制。这有助于您：
  • 设置预算限制
  • 通过速率限制防止意外的使用峰值
  • 跟踪部门支出

​
设置特定部门的控制

  1. 导航到 Portkey 控制面板中的虚拟密钥
  2. 为每个部门创建带有预算限制和速率限制的新虚拟密钥
  3. 配置部门特定的限制

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

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

​
访问控制功能

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

​
配置示例

这是一个将请求路由至 OpenAI 并专门使用 GPT-4o 的基本配置：
{
	"strategy": {
		"mode": "single"
	},
	"targets": [
		{
			"virtual_key": "YOUR_OPENAI_VIRTUAL_KEY",
			"override_params": {
				"model": "gpt-4o"
			}
		}
	]
}
在 Portkey 控制面板的配置页面创建您的配置。
配置可以随时更新以调整控制措施，而不会影响正在运行的应用程序。

​
第 3 步：实施访问控制

创建用户特定的 API 密钥，该密钥可自动：
  • 借助虚拟密钥跟踪每个用户/团队的使用情况
  • 应用适当的配置来路由请求
  • 收集相关元数据以过滤日志
  • 强制执行访问权限
通过 Portkey 应用创建 API 密钥使用 Python SDK 的示例：
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 步：部署与监控

将 API 密钥分发给团队成员后，您的企业级 CrewAI 设置即可投入使用。每个团队成员现在都可以使用具有适当访问级别和预算控制的指定 API 密钥。在 Portkey 仪表板中监控使用情况：
  • 按部门跟踪成本
  • 模型使用模式
  • 请求量
  • 错误率

​
企业级功能现已推出

您的 CrewAI 集成现已拥有：
  • 部门预算控制
  • 模型访问治理
  • 使用跟踪与归因
  • 安全护栏
  • 可靠性功能

​
常见问题解答

Portkey 通过全面的可观测性（追踪、日志、指标）、可靠性功能（回退、重试、缓存）以及通过统一接口访问 200 多种 LLM，为 CrewAI 带来了生产就绪特性。这使调试、优化和扩展您的智能体应用程序变得更加容易。
可以！Portkey 可以与现有的 CrewAI 应用程序无缝集成。您只需使用启用 Portkey 的版本更新您的 LLM 配置代码即可。您的其他智能体和团队代码保持不变。
Portkey 支持所有 CrewAI 功能，包括智能体、工具、人机协作工作流以及所有任务处理类型（顺序、分层等）。它在不限制框架任何功能的情况下，增加了可观测性和可靠性。
是的，Portkey 允许您在团队的多个智能体中使用一致的 trace_id 来跟踪整个工作流。对于复杂的团队，如果您想了解跨多个智能体的完整执行路径，这尤其有用。
Portkey 允许您向 LLM 配置添加自定义元数据，然后您可以使用该元数据进行过滤。添加如 crew_name、crew_type 或 session_id 等字段，即可轻松查找和分析特定的团队执行情况。
可以！Portkey 使用您自己的 API 密钥连接各种 LLM 提供商。它将它们安全地存储为虚拟密钥，允许您轻松管理和轮换密钥，而无需更改代码。

​
资源

CrewAI 文档

官方 CrewAI 文档

预约演示

获取实施此集成的个性化指导