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 2
mkdir aidevs cd aidevs
-
Utwórz strukturę katalogów i plikow w lib:
1 2 3
mkdir -p lib cd lib touch agent.py ai.py prompts.py tools.py
-
Utwórz pliki projektu w odpowiednich katalogach:
1
touch .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 2
python3 -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 12
openai asyncssh markdown2 python-dotenv ansible-lint flask anthropic playwright markdownify httpx quart uvicorn
-
Zainstaluj pakiety z
requirements.txt
:1
pip install -r requirements.txt
3. Konfiguracja pliku .env
-
Utwórz plik
.env
w głównym katalogu projektu z kluczami API:1 2 3 4
OPENAI_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
Quart
jest asynchroniczną wersjąFlask
i obsługuje zarówno synchroniczne, jak i asynchroniczne endpointy.- Aplikacja jest definiowana i przypisywana do zmiennej
app
.
-
Ładowanie zmiennych środowiskowych
dotenv
jest używany do ładowania kluczowych zmiennych środowiskowych, takich jak klucz API Anthropic.
-
Inicjalizacja klasy
AIAgent
- Klasa
AIAgent
zarzą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_answer
lub przekroczony zostanie limit kroków.
- Przetwarza wiadomość użytkownika w kolejnych etapach:
-
Metody etapowe
_plan
tworzy plan działania na podstawie wiadomości użytkownika._decide
wybiera kolejne narzędzie lub decyduje o zakończeniu działania._describe
generuje dane wejściowe do wybranego narzędzia._execute
wykonuje wybrane narzędzie i zapisuje wyniki._reflect
analizuje 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ę
AIAgent
i wywołuje metodęrun
z 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
AnthropicCompletion
obsł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
logging
zamiast 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
Literal
definiujący różne etapy działania agenta, w których może się znajdować (init
,plan
,decide
,describe
,reflect
,execute
orazfinal
). -
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:
TypedDict
reprezentują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:
TypedDict
definiują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
AnthropicCompletion
jest 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.env
lub 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.
payload
zawiera:- 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-20241022
jest 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.py
odpowiada 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.py
implementuje 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
currentStage
Aktualny etap przetwarzania (np.plan
,decide
).currentStep
Bieżący krok w ramach całego procesu.maxSteps
Maksymalna liczba kroków, aby uniknąć zapętlenia.messages
Wiadomości użytkownika, które są podstawą pracy agenta.actionsTaken
Historia działań podjętych przez agenta.api_key
Klucz 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
header
Nagłówek sekcji.content
Treść, 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_prompt
oraz 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_prompt
i zwraca odpowiedź jako wynik działania agenta.
3. Pętla przetwarzania w klasie AIAgent
- Opis
- Pętla iteruje przez maksymalnie
maxSteps
krokó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_answer
lub 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
actionsTaken
moż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
data
zawierającego klucze:content
: Treść pliku.file_name
: Nazwa pliku.
- Używa zmiennej środowiskowej
UPLOAD_DOMAIN
jako 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_DOMAIN
jest 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
data
zawierającego szczegóły dotyczące żądania, np. utwory do odtworzenia. - Używa zmiennej środowiskowej
MUSIC_URL
jako 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_URL
jest 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_file
iplay_music
opierają 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
tools
umoż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
browse
pozwala 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.yml
koordynuje 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 3
python3 -m venv venv source venv/bin/activate # Aktywacja środowiska wirtualnego pip install -r requirements.txt # Instalacja zależności
-
W 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:
1
source venv/bin/activate
-
Uruchom aplikację:
1
uvicorn index:app --host 0.0.0.0 --port 3000
index:app
wskazuje na modułindex.py
oraz instancję Quartapp
w tym pliku.- Port
3000
jest standardowym ustawieniem. Upewnij się, że jest wolny.
-
Sprawdź, czy serwer działa:
-
Sprawdź otwarte porty:
1
ss -tuln | grep 3000
-
Wyślij testowe zapytanie HTTP:
1
curl -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:
1
uvicorn 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 2
export QUART_ENV=development export QUART_DEBUG=1
-
-
Plik log.md:
-
Sprawdź, czy
log.md
zapisuje poprawne dane dla poszczególnych etapów działania agenta:1
tail -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:
1
ps aux | grep uvicorn
-
-
Przetestuj endpoint:
-
Wyślij zapytanie do serwera:
1
curl -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 2
pkill -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.