Film instruktażowy
Część 1: Omówienie kroków
- Tworzenie Dokumentacji w Markdown
Każdy z głównych plików (index.py, types.dt.py, pliki z katalogu lib/) powinien być opisany w dokumentacji technicznej. Poniżej przedstawiam pliki Markdown z pełną zawartością.
Plik README.md
README.md zawiera ogólne informacje o projekcie, jego działaniu, zależnościach oraz instrukcje uruchomienia.
Opis
Projekt AI Dev Agent to aplikacja umożliwiająca interakcję z modelem AI w celu realizacji określonych zadań. Skonfigurowany jest do pracy z różnymi narzędziami do przetwarzania tekstu i integracji z modelem Anthropic Claude.
Struktura Projektu
- index.py - główny plik aplikacji uruchamiający serwer Flask i obsługujący żądania.
- lib/ - folder zawierający wszystkie dodatkowe moduły:
- ai.py - obsługa API dla modelu Anthropic.
- agent.py - logika podejmowania decyzji i wykonania zadań przez agenta.
- prompts.py - definicje promptów dla agenta.
- tools.py - zestaw narzędzi do pobierania treści, przesyłania plików i innych działań.
- ssh_manager.py - zarządzanie połączeniami SSH i wykonywanie poleceń
- task_manager.py - zarządzanie zadaniami.
- types.dt.py - definicje typów danych i struktury stanu agenta.
- config.py - zmienne środowiskowe
- config.yml - zmienne środowiskowe
- .env - klucze API
Instalacja
1.Sklonuj repozytorium.
| |
2.Zainstaluj Ansible i uruchom playbook site.yml 3.Uruchom środowisko wirtualne 4.Uruchom serwer
| |
Użycie
Wysyłaj żądania POST do głównego punktu końcowego / z odpowiednią treścią wiadomości.
Plik log.md
log.md służy do zapisywania wyników działań agenta w formacie Markdown.
markdown
Log Operacji Agenta
Tutaj będą zapisywane wszystkie operacje wykonane przez agenta w czasie rzeczywistym.
Struktura Logów
Każda operacja zostanie opisana wraz z jej typem, nagłówkiem oraz treścią.
Przykład
[Typ Operacji] Nagłówek
Treść operacji…
Część 2: Ręczne tworzenie struktury projektu i konfiguracja środowiska
1. Tworzenie struktury katalogów projektu i plików
Utwórz główny katalog projektu i przejdź do niego:
1 2mkdir aidevs cd aidevsUtwórz strukturę katalogów i plikow w lib:
1 2 3mkdir -p lib cd lib touch agent.py ai.py prompts.py tools.pyUtwórz pliki projektu w odpowiednich katalogach:
1touch .env asgi_app.py config.py config.yml index.py requirements.txt ssh_manager.py task_manager.py types.dt.py
Pliki są tworzone w głównym katalogu projektu (ai_dev_agent), ponieważ pełnią podstawowe funkcje dla całego projektu i nie są specyficzne dla żadnego podkatalogu.
2. Konfiguracja środowiska wirtualnego i pliku requirements.txt
Utwórz i aktywuj środowisko wirtualne:
1 2python3 -m venv venv source venv/bin/activate # Linux/macOS
Dodaj do .bashrc to:
| |
A potem wykonaj to:
| |
Dodaj wymagane pakiety do pliku
requirements.txt:1 2 3 4 5 6 7 8 9 10 11 12openai asyncssh markdown2 python-dotenv ansible-lint flask anthropic playwright markdownify httpx quart uvicornZainstaluj pakiety z
requirements.txt:1pip install -r requirements.txt
3. Konfiguracja pliku .env
Utwórz plik
.envw głównym katalogu projektu z kluczami API:1 2 3 4OPENAI_API_KEY=your_openai_api_key OPENROUTER_API_KEY=your_openrouter_api_key ANTHROPIC_API_KEY=your_anthropic_api_key LLAMA_PATH=path_to_your_local_llama_model
Część 3: Tworzenie głównej logiki agenta i innych plików
1.Plik index.py – serves as the main entry point for the Flask-based server and handles various HTTP requests related to the AI agent’s functionality.
| |
Pełne wyjaśnienie sekcji w pliku index.py
1. Inicjalizacja i konfiguracja
Flask jako framework
Quartjest asynchroniczną wersjąFlaski obsługuje zarówno synchroniczne, jak i asynchroniczne endpointy.- Aplikacja jest definiowana i przypisywana do zmiennej
app.
Ładowanie zmiennych środowiskowych
dotenvjest używany do ładowania kluczowych zmiennych środowiskowych, takich jak klucz API Anthropic.
Inicjalizacja klasy
AIAgent- Klasa
AIAgentzarządza logiką działania agenta AI i komunikuje się z modelem przez klientaAnthropicCompletion.
- Klasa
2. Struktura klasy AIAgent
Atrybuty stanu (
state)- Przechowują informacje o bieżącym etapie (
currentStage), wiadomościach użytkownika (messages) i działaniach podjętych przez agenta (actionsTaken).
- Przechowują informacje o bieżącym etapie (
Pętla przetwarzania (
run)- Przetwarza wiadomość użytkownika w kolejnych etapach:
plan,decide,describe,execute,reflect. - Kończy się, gdy osiągnięty zostanie etap
final_answerlub przekroczony zostanie limit kroków.
- Przetwarza wiadomość użytkownika w kolejnych etapach:
Metody etapowe
_plantworzy plan działania na podstawie wiadomości użytkownika._decidewybiera kolejne narzędzie lub decyduje o zakończeniu działania._describegeneruje dane wejściowe do wybranego narzędzia._executewykonuje wybrane narzędzie i zapisuje wyniki._reflectanalizuje wyniki i aktualizuje plan.
Metoda
final_answer- Tworzy odpowiedź końcową i wysyła ją do użytkownika na podstawie zgromadzonych danych.
Debugowanie
- Logi debugowania, takie jak
[DEBUG], pomagają śledzić działanie agenta na każdym etapie.
- Logi debugowania, takie jak
3. Endpoint process_request
- Obsługuje żądania POST na adres
/- Pobiera dane w formacie JSON, analizuje je i przetwarza za pomocą
AIAgent. - Tworzy instancję
AIAgenti wywołuje metodęrunz wiadomością użytkownika. - Zwraca odpowiedź agenta lub kod błędu, jeśli wystąpi problem.
- Pobiera dane w formacie JSON, analizuje je i przetwarza za pomocą
4. Obsługa błędów
- Obsługa wyjątków
- Każdy etap działania i endpoint są opakowane w bloki try-except, aby obsłużyć błędy i zwrócić odpowiednie informacje w odpowiedzi HTTP.
5. Logowanie
_log_to_markdown- Dane o działaniach agenta są zapisywane w pliku
log.md, co umożliwia ich analizę.
- Dane o działaniach agenta są zapisywane w pliku
- Logi debugowania
[DEBUG]wyświetlają szczegóły dotyczące przetwarzanych danych i etapów działania.
6. Kluczowe elementy
Asynchroniczność
- Wszystkie operacje są asynchroniczne, co umożliwia obsługę wielu żądań jednocześnie.
Integracja z AnthropicCompletion
- Klasa
AnthropicCompletionobsługuje komunikację z modelem AI, przetwarzając dane wejściowe i generując odpowiedzi.
- Klasa
7. Potencjalne rozszerzenia
Dodawanie nowych endpointów
- Można dodać funkcje do obsługi nowych narzędzi lub funkcjonalności agenta.
Optymalizacja logiki
- Można wprowadzić bardziej zaawansowane mechanizmy decyzyjne, aby zwiększyć elastyczność.
Lepsze logowanie
- Można wdrożyć system logowania oparty na module
loggingzamiast używać standardowegoprint.
- Można wdrożyć system logowania oparty na module
Plik index.py stanowi serce aplikacji, które zarządza przepływem danych między użytkownikiem, agentem AI i serwerem, umożliwiając realizację zadań w sposób skalowalny i efektywny.
2.Plik types.dt.py – zawiera definicje typów danych:
| |
Wyjaśnienie
Stage: Typ
Literaldefiniujący różne etapy działania agenta, w których może się znajdować (init,plan,decide,describe,reflect,executeorazfinal).ITool:
TypedDict, który opisuje narzędzie za pomocą trzech pól:name: Nazwa narzędzia.instruction: Instrukcje dotyczące użycia narzędzia.description: Krótki opis działania narzędzia.
IAction:
TypedDictreprezentujący akcję wykonaną przez agenta AI, zawierający pola:name: Nazwa akcji.payload: Dane wejściowe lub ładunek dla akcji.result: Wynik lub rezultat akcji.reflection: Refleksja lub dodatkowe informacje o akcji.tool: Narzędzie użyte do wykonania akcji.
IState:
TypedDictdefiniujący pełny stan agenta AI, zawierający klucze:systemPrompt: Bieżący prompt systemowy, który kieruje działaniem agenta.messages: Lista wiadomości w rozmowie.currentStage: Etap operacji, na którym znajduje się agent.currentStep: Bieżący krok w wykonaniu agenta.maxSteps: Maksymalna liczba kroków dozwolona dla agenta.activeTool: Obecnie używane narzędzie.activeToolPayload: Ładunek dla aktywnego narzędzia.plan: Bieżący plan działania agenta.actionsTaken: Lista wszystkich wykonanych dotychczas akcji.
Ten plik definiuje wszystkie typy potrzebne do zarządzania stanem i śledzenia akcji w ramach przepływu pracy agenta AI w sposób uporządkowany i bezpieczny typowo.
3.Plik task_manager.py - zarządzanie zadaniami:
| |
4.Plik ssh_manager.py – asynchroniczne połączenie SSH:
| |
Pliki w katalogu lib
1.Plik ai.py - Kod odpowiedzialny za obsługę API Anthropic
| |
Pełne wyjaśnienie pliku ai.py
1. Kluczowe funkcjonalności
Obsługa klienta Anthropic API
- Klasa
AnthropicCompletionjest odpowiedzialna za komunikację z API Anthropic. - Umożliwia wysyłanie zapytań do modelu AI w celu generowania odpowiedzi na podstawie podanego kontekstu.
- Klasa
Integracja ze zmiennymi środowiskowymi
- Klucz API Anthropic (
ANTHROPIC_API_KEY) jest ładowany z pliku.envlub ustawień środowiskowych, co zapewnia bezpieczne przechowywanie danych uwierzytelniających.
- Klucz API Anthropic (
2. Klasa AnthropicCompletion
Inicjalizacja
- Podczas inicjalizacji klasa pobiera klucz API z argumentów lub zmiennych środowiskowych. Jeśli klucz nie zostanie znaleziony, zgłaszany jest błąd (
ValueError).
- Podczas inicjalizacji klasa pobiera klucz API z argumentów lub zmiennych środowiskowych. Jeśli klucz nie zostanie znaleziony, zgłaszany jest błąd (
Metoda
completion- Jest to główna metoda klasy, która obsługuje wysyłanie zapytań do API.
- Przyjmuje następujące parametry:
messages: Lista wiadomości reprezentujących kontekst rozmowy.model: Nazwa modelu AI (domyślnieclaude-3-5-sonnet-20241022).retries: Liczba prób w przypadku niepowodzenia zapytania.delay: Czas oczekiwania między kolejnymi próbami.
- Buduje odpowiednie nagłówki (
headers) i treść żądania (payload).
3. Proces obsługi zapytań
Przygotowanie żądania
- Tworzone są nagłówki HTTP zawierające klucz API oraz treść żądania w formacie JSON.
payloadzawiera:- Model, który ma zostać użyty.
- Wiadomości dostarczające kontekstu rozmowy.
- Parametry takie jak maksymalna liczba tokenów (
max_tokens) i temperatura (temperature).
Próby wysyłki żądania
- W przypadku niepowodzenia zapytania (np. przeciążenie API), metoda ponawia żądanie określoną liczbę razy (
retries) z opóźnieniem (delay).
- W przypadku niepowodzenia zapytania (np. przeciążenie API), metoda ponawia żądanie określoną liczbę razy (
Obsługa wyjątków
RequestError: W przypadku błędu sieciowego, wyświetlany jest komunikat i wykonywana jest ponowna próba, jeśli to możliwe.HTTPStatusError: W przypadku błędu HTTP (np. brak autoryzacji), metoda zgłasza błąd i przerywa działanie.
Zwracanie odpowiedzi
- Jeśli zapytanie zakończy się sukcesem, metoda zwraca odpowiedź w formacie JSON.
4. Debugowanie
- Logowanie szczegółów
[DEBUG] Response Status Code: Wyświetla kod statusu HTTP dla każdego zapytania.[WARNING] API overloaded: Ostrzega o przeciążeniu API i podejmuje próbę ponowienia zapytania.[ERROR] Request failed: Informuje o błędzie w połączeniu.[ERROR] HTTP Error: Informuje o błędach związanych z odpowiedzią serwera API.
5. Potencjalne rozszerzenia
Obsługa innych modeli
- Obecnie model
claude-3-5-sonnet-20241022jest domyślnie ustawiony, ale można dodać możliwość wyboru innych modeli przez użytkownika.
- Obecnie model
Usprawnienie logowania
- Zamiast używać
print, można wdrożyć modułlogging, co pozwoli lepiej zarządzać poziomami logowania (np.INFO,DEBUG,ERROR).
- Zamiast używać
Mechanizmy buforowania
- Można zaimplementować buforowanie odpowiedzi API, aby zmniejszyć liczbę zapytań przy wielokrotnych żądaniach z tym samym kontekstem.
Plik ai.py jest kluczowym elementem projektu, umożliwiającym komunikację z modelem AI. Jest to odpowiednik modułu obsługującego API w TypeScript, ale dostosowany do środowiska Pythona.
2.Plik prompts.py
| |
Pełne wyjaśnienie pliku prompts.py
1. Kluczowe funkcjonalności
Generowanie promptów dla systemu agenta AI
- Plik
prompts.pyodpowiada za tworzenie promptów w różnych fazach działania agenta, takich jak planowanie, podejmowanie decyzji, opis, refleksja czy generowanie ostatecznej odpowiedzi. - Każda faza ma predefiniowane zasady i struktury promptów.
- Plik
Dynamiczne dostosowywanie treści promptów
- Prompt uwzględnia stan systemu (
state), co pozwala na generowanie odpowiedzi dopasowanych do bieżącego kontekstu i historii interakcji.
- Prompt uwzględnia stan systemu (
2. Funkcje w pliku prompts.py
tools_instruction()
- Zwraca słownik opisujący instrukcje dla dostępnych narzędzi, takich jak:
get_html_contents: Pobieranie zawartości HTML z podanego URL.game_submit_form: Wysyłanie plików lub danych do gry.upload_text_file: Tworzenie i przesyłanie plików tekstowych.final_answer: Generowanie finalnej odpowiedzi na pytanie użytkownika.play_music: Obsługa działań związanych z API Spotify.
available_tools()
- Zwraca listę dostępnych narzędzi w uproszczonym formacie, używaną w promptach takich jak
decide_prompt.
plan_prompt(state)
- Tworzy prompt dla etapu planowania.
- Uwzględnia obecny stan (
state) systemu, w tym:- Wysłane wiadomości użytkownika.
- Wcześniejsze działania (
actionsTaken). - Aktualny plan (
plan), jeśli istnieje.
- Prompt opisuje cel planowania oraz reguły działania agenta:
- Rozpoznawanie prostych pytań i natychmiastowe udzielanie odpowiedzi.
- Tworzenie planu, jeśli pytanie wymaga bardziej złożonej analizy.
decide_prompt(state)
- Generuje prompt dla etapu podejmowania decyzji.
- Uwzględnia obecny plan, listę wykonanych działań oraz dostępne narzędzia.
- Określa:
- Kolejny krok w przetwarzaniu.
- Wybór odpowiedniego narzędzia w formacie JSON.
describe_prompt(state)
- Tworzy prompt dla etapu opisu (
describe). - Wymaga, aby w stanie (
state) zdefiniowane były:- Nazwa aktywnego narzędzia (
activeTool.name). - Instrukcja dla narzędzia (
activeTool.instruction).
- Nazwa aktywnego narzędzia (
- Prompt definiuje reguły generowania odpowiednich danych do wykonania narzędzia.
reflection_prompt(state)
- Tworzy prompt dla etapu refleksji.
- Pozwala agentowi analizować wykonane działania i sugerować ulepszenia.
- Uwzględnia plan i wszystkie wcześniejsze działania, aby ułatwić dokładną analizę.
final_answer_prompt(state)
- Generuje prompt dla ostatecznej odpowiedzi na zapytanie użytkownika.
- Uwzględnia:
- Początkowy plan (
plan), jeśli istnieje. - Wszystkie podjęte działania (
actionsTaken). - Zapytanie użytkownika jako punkt wyjścia.
- Początkowy plan (
- Reguły w promptach nakierowują agenta na dostarczanie jasnych, dokładnych i przyjaznych odpowiedzi.
3. Główne zalety pliku prompts.py
- Modularność:
- Każda faza przetwarzania agenta ma dedykowaną funkcję, co ułatwia rozbudowę i utrzymanie kodu.
- Dynamiczność:
- Prompt generowany jest na podstawie bieżącego stanu systemu, co pozwala na większą elastyczność i precyzję w odpowiedziach.
- Obsługa złożonych zapytań:
- System potrafi dostosować się do prostych pytań użytkownika, jak i bardziej złożonych scenariuszy wymagających wielu kroków.
4. Potencjalne rozszerzenia
- Dodanie nowych narzędzi:
- Łatwo można wprowadzić nowe narzędzia, dodając je do funkcji
tools_instruction()iavailable_tools().
- Łatwo można wprowadzić nowe narzędzia, dodając je do funkcji
- Zaawansowana obsługa języka naturalnego:
- Można wzbogacić prompty o dodatkowe reguły obsługujące bardziej złożone struktury językowe.
- Lepsze logowanie błędów:
- Wprowadzenie systemu walidacji danych w stanie (
state), aby unikać błędów wynikających z brakujących kluczy.
- Wprowadzenie systemu walidacji danych w stanie (
Plik prompts.py stanowi kluczowy element systemu agenta, określając strukturę i zasady działania każdej fazy interakcji. Jest to odpowiednik pliku prompts.ts, ale w pełni zaadaptowany do środowiska Pythona.
3.Plik agent.py – Logika agenta do podejmowania decyzji, refleksji i wykonania działań
| |
Pełne wyjaśnienie pliku agent.py
1. Kluczowe funkcjonalności
Zarządzanie etapami agenta AI
- Plik
agent.pyimplementuje klasęAIAgent, która obsługuje przepływ procesu agenta AI przez kolejne etapy- Planowanie (
plan) - Podejmowanie decyzji (
decide) - Generowanie opisu (
describe) - Wykonanie akcji (
execute) - Refleksja nad wynikiem (
reflect) - Generowanie ostatecznej odpowiedzi (
final_answer)
- Planowanie (
- Plik
Logowanie postępów w pliku Markdown
- Każda istotna akcja jest zapisywana w pliku
log.md, aby umożliwić łatwe śledzenie działań agenta.
- Każda istotna akcja jest zapisywana w pliku
2. Kluczowe elementy pliku
Klasa AIAgent
- Główna klasa odpowiedzialna za sterowanie wszystkimi etapami pracy agenta.
__init__()
- Inicjalizacja stanu agenta
currentStageAktualny etap przetwarzania (np.plan,decide).currentStepBieżący krok w ramach całego procesu.maxStepsMaksymalna liczba kroków, aby uniknąć zapętlenia.messagesWiadomości użytkownika, które są podstawą pracy agenta.actionsTakenHistoria działań podjętych przez agenta.api_keyKlucz API Anthropic, używany do komunikacji z modelem AI.
log_to_markdown()
- Funkcja zapisująca wyniki poszczególnych etapów do pliku
log.md. - Przyjmuje
headerNagłówek sekcji.contentTreść, która ma być zapisana.
Asynchroniczne metody etapowe
- Każdy etap procesu jest obsługiwany przez dedykowaną metodę.
plan()
- Generuje plan działania na podstawie promptu.
- Wysyła zapytanie do modelu AI z wygenerowanym promptem
plan_prompt.
decide()
- Decyduje o następnym kroku lub narzędziu do użycia.
- Używa promptu
decide_prompt, aby określić najlepszy sposób kontynuacji. - Wynik jest przetwarzany jako JSON, co pozwala na precyzyjne wybranie narzędzia lub akcji.
describe()
- Generuje dane wejściowe (
payload) wymagane do wykonania narzędzia. - Używa promptu
describe_promptoraz wymaga, aby narzędzie (activeTool) było zdefiniowane w stanie agenta.
execute()
- Wykonuje wybrane narzędzie lub akcję.
- Przechowuje wynik działania w stanie (
state['actionsTaken']).
reflect()
- Analizuje ostatnie działanie agenta.
- Używa promptu
reflection_prompt, aby zasugerować ulepszenia lub dostosowania planu.
final_answer()
- Generuje ostateczną odpowiedź na pytanie użytkownika.
- Używa promptu
final_answer_prompti zwraca odpowiedź jako wynik działania agenta.
3. Pętla przetwarzania w klasie AIAgent
- Opis
- Pętla iteruje przez maksymalnie
maxStepskroków. - Kolejne etapy (
plan,decide,describe,execute,reflect) są wykonywane w ustalonej kolejności. - Pętla kończy się, gdy osiągnięty zostanie etap
final_answerlub limit kroków.
- Pętla iteruje przez maksymalnie
- Zachowanie w przypadku błędów
- Jeśli wystąpi błąd na którymkolwiek etapie, proces jest zatrzymywany i błąd jest logowany.
4. Kluczowe zalety
Asynchroniczność
- Wszystkie metody są asynchroniczne, co pozwala na efektywne przetwarzanie równoległe.
Elastyczność i modularność
- Każdy etap jest oddzielnie zdefiniowany, co ułatwia rozszerzanie i modyfikowanie funkcjonalności.
Obsługa złożonych scenariuszy
- Agent potrafi przetwarzać zarówno proste pytania użytkownika, jak i bardziej złożone zadania wymagające wieloetapowego planowania i refleksji.
5. Potencjalne ulepszenia
Obsługa wyjątków
- Można dodać bardziej precyzyjne komunikaty błędów dla każdego etapu.
Zaawansowane logowanie
- Logowanie do oddzielnych plików lub systemów monitorowania (np. ElasticSearch, Sentry) może zwiększyć możliwości analizy.
Wzbogacenie historii działań
- Zapisywanie bardziej szczegółowych danych w
actionsTakenmoże ułatwić debugowanie i analizę wyników.
- Zapisywanie bardziej szczegółowych danych w
Plik agent.py jest centralnym elementem systemu, zarządzającym przepływem procesu agenta AI oraz integracją z modelem Anthropic poprzez asynchroniczne zapytania.
4.Plik tools.py – Funkcje obsługujące pobieranie treści HTML, przesyłanie plików, odtwarzanie muzyki, itp.
| |
Wyjaśnienie pliku tools.py
1. Główne funkcje
Plik tools.py dostarcza implementację różnych narzędzi używanych w systemie agenta AI. Każde narzędzie jest reprezentowane przez funkcję, która wykonuje specyficzne zadanie. Funkcje te umożliwiają wykonywanie operacji takich jak pobieranie treści HTML, przesyłanie plików czy integracja z usługami muzycznymi.
Wyjaśnienie każdej funkcji
browse(url)- Opis: Pobiera zawartość HTML z podanego adresu URL.
- Działanie:
- Wysyła zapytanie HTTP GET do podanego adresu URL.
- Otrzymaną zawartość HTML konwertuje na markdown przy użyciu biblioteki
markdownify. - Zwraca sformatowany wynik lub odpowiedni komunikat o błędzie, jeśli operacja się nie powiedzie.
- Obsługa błędów:
- Obsługuje wyjątki
RequestException, zwracając szczegółowy komunikat w przypadku błędu połączenia.
- Obsługuje wyjątki
upload_file(data)- Opis: Przesyła plik tekstowy na zdalny serwer.
- Działanie:
- Oczekuje słownika
datazawierającego klucze:content: Treść pliku.file_name: Nazwa pliku.
- Używa zmiennej środowiskowej
UPLOAD_DOMAINjako punktu końcowego serwera. - Wysyła żądanie POST z zawartością pliku jako payload.
- Zwraca URL przesłanego pliku w przypadku powodzenia lub odpowiedni komunikat o błędzie w przypadku niepowodzenia.
- Oczekuje słownika
- Obsługa błędów:
- Sprawdza, czy zmienna
UPLOAD_DOMAINjest ustawiona. Jeśli nie, zwraca odpowiedni komunikat o błędzie. - Obsługuje wyjątki związane z połączeniem lub odpowiedzią serwera.
- Sprawdza, czy zmienna
play_music(data)- Opis: Wysyła żądanie odtworzenia muzyki do usługi muzycznej.
- Działanie:
- Oczekuje słownika
datazawierającego szczegóły dotyczące żądania, np. utwory do odtworzenia. - Używa zmiennej środowiskowej
MUSIC_URLjako punktu końcowego usługi muzycznej. - Wysyła żądanie POST z danymi o muzyce.
- Zwraca odpowiedź serwera, która może zawierać szczegóły o odtwarzanej muzyce.
- Oczekuje słownika
- Obsługa błędów:
- Sprawdza, czy zmienna
MUSIC_URLjest ustawiona. Jeśli nie, zwraca odpowiedni komunikat o błędzie. - Obsługuje błędy związane z połączeniem i odpowiedzią serwera.
- Sprawdza, czy zmienna
2. Słownik tools
- Opis:
- Mapa funkcji narzędziowych, przypisująca nazwy narzędzi (np.
"browse","upload_file","play_music") do odpowiadających im funkcji w Pythonie. - Ułatwia dostęp do funkcji na podstawie ich nazwy, co jest przydatne podczas dynamicznego wykonywania narzędzi w ramach agenta AI.
- Mapa funkcji narzędziowych, przypisująca nazwy narzędzi (np.
3. Główne cechy
- Obsługa zmiennych środowiskowych:
- Funkcje
upload_fileiplay_musicopierają się na zmiennych środowiskowych (UPLOAD_DOMAIN,MUSIC_URL), aby określić punkty końcowe serwerów.
- Funkcje
- Obsługa błędów:
- Każda funkcja zawiera szczegółową obsługę błędów, zapewniając, że użytkownik otrzyma czytelny komunikat w przypadku problemów.
- Elastyczność:
- Słownik
toolsumożliwia łatwe dodawanie nowych narzędzi lub modyfikowanie istniejących.
- Słownik
4. Kluczowe zalety
Integracja z zewnętrznymi usługami:
- Obsługuje operacje wymagające interakcji z zewnętrznymi serwisami, jak przesyłanie plików czy odtwarzanie muzyki.
Konwersja danych:
- Funkcja
browsepozwala na automatyczną konwersję zawartości HTML na markdown, co może być przydatne do przetwarzania treści.
- Funkcja
5. Możliwości rozwoju
Rozszerzenie funkcjonalności:
- Dodanie nowych funkcji narzędziowych (np. edycji plików, obsługi innych formatów danych).
Lepsze logowanie:
- Wprowadzenie systemu logowania (np. do pliku lub zewnętrznego systemu monitorowania) zamiast prostych komunikatów błędów.
Testy jednostkowe:
- Dodanie testów jednostkowych dla każdej funkcji w celu zapewnienia większej niezawodności.
Plik tools.py dostarcza funkcje niezbędne do obsługi narzędzi w systemie agenta AI, umożliwiając integrację z różnymi zewnętrznymi usługami i ułatwiając przetwarzanie danych.
Część 4: Automatyzacja z użyciem Ansible
1. Utwórz playbook Ansible – site.yml
Podzielmy playbook na logiczne części i utwórzmy projekt Ansible, w którym każda funkcjonalność (np. tworzenie środowiska, kopiowanie plików, konfiguracja aplikacji) będzie osobnym playbookiem lub rolą. Dzięki temu będziemy mieli elastyczny projekt, który można łatwo instalować, modyfikować i rozwijać.
Plan
Struktura projektu Ansible:
- Stworzymy główny katalog projektu Ansible z podkatalogami, takimi jak
roles(gdzie umieścimy poszczególne role Ansible) iplaybooks. - Podzielimy zadania na role:
- Role dla środowiska: Tworzenie środowiska wirtualnego, instalacja paczek.
- Role dla plików aplikacji: Tworzenie każdego pliku aplikacji z pełnym kodem.
- Role dla konfiguracji serwera: Konfiguracja i uruchomienie serwera aplikacji.
- Stworzymy główny katalog projektu Ansible z podkatalogami, takimi jak
Główna struktura projektu Ansible:
site.yml- główny plik playbooka, który uruchamia wszystkie role.roles/environment- rola, która tworzy środowisko wirtualne i instaluje wymagane paczki.roles/application_files- rola, która tworzy pliki aplikacji z pełnym kodem.roles/server_configuration- rola, która konfiguruje i uruchamia serwer aplikacji.
Krok 1: Tworzenie struktury katalogów
W katalogu projektu Ansible wykonaj poniższe kroki:
| |
W katalogu roles utwórz podkatalogi dla każdej roli:
| |
Krok 2: Utworzenie plików Ansible dla poszczególnych ról
1. Rola environment: Tworzenie środowiska wirtualnego i instalacja paczek
W pliku roles/environment/tasks/main.yml:
| |
2. Rola application_files: Tworzenie plików aplikacji
W pliku roles/application_files/tasks/main.yml, dodajemy pełny kod każdego pliku aplikacji.
| |
3. Rola server_configuration: Konfiguracja serwera
W pliku roles/server_configuration/tasks/main.yml:
| |
Krok 3: Główny plik playbooka site.yml
W głównym katalogu ansible_project, utwórz plik site.yml, który uruchamia wszystkie role:
| |
Krok 4: Przygotowanie archiwum projektu ZIP
Po utworzeniu całej struktury i dodaniu pełnych kodów plików w odpowiednich miejscach, możesz utworzyć archiwum ZIP:
| |
Podsumowanie
- Struktura projektu została podzielona na logiczne role.
- Każda rola wykonuje specyficzne zadania, co ułatwia zarządzanie i rozwój.
- Główny plik
site.ymlkoordynuje wszystkie role, tworząc w pełni funkcjonalne środowisko aplikacji. - Po zakończeniu tworzenia struktury możesz spakować cały projekt do pliku ZIP, gotowego do pobrania i wdrożenia.
1. Uruchamianie Playbooka
Aby uruchomić playbook i zautomatyzować proces konfiguracji projektu, wykonaj:
| |
2. Debugowanie i testowanie środowiska wirtualnego
Jeśli chcesz sprawdzić, czy Ansible poprawnie tworzy i używa środowiska wirtualnego:
Uruchom ręcznie poniższe komendy w katalogu projektu, aby sprawdzić, czy proces działa:
1 2 3python3 -m venv venv source venv/bin/activate # Aktywacja środowiska wirtualnego pip install -r requirements.txt # Instalacja zależnościW razie problemów, sprawdź logi Ansible po pełnym uruchomieniu playbooka.
Debugowanie aplikacji opartej na Uvicorn i Quart
Uruchamianie serwera ręcznie
Aplikacja korzysta z serwera Uvicorn, który uruchamia framework Quart. Aby przetestować jej działanie:
Aktywuj środowisko wirtualne:
1source venv/bin/activateUruchom aplikację:
1uvicorn index:app --host 0.0.0.0 --port 3000index:appwskazuje na modułindex.pyoraz instancję Quartappw tym pliku.- Port
3000jest standardowym ustawieniem. Upewnij się, że jest wolny.
Sprawdź, czy serwer działa:
Sprawdź otwarte porty:
1ss -tuln | grep 3000Wyślij testowe zapytanie HTTP:
1curl -X POST http://localhost:3000 -H "Content-Type: application/json" -d '{"messages": [{"role": "user", "content": "Hello, World!"}]}'
Logi i debugowanie
Logi Uvicorn:
Logi serwera Uvicorn zawierają informacje o błędach i ruchu HTTP.
Uruchom aplikację z podniesionym poziomem logowania:
1uvicorn index:app --host 0.0.0.0 --port 3000 --log-level debug
Logi aplikacji:
W aplikacji Quart są wbudowane debugujące
print-y dla większości operacji. Upewnij się, że masz włączony tryb debugowania Quart:1 2export QUART_ENV=development export QUART_DEBUG=1
Plik log.md:
Sprawdź, czy
log.mdzapisuje poprawne dane dla poszczególnych etapów działania agenta:1tail -f log.md
Sprawdzanie zmiennych środowiskowych
Upewnij się, że plik .env zawiera prawidłowe wartości:
| |
Zweryfikuj, czy zmienne zostały załadowane:
| |
Weryfikacja po instalacji
Zweryfikuj proces:
Sprawdź, czy proces Uvicorn działa:
1ps aux | grep uvicorn
Przetestuj endpoint:
Wyślij zapytanie do serwera:
1curl -X POST http://localhost:3000 -H "Content-Type: application/json" -d '{"messages": [{"role": "user", "content": "How far is the Moon?"}]}'
Przywracanie aplikacji:
W przypadku problemów zatrzymaj i ponownie uruchom proces:
1 2pkill -f uvicorn uvicorn index:app --host 0.0.0.0 --port 3000
Ten zestaw kroków powinien ułatwić debugowanie i testowanie aplikacji opartej na Uvicorn i Quart.
Comments