Configuration de l'environnement d'agent Python

Avant de commencer à construire un Agent IA, nous devons mettre en place un environnement de développement approprié.

Python est le langage le plus populaire dans les domaines de l'IA et de l'apprentissage automatique, avec un riche support de bibliothèques et d'outils.

1. Sélection de la version de Python

Pour le développement d'agents IA, nous recommandons d'utiliserPython 3.9 ou supérieur。

Les versions suivantes sont des choix courants :

  • Python 3.9: Bonne stabilité, meilleure compatibilité
  • Python 3.10: Améliorations des performances, nouvelles fonctionnalités
  • Python 3.11+: Dernière version, meilleures performances

Remarque: Certaines bibliothèques peuvent avoir des exigences spécifiques concernant les versions de Python ; il est recommandé de consulter la documentation officielle.

2. Installation de Python

Système Windows

  • Visitezle site officiel de Python
  • Téléchargez le dernier programme d'installation de Python (3.9 ou supérieur)
  • Exécutez le programme d'installation,Veillez à cocherAdd Python to PATH
  • Une fois l'installation terminée, ouvrez l'invite de commandes (CMD) ou PowerShell, puis saisissez :python --version, le numéro de version de Python devrait s'afficher.

Système macOS

macOS est généralement livré avec Python préinstallé, mais il peut s'agir d'une ancienne version. Il est recommandé d'installer à l'aide de Homebrew :

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

# 安装 Python
brew install python@3.9

# 验证安装
python3 --version

Système Linux

La plupart des distributions Linux sont livrées avec Python préinstallé. Si vous avez besoin d'une version spécifique :

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

# CentOS/RHEL
sudo yum install python39 python39-pip

# 验证安装
python3 --version

3. Configuration de l'environnement virtuel

L'utilisation d'un environnement virtuel permet d'isoler les dépendances de différents projets et d'éviter les conflits de versions.

Création d'un environnement virtuel

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

Utilisez uv pour créer et activer un environnement virtuel. Pour plus de détails, vous pouvez lireTutoriel uv。

Installer uv

pip install uv

Créez à l'aide de la commande uv :

# 创建名为 .venv 的虚拟环境(默认)
uv venv

# 激活环境(macOS/Linux)
source .venv/bin/activate

# 激活环境(Windows)
.venv\Scripts\activate

Autres outils :

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

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

Activation de l'environnement virtuel

Windows:

venv\Scripts\activate

macOS/Linux:

source venv/bin/activate

Après activation, l'invite de ligne de commande affiche généralement le nom de l'environnement virtuel (par ex.,(venv))。

Quitter l'environnement virtuel

deactivate

4. Outil de gestion des paquets pip

pip est l'outil de gestion des paquets de Python, utilisé pour installer des bibliothèques tierces.

Commandes courantes:

# 升级 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. Structure de répertoires de développement recommandée

Une bonne structure de projet facilite la gestion et la maintenance du code :

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 des bibliothèques essentielles

Le développement d'agents IA nécessite le support d'une série de bibliothèques tierces. Vous trouverez ci-dessous les méthodes d'installation et de brèves présentations des bibliothèques principales.

Installation des bibliothèques principales

Créezrequirements.txtfichier, contenant le contenu suivant :

# 基础库
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 笔记本

Installez toutes les dépendances :

pip install -r requirements.txt

Introduction aux principales bibliothèques

1. LangChain

LangChain est le framework de développement d'agents IA le plus populaire, offrant des outils pour créer des applications de chaînes (Chain) et d'agents (Agent).

# 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 (anciennement GPT Index) se concentre sur l'indexation et la récupération de documents, adapté à la création de systèmes de questions-réponses basés sur des documents.

# 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 est un framework lancé par Microsoft, mettant l'accent sur l'extensibilité et les applications de niveau entreprise.

# 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)

Vérification de l'installation

Créer un script de vérificationverify_installation.py:

Exemple

# verify_installation.py
import sys

