Konfiguration der Python-Agent-Umgebung

Bevor wir mit dem Aufbau eines KI-Agenten beginnen, müssen wir eine geeignete Entwicklungsumgebung einrichten.

Python ist die beliebteste Sprache in den Bereichen KI und maschinelles Lernen, mit reicher Bibliotheks- und Tool-Unterstützung.

1. Auswahl der Python-Version

Für die Entwicklung von KI-Agenten empfehlen wir die Verwendung vonPython 3.9 oder höher。

Die folgenden Versionen sind gängige Wahlmöglichkeiten:

• Python 3.9: Gute Stabilität, beste Kompatibilität
• Python 3.10: Leistungsverbesserungen, neue Funktionen
• Python 3.11+: Neueste Version, beste Leistung

Hinweis: Einige Bibliotheken können spezifische Anforderungen an Python-Versionen haben; es wird empfohlen, die offizielle Dokumentation zu überprüfen.

2. Installation von Python

Windows-System

• Besuchedie offizielle Python-Website
• Lade den neuesten Python-Installer herunter (3.9 oder höher)
• Führe den Installer aus,stelle sicher, dassAdd Python to PATH
• Nach Abschluss der Installation öffne die Eingabeaufforderung (CMD) oder PowerShell und gib ein:python --version, die Python-Versionsnummer sollte angezeigt werden.

macOS-System

macOS wird normalerweise mit vorinstalliertem Python geliefert, aber es könnte eine alte Version sein. Es wird empfohlen, mit Homebrew zu installieren:

# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install [email protected]

# 验证安装
python3 --version

Linux-System

Die meisten Linux-Distributionen werden mit vorinstalliertem Python geliefert. Wenn du eine bestimmte Version benötigst:

# Ubuntu/Debian
sudo apt update
sudo apt install python3.9 python3-pip

# CentOS/RHEL
sudo yum install python39 python39-pip

# 验证安装
python3 --version

3. Konfiguration der virtuellen Umgebung

Die Verwendung einer virtuellen Umgebung kann Abhängigkeiten verschiedener Projekte isolieren und Versionskonflikte vermeiden.

Erstellen einer virtuellen Umgebung

# 创建项目目录
mkdir ai-agent-project
cd ai-agent-project

Verwende uv, um eine virtuelle Umgebung zu erstellen und zu aktivieren. Für weitere Details kannst duuv-Tutorial lesen。

uv installieren

pip install uv

Erstellen mit dem uv-Befehl:

# 创建名为 .venv 的虚拟环境（默认）
uv venv

# 激活环境（macOS/Linux）
source .venv/bin/activate

# 激活环境（Windows）
.venv\Scripts\activate

Andere Tools:

# 使用 venv，Python 3.3+ 内置
python -m venv venv

# 或使用 conda（如果已安装 Anaconda/Miniconda）
conda create -n ai-agent python=3.9
conda activate ai-agent

Aktivieren der virtuellen Umgebung

Windows:

venv\Scripts\activate

macOS/Linux:

source venv/bin/activate

Nach der Aktivierung zeigt die Eingabeaufforderung normalerweise den Namen der virtuellen Umgebung an (z. B.(venv)）。

Verlassen der virtuellen Umgebung

deactivate

4. Paketverwaltungstool pip

pip ist Pythons Paketverwaltungstool, das zur Installation von Bibliotheken von Drittanbietern verwendet wird.

Häufige Befehle：

# 升级 pip 到最新版本
pip install --upgrade pip

# 安装包
pip install package_name

# 安装特定版本
pip install package_name==1.2.3

# 从 requirements.txt 安装所有依赖
pip install -r requirements.txt

# 列出已安装的包
pip list

# 生成 requirements.txt
pip freeze > requirements.txt

5. Empfohlene Entwicklungsverzeichnisstruktur

Eine gute Projektstruktur hilft bei der Codeverwaltung und -wartung:

ai-agent-project/
├── .env                    # 环境变量文件（不提交到Git）
├── .gitignore             # Git忽略文件
├── requirements.txt       # 项目依赖
├── README.md             # 项目说明
├── src/                  # 源代码目录
│   ├── __init__.py
│   ├── agents/          # Agent相关代码
│   │   ├── __init__.py
│   │   ├── base_agent.py
│   │   └── weather_agent.py
│   ├── tools/           # 工具定义
│   │   ├── __init__.py
│   │   ├── calculator.py
│   │   └── web_search.py
│   ├── memory/          # 记忆系统
│   │   ├── __init__.py
│   │   ├── short_term.py
│   │   └── vector_memory.py
│   └── utils/           # 工具函数
│       ├── __init__.py
│       ├── config.py
│       └── logger.py
├── tests/               # 测试代码
│   ├── __init__.py
│   ├── test_agents.py
│   └── test_tools.py
├── examples/            # 示例代码
│   ├── basic_agent.py
│   └── multi_tool_agent.py
└── notebooks/           # Jupyter笔记本
    └── experiments.ipynb

Installation wesentlicher Bibliotheken

Die Entwicklung von KI-Agenten erfordert die Unterstützung einer Reihe von Bibliotheken von Drittanbietern. Im Folgenden finden Sie die Installationsmethoden und kurze Einführungen für die Kernbibliotheken.

Installation der Kernbibliotheken

Erstellerequirements.txtDatei, die folgenden Inhalt enthält:

# 基础库
python-dotenv>=1.0.0      # 环境变量管理
pydantic>=2.0.0           # 数据验证和设置管理
loguru>=0.7.0             # 日志记录

# AI/ML 相关
openai>=1.0.0             # OpenAI API
anthropic>=0.7.0          # Claude API
google-generativeai>=0.3.0 # Gemini API
sentence-transformers>=2.2.0 # Embedding 模型
chromadb>=0.4.0           # 向量数据库

# Agent 框架
langchain>=0.1.0          # LangChain 框架
langchain-community>=0.0.10 # LangChain 社区工具
langchain-openai>=0.0.5   # LangChain OpenAI 集成
llama-index>=0.10.0       # LlamaIndex（可选）
semantic-kernel>=0.9.0    # Semantic Kernel（可选）

# 工具和工具
requests>=2.31.0          # HTTP 请求
beautifulsoup4>=4.12.0    # HTML 解析
pandas>=2.0.0             # 数据处理
numpy>=1.24.0             # 数值计算

# 开发工具
pytest>=7.4.0             # 测试框架
black>=23.0.0             # 代码格式化
flake8>=6.0.0             # 代码检查
jupyter>=1.0.0            # Jupyter 笔记本

Alle Abhängigkeiten installieren:

pip install -r requirements.txt

Einführung in wichtige Bibliotheken

1. LangChain

LangChain ist das beliebteste Framework zur Entwicklung von KI-Agenten und bietet Werkzeuge zum Erstellen von Ketten- (Chain) und Agenten- (Agent) Anwendungen.

# LangChain 基本使用示例
from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from langchain.tools import Tool

# 初始化 LLM
llm = ChatOpenAI(temperature=0.7, model="gpt-3.5-turbo")

# 创建工具
tools = [
    Tool(
        name="计算器",
        func=lambda x: str(eval(x)),
        description="用于数学计算"
    )
]

# 创建 Agent
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 运行 Agent
result = agent.run("计算 25 的平方根")
print(result)

2. LlamaIndex

LlamaIndex (früher GPT Index) konzentriert sich auf Dokumentenindexierung und -abruf und eignet sich für den Aufbau dokumentbasierter Q&A-Systeme.

# LlamaIndex 基本使用示例
from llama_index import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms import OpenAI

# 加载文档
documents = SimpleDirectoryReader("./data").load_data()

# 创建索引
index = VectorStoreIndex.from_documents(documents)

# 创建查询引擎
query_engine = index.as_query_engine()

# 查询
response = query_engine.query("文档中提到了哪些AI技术？")
print(response)

3. Semantic Kernel

Semantic Kernel ist ein von Microsoft eingeführtes Framework, das Erweiterbarkeit und Enterprise-Anwendungen betont.

# Semantic Kernel 基本使用示例
import semantic_kernel as sk
from semantic_kernel.connectors.ai.open_ai import OpenAITextCompletion

# 初始化内核
kernel = sk.Kernel()
api_key = "your-openai-api-key"
kernel.add_text_completion_service(
    "dv",
    OpenAITextCompletion("text-davinci-003", api_key)
)

# 定义技能
skill = kernel.import_semantic_skill_from_directory("./skills", "ExampleSkill")

# 运行技能
context = kernel.create_new_context()
context["input"] = "介绍一下人工智能"
result = skill["Summarize"](context)
print(result)

Installationsüberprüfung

Erstellen Sie ein Verifizierungsskriptverify_installation.py：

Verifizierung ausführen:

python verify_installation.py

Fehlerbehebung bei häufigen Installationsproblemen

1. Langsame Installation oder Zeitüberschreitung

# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用阿里云镜像
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

2. Versionskonflikte

# 创建新的虚拟环境
python -m venv new_venv
source new_venv/bin/activate  # oder  venv\Scripts\activate

# 重新安装，让 pip 自动解决依赖
pip install --upgrade pip
pip install langchain openai

3. Spezifische Plattformprobleme (z. B. Apple Silicon)

# 对于 Apple Silicon (M1/M2/M3)，可能需要特定版本
pip install grpcio==1.48.2  # 解决某些兼容性问题

# 或使用 conda
conda install -c conda-forge grpcio

API-Schlüssel-Verwaltung

Die Entwicklung von KI-Agenten erfordert Zugriff auf verschiedene API-Dienste (wie OpenAI, Anthropic, DeepSeek usw.). Die sichere und effektive Verwaltung von API-Schlüsseln ist entscheidend.

1. Warum müssen API-Schlüssel sicher verwaltet werden?

• Lecks verhindern: API-Schlüssel-Lecks können zu finanziellen Verlusten führen
• Zugriffskontrolle: Verwenden Sie unterschiedliche Schlüssel in verschiedenen Umgebungen
• Einfache Konfiguration: Einheitliche Konfigurationsmethode für die Teamzusammenarbeit
• Umgebungsisolierung: Verwenden Sie unterschiedliche Schlüssel für Entwicklungs-, Test- und Produktionsumgebungen

2. Verwaltung von Umgebungsvariablen (empfohlen)

Verwenden Sie.envVerwalten Sie sensible Informationen mit Dateien; committen Sie sie nicht in die Versionskontrolle.

Erstelle.envDatei

# API Keys
OPENAI_API_KEY=sk-你的OpenAI密钥
ANTHROPIC_API_KEY=你的Claude密钥
GOOGLE_API_KEY=你的Gemini密钥
SERPAPI_API_KEY=你的搜索API密钥

# 应用配置
APP_ENV=development
LOG_LEVEL=INFO
DEBUG=true

# 数据库配置（如使用）
VECTOR_DB_PATH=./data/vector_db
MAX_MEMORY_ITEMS=1000

Erstelle.gitignoreDatei

Stellen Sie sicher.envDateien werden nicht in Git committet:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/
env.bak/
venv.bak/

# 环境变量
.env
.env.local
.env.*.local

# 数据文件
data/
*.db
*.sqlite
*.sqlite3

# 日志
logs/
*.log

# 编辑器
.vscode/
.idea/
*.swp
*.swo

Umgebungsvariablen mit python-dotenv laden

3. API-Schlüssel sicher verwenden

Umgebungsvariablen im Code verwenden

import os
from openai import OpenAI

# 从环境变量读取 API Key
api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    raise ValueError("OPENAI_API_KEY 环境变量未设置")

# 初始化 OpenAI 客户端
client = OpenAI(api_key=api_key)

# 使用客户端
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "你好"}]
)

Eine Konfigurationsklasse verwenden

4. Multi-Umgebungskonfiguration

Für große Projekte können unterschiedliche Umgebungskonfigurationen erforderlich sein:

Umgebungsspezifisch.envDatei

# .env.development (开发环境)
OPENAI_API_KEY=sk-dev-key
APP_ENV=development
DEBUG=true

# .env.production (生产环境)
OPENAI_API_KEY=sk-prod-key
APP_ENV=production
DEBUG=false

Umgebungskonfiguration dynamisch laden

# config_manager.py
import os
from pathlib import Path
from dotenv import load_dotenv

class ConfigManager:
    """配置管理器"""

    def __init__(self, env=None):
        self.env = env or os.getenv("APP_ENV", "development")
        self.load_config()

    def load_config(self):
        """加载配置"""
        # 先加载通用配置
        load_dotenv(dotenv_path=Path('.') / '.env')

        # 加载环境特定配置
        env_file = Path('.') / f'.env.{self.env}'
        if env_file.exists():
            load_dotenv(dotenv_path=env_file, override=True)

        # 加载本地覆盖配置（不提交到Git）
        local_file = Path('.') / f'.env.{self.env}.local'
        if local_file.exists():
            load_dotenv(dotenv_path=local_file, override=True)

    def get(self, key, default=None):
        """获取配置值"""
        return os.getenv(key, default)

# 使用示例
config = ConfigManager(env="development")
print(f"当前环境: {config.get('APP_ENV')}")
print(f"API Key: {config.get('OPENAI_API_KEY')[:10]}...")  # 只显示前10个字符

5. Schlüsselrotation und Monitoring

Für Produktionsumgebungen wird empfohlen, Schlüsselrotation und Monitoring zu implementieren:

# key_manager.py
import os
import time
from datetime import datetime, timedelta

class APIKeyManager:
    """API Key 管理器"""

    def __init__(self):
        self.keys = {}
        self.key_history = []
        self.load_keys()

    def load_keys(self):
        """加载 API Keys"""
        # 可以从环境变量、数据库或密钥管理服务加载
        self.keys = {
            "openai": {
                "current": os.getenv("OPENAI_API_KEY"),
                "previous": os.getenv("OPENAI_API_KEY_PREVIOUS"),
                "created_at": datetime.now(),
                "rotation_days": 30  # 30天轮换一次
            },
            "anthropic": {
                "current": os.getenv("ANTHROPIC_API_KEY"),
                "previous": None,
                "created_at": datetime.now(),
                "rotation_days": 30
            }
        }

    def get_key(self, service):
        """获取当前可用的 Key"""
        key_info = self.keys.get(service)
        if not key_info:
            raise ValueError(f"未配置服务 {service} 的 API Key")

        # 检查是否需要轮换
        if self.should_rotate(key_info):
            self.rotate_key(service)

        return key_info["current"]

    def should_rotate(self, key_info):
        """检查是否需要轮换 Key"""
        rotation_days = key_info.get("rotation_days", 30)
        created_at = key_info.get("created_at", datetime.now())

        age = datetime.now() - created_at
        return age.days >= rotation_days

    def rotate_key(self, service):
        """轮换 API Key"""
        # 在实际应用中，这里会从密钥管理服务获取新 Key
        print(f"轮换 {service} 的 API Key...")

        key_info = self.keys[service]
        key_info["previous"] = key_info["current"]
        # 这里应该从安全的地方获取新 Key
        # key_info["current"] = get_new_key_from_vault(service)
        key_info["created_at"] = datetime.now()

        # 记录历史
        self.key_history.append({
            "service": service,
            "rotated_at": datetime.now(),
            "old_key": key_info["previous"][:10] + "..." if key_info["previous"] else None
        })

# 使用示例
key_manager = APIKeyManager()
openai_key = key_manager.get_key("openai")
print(f"OpenAI Key: {openai_key[:10]}...")

Empfohlene Entwicklungstools

Die Wahl der richtigen Entwicklungstools kann die Entwicklungseffizienz erheblich verbessern. Im Folgenden finden Sie einige empfohlene Entwicklungstools.

1. Code-Editor/IDE

Visual Studio Code (empfohlen)

Download-URL：https://code.visualstudio.com/

Empfohlene Erweiterungen：

• Python: Python-Sprachunterstützung
• Pylance: Erweiterter Python-Sprachserver
• Jupyter: Jupyter-Notebook-Unterstützung
• GitLens: Git-Erweiterungen
• Prettier: Codeformatierung
• Code Spell Checker: Rechtschreibprüfung
• Rainbow CSV: CSV-Dateihervorhebung
• Thunder Client: API-Testtool

VS-Code-Konfiguration（.vscode/settings.json）：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": [
        "--line-length",
        "88"
    ],
    "python.testing.pytestEnabled": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": "always"
        }
    },
    "files.exclude": {
        "**/__pycache__": true,
        "**/.pytest_cache": true,
        "**/.venv": true,
        "**/venv": true
    }
}

PyCharm (Professional Edition)

Download-URL：https://www.jetbrains.com/pycharm/

Funktionen：

• Professionelle Python-IDE
• Leistungsstarke Debugging-Funktionen
• Datenbanktool-Integration
• Unterstützung für wissenschaftliches Rechnen

2. Versionskontrolle: Git

Git ist ein unverzichtbares Versionskontrollwerkzeug.

Basiskonfiguration：

# 配置用户信息
git config --global user.name "你的姓名"
git config --global user.email "你的邮箱"

# 配置默认编辑器（可选）
git config --global core.editor "code --wait"

# 创建 Git 仓库
cd ai-agent-project
git init

# 添加所有文件
git add .

# 提交
git commit -m "初始提交：AI Agent 项目"

# 连接到远程仓库（如 GitHub）
git remote add origin https://github.com/你的用户名/ai-agent-project.git
git branch -M main
git push -u origin main

3. Debugging-Tools

Python-Debugger (pdb)

# 在代码中插入断点
import pdb

def complex_function(x):
    pdb.set_trace()  # 这里会进入调试器
    result = x * 2
    return result

# 常用 pdb 命令：
# n(ext) - 执行下一行
# s(tep) - 进入函数
# c(ontinue) - 继续执行
# l(ist) - 显示代码
# p(rint) - 打印变量值
# q(uit) - 退出调试器

VS-Code-Debugging-Konfiguration

.vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        },
        {
            "name": "Python: 测试",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/tests",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

4. Test-Tools

pytest

# tests/test_agent.py
import pytest
from src.agents.base_agent import BaseAgent

def test_agent_initialization():
    """测试 Agent 初始化"""
    agent = BaseAgent(name="测试Agent")
    assert agent.name == "测试Agent"
    assert agent.messages == []

def test_agent_add_message():
    """测试添加消息"""
    agent = BaseAgent()
    agent.add_message("user", "你好")

    assert len(agent.messages) == 1
    assert agent.messages[0]["role"] == "user"
    assert agent.messages[0]["content"] == "你好"

Tests ausführen:

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_agent.py

# 运行特定测试函数
pytest tests/test_agent.py::test_agent_initialization

# 显示详细输出
pytest -v

# 显示覆盖率报告
pytest --cov=src

5. Codequalität und Formatierung

black (Codeformatierung)

# 格式化所有 Python 文件
black .

# 检查哪些文件需要格式化
black --check .

# 格式化单个文件
black src/agents/base_agent.py

flake8 (Codeüberprüfung)

# 检查代码质量
flake8 src/

# 忽略特定错误
flake8 --ignore=E501,W503 src/

# 显示错误统计
flake8 --statistics src/

pre-commit (Git-Hooks)

Erstelle.pre-commit-config.yaml：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--max-line-length=88]

pre-commit installieren:

pip install pre-commit
pre-commit install

6. Dokumentations-Tools

Jupyter Notebook

Für Experimente und Dokumentation:

# 启动 Jupyter
jupyter notebook

# 或使用 JupyterLab
jupyter lab

MkDocs (Dokumentationsgenerierung)

Erstelledocs/Verzeichnis undmkdocs.yml：

site_name: AI Agent 项目文档
site_url: https://your-project.com
nav:
  - 首页: index.md
  - API文档: api.md
  - 使用指南: guide.md
theme: readthedocs

Dokumentation generieren:

# 安装 MkDocs
pip install mkdocs mkdocs-material

# 本地预览
mkdocs serve

# 构建文档
mkdocs build

7. Containerisierungstools (optional)

Docker

Dockerfile：

FROM python:3.9-slim

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY src/ ./src/
COPY .env.example .env

# 设置环境变量
ENV PYTHONPATH=/app

# 运行应用
CMD ["python", "src/main.py"]

docker-compose.yml：

version: '3.8'

services:
  ai-agent:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

8. Monitoring und Logging

loguru (Logging-Bibliothek)

from loguru import logger
import sys

# 配置日志
logger.remove()  # 移除默认处理器
logger.add(
    sys.stderr,
    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
    level="INFO"
)

logger.add(
    "logs/app_{time}.log",
    rotation="500 MB",  # 每500MB轮转
    retention="30 days",  # 保留30天
    compression="zip",  # 压缩旧日志
    level="DEBUG"
)

# 使用日志
logger.info("应用启动")
logger.debug(f"配置加载: {config}")
logger.error("API调用失败", exc_info=True)