def check_package(package_name, import_name=None):
    Vérifier si le paquet est installé
    import_name = import_name or package_name
    try:
        __import__(import_name)
        print(f{package_name} installé avec succès)
        return True
    except ImportError:
        print(f{package_name} n'est pas installé)
        return False

def main():
    print(Vérification de l'environnement de développement d'agent IA...)
    print("=" * 50)

    # Vérifier la version de Python
    python_version = sys.version_info
    print(fVersion de Python : {python_version.major}.{python_version.minor}.{python_version.micro})
    if python_version.major == 3 and python_version.minor >= 9:
        print(La version de Python répond aux exigences (>=3.9))
    else:
        print(La version de Python ne répond pas aux exigences ; 3.9 ou supérieur est requis.)

    print("\nVérification des bibliothèques principales...)

    # Bibliothèques de base
    check_package("dotenv", "dotenv")
    check_package("pydantic")
    check_package("loguru")

    # Bibliothèques IA/ML
    check_package("openai")
    check_package("anthropic")
    check_package("chromadb")
    check_package("sentence_transformers", "sentence_transformers")

    # Frameworks d'agents
    check_package("langchain")
    check_package("llama_index", "llama_index")

    # Bibliothèques d'outils
    check_package("requests")
    check_package("pandas")
    check_package("numpy")

    print("\n" + "=" * 50)
    print(Vérification de l'environnement terminée !)

if __name__ == "__main__":
    main()

Lancer la vérification :

python verify_installation.py

Dépannage des problèmes d'installation courants

1. Installation lente ou délai d'attente dépassé

# 使用国内镜像源
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. Conflits de versions

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

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

3. Problèmes spécifiques à une plateforme (par ex., Apple Silicon)

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

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

Gestion des clés API

Le développement d'agents IA nécessite l'accès à divers services API (tels qu'OpenAI, Anthropic, DeepSeek, etc.). La gestion sécurisée et efficace des clés API est cruciale.

1. Pourquoi devez-vous gérer les clés API en toute sécurité ?

  • Prévenir les fuites: les fuites de clés API peuvent entraîner des pertes financières
  • Contrôle d'accès: utilisez différentes clés dans différents environnements
  • Configuration facile: méthode de configuration unifiée pour la collaboration d'équipe
  • Isolation des environnements: utilisez différentes clés pour les environnements de développement, de test et de production

2. Gestion des variables d'environnement (recommandée)

Utiliser.envGérer les informations sensibles avec des fichiers ; ne pas les valider dans le contrôle de version.

Créez.envFichier

# 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

Créez.gitignoreFichier

Assurez-vous.envLes fichiers ne sont pas validés dans Git :

# 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

Charger les variables d'environnement avec python-dotenv

Exemple

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

# Charger le fichier .env
env_path = Path('.') / '.env'
load_dotenv(dotenv_path=env_path)

class Config:
    """Configuration de l'application"""

    # Clés API
    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
    ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
    GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
    SERPAPI_API_KEY = os.getenv("SERPAPI_API_KEY")

    # Configuration de l'application
    APP_ENV = os.getenv("APP_ENV", "development")
    LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
    DEBUG = os.getenv("DEBUG", "false").lower() == "true"

    # Configuration de la base de données
    VECTOR_DB_PATH = os.getenv("VECTOR_DB_PATH", "./data/vector_db")
    MAX_MEMORY_ITEMS = int(os.getenv("MAX_MEMORY_ITEMS", "1000"))

    @classmethod
    def validate(cls):
        """Valider la configuration requise"""
        missing = []

        if not cls.OPENAI_API_KEY:
            missing.append("OPENAI_API_KEY")

        if missing:
            raise ValueError(f"Variables d'environnement requises manquantes : {', '.join(missing)}")

# Exemple d'utilisation
config = Config()
print(f"Environnement : {config.APP_ENV}")
print(f"Mode débogage : {config.DEBUG}")

3. Utilisation sécurisée des clés API

Utiliser les variables d'environnement dans le code

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": "你好"}]
)

Utiliser une classe de configuration

Exemple

from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI
from config import Config

class LLMClientFactory:
    """Fabrique de clients LLM"""

    @staticmethod
    def create_openai_client(model="gpt-3.5-turbo", **kwargs):
        """Créer un client OpenAI"""
        Config.validate()  # Vérifier la configuration

        return ChatOpenAI(
            model=model,
            openai_api_key=Config.OPENAI_API_KEY,
            temperature=kwargs.get("temperature", 0.7),
            max_tokens=kwargs.get("max_tokens", 1000)
        )

    @staticmethod
    def create_anthropic_client(model="claude-3-sonnet-20240229", **kwargs):
        """Créer un client Anthropic"""
        from langchain.chat_models import ChatAnthropic

        Config.validate()

        return ChatAnthropic(
            model=model,
            anthropic_api_key=Config.ANTHROPIC_API_KEY,
            temperature=kwargs.get("temperature", 0.7),
            max_tokens=kwargs.get("max_tokens", 1000)
        )

# Exemple d'utilisation
llm = LLMClientFactory.create_openai_client()
response = llm.predict(Bonjour, veuillez vous présenter)
print(response)

4. Configuration multi-environnements

Pour les grands projets, différentes configurations d'environnement peuvent être nécessaires :

Spécifique à l'environnement.envFichier

# .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

Charger dynamiquement la configuration d'environnement

# 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. Rotation et surveillance des clés

Pour les environnements de production, il est recommandé de mettre en œuvre la rotation et la surveillance des clés :

# 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]}...")

Outils de développement recommandés

Choisir les bons outils de développement peut grandement améliorer l'efficacité du développement. Voici quelques outils de développement recommandés.

1. Éditeur de code/IDE

Visual Studio Code (recommandé)

URL de téléchargement:https://code.visualstudio.com/

Extensions recommandées:

  • Python: Prise en charge du langage Python
  • Pylance: Serveur de langage Python avancé
  • Jupyter: Prise en charge des notebooks Jupyter
  • GitLens: Améliorations Git
  • Prettier: Formatage du code
  • Code Spell Checker: Vérification orthographique
  • Rainbow CSV: Coloration syntaxique des fichiers CSV
  • Thunder Client: Outil de test d'API

Configuration de VS Code(.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 (Édition professionnelle)

URL de téléchargement:https://www.jetbrains.com/pycharm/

Fonctionnalités:

  • IDE Python professionnel
  • Fonctionnalités de débogage puissantes
  • Intégration d'outils de base de données
  • Prise en charge du calcul scientifique

2. Gestion de version : Git

Git est un outil essentiel de gestion de version.

Configuration de base:

# 配置用户信息
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. Outils de débogage

Débogueur Python (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) - 退出调试器

Configuration de débogage de VS Code

.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. Outils de test

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"] == "你好"

Exécuter les tests :

# 运行所有测试
pytest

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

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

# 显示详细输出
pytest -v

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

5. Qualité du code et formatage

black (formatage du code)

# 格式化所有 Python 文件
black .

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

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

flake8 (vérification du code)

# 检查代码质量
flake8 src/

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

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

pre-commit (hooks Git)

Créez.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]

Installer pre-commit :

pip install pre-commit
pre-commit install

6. Outils de documentation

Jupyter Notebook

Pour les expérimentations et la documentation :

# 启动 Jupyter
jupyter notebook

# 或使用 JupyterLab
jupyter lab

MkDocs (génération de documentation)

Créezdocs/répertoire etmkdocs.yml:

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

Générer la documentation :

# 安装 MkDocs
pip install mkdocs mkdocs-material

# 本地预览
mkdocs serve

# 构建文档
mkdocs build

7. Outils de conteneurisation (facultatif)

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. Surveillance et journalisation

loguru (bibliothèque de journalisation)

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)
Autres extensions