diff --git a/docs/source/ko/_toctree.yml b/docs/source/ko/_toctree.yml index 870089f44..0626539f0 100644 --- a/docs/source/ko/_toctree.yml +++ b/docs/source/ko/_toctree.yml @@ -10,8 +10,8 @@ sections: - local: tutorials/building_good_agents title: 좋은 에이전트 구축하기 -# - local: tutorials/inspect_runs -# title: 📊 Inspect your agent runs using telemetry + - local: tutorials/inspect_runs + title: 📊 텔레메트리로 에이전트 실행 검사하기 # - local: tutorials/tools # title: 🛠️ Tools - in-depth guide # - local: tutorials/secure_code_execution diff --git a/docs/source/ko/tutorials/inspect_runs.md b/docs/source/ko/tutorials/inspect_runs.md new file mode 100644 index 000000000..bee0bb59e --- /dev/null +++ b/docs/source/ko/tutorials/inspect_runs.md @@ -0,0 +1,179 @@ +# OpenTelemetry로 실행 검사하기[[inspecting-runs-with-opentelemetry]] + +[[open-in-colab]] + +> [!TIP] +> 에이전트 구축이 처음이라면 먼저 [에이전트 소개](../conceptual_guides/intro_agents)와 [안내서](../guided_tour)를 읽어보세요. + +## 에이전트 실행을 로깅하는 이유는?[[why-log-your-agent-runs?]] + +에이전트 실행을 디버깅하는 것은 복잡한 작업입니다. + +실행이 제대로 진행되었는지 확인하기 어렵습니다. 에이전트 워크플로우는 설계상 예측 불가능하기 때문입니다(만약 예측 가능했다면 일반적인 코드를 사용했을 것입니다). + +실행 과정을 살펴보는 것도 쉽지 않습니다. 다단계 에이전트는 콘솔을 로그로 빠르게 채우는 경향이 있으며, 대부분의 오류는 단순한 "LLM의 실수" 유형으로, LLM이 다음 단계에서 더 나은 코드나 도구 호출을 작성하여 스스로 교정합니다. + +따라서 나중에 검사하고 모니터링할 수 있도록 계측을 통해 에이전트 실행을 기록하는 것이 프로덕션 환경에서는 필수입니다! + +에이전트 실행을 계측하기 위해 [OpenTelemetry](https://opentelemetry.io/) 표준을 도입했습니다. + +즉, 계측 코드를 실행한 후 에이전트를 평소처럼 실행하면 모든 내용이 플랫폼에 자동으로 로깅됩니다. 다양한 OpenTelemetry 백엔드에서 이를 구현하는 방법의 예시를 아래에 제시합니다. + +플랫폼에서의 실제 모습은 다음과 같습니다. + +
+ +
+ +## Arize AI Phoenix로 텔레메트리 설정[[setting-up-telemetry-with-arize-ai-phoenix]] + +먼저 필요한 패키지를 설치합니다. 여기서는 로그를 수집하고 검사하기에 좋은 솔루션인 [Arize AI의 Phoenix](https://github.com/Arize-ai/phoenix)를 설치하지만, 이 과정에는 다른 OpenTelemetry 호환 플랫폼을 활용할 수도 있습니다. + +```shell +pip install 'smolagents[telemetry,toolkit]' +``` + +다음 단계로 수집기를 백그라운드에서 실행합니다. + +```shell +python -m phoenix.server.main serve +``` + +마지막으로 `SmolagentsInstrumentor`를 설정하여 에이전트를 추적하고 Phoenix 기본 엔드포인트로 해당 추적 데이터를 전송합니다. + +```python +from phoenix.otel import register +from openinference.instrumentation.smolagents import SmolagentsInstrumentor + +register() +SmolagentsInstrumentor().instrument() +``` +이제 에이전트를 실행할 수 있습니다! + +```py +from smolagents import ( + CodeAgent, + ToolCallingAgent, + WebSearchTool, + VisitWebpageTool, + InferenceClientModel, +) + +model = InferenceClientModel() + +search_agent = ToolCallingAgent( + tools=[WebSearchTool(), VisitWebpageTool()], + model=model, + name="search_agent", + description="This is an agent that can do web search.", +) + +manager_agent = CodeAgent( + tools=[], + model=model, + managed_agents=[search_agent], +) +manager_agent.run( + "If the US keeps its 2024 growth rate, how many years will it take for the GDP to double?" +) +``` +끝입니다! +이제 `http://0.0.0.0:6006/projects/`로 이동하여 실행 결과를 확인할 수 있습니다! + + + +CodeAgent가 관리하는 ToolCallingAgent를 호출하여(참고로 관리되는 에이전트는 CodeAgent가 될 수도 있습니다) 미국 2024년 성장률을 웹에서 검색하도록 요청한 것을 확인할 수 있습니다. 이후 관리되는 에이전트가 결과를 보고하면, 관리자 에이전트가 이 정보를 활용하여 경제 배증 시간을 계산했습니다! 흥미롭죠? + +## 🪢 Langfuse로 텔레메트리 설정[[setting-up-telemetry-with-🪢-langfuse]] + +이 부분은 `SmolagentsInstrumentor`를 사용하여 **Langfuse**로 Hugging Face **smolagents**를 모니터링하고 디버깅하는 방법을 보여줍니다. + +> **Langfuse란?** [Langfuse](https://langfuse.com)는 LLM 엔지니어링을 위한 오픈소스 플랫폼입니다. AI 에이전트를 위한 추적 및 모니터링 기능을 제공하여 개발자가 제품을 디버깅하고, 분석하고, 최적화할 수 있도록 도와줍니다. Langfuse는 네이티브 통합, OpenTelemetry, SDK를 통해 다양한 도구와 프레임워크와 통합됩니다. + +### 1단계: 의존성 설치[[step-1:-install-dependencies]] + +```python +%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents +``` + +### 2단계: 환경 변수 설정[[step-2:-set-up-environment-variables]] + +Langfuse API 키를 설정하고 Langfuse로 추적을 보내도록 OpenTelemetry 엔드포인트를 구성하세요. [Langfuse Cloud](https://cloud.langfuse.com)에 가입하거나 [Langfuse를 자체 호스팅](https://langfuse.com/self-hosting)하여 Langfuse API 키를 얻으세요. + +또한 [Hugging Face 토큰](https://huggingface.co/settings/tokens) (`HF_TOKEN`)을 환경 변수로 추가하세요. + +```python +import os +# 프로젝트 설정 페이지(https://cloud.langfuse.com)에서 프로젝트 키를 가져옵니다. +os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." +os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 유럽 지역 +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 미국 지역 + +# Hugging Face 토큰을 입력합니다. +os.environ["HF_TOKEN"] = "hf_..." +``` + +환경 변수가 설정되면 이제 Langfuse 클라이언트를 초기화할 수 있습니다. `get_client()`는 환경 변수에 제공된 자격 증명을 사용하여 Langfuse 클라이언트를 초기화합니다. + +```python +from langfuse import get_client + +langfuse = get_client() + +# 연결을 확인합니다. +if langfuse.auth_check(): + print("Langfuse client is authenticated and ready!") +else: + print("Authentication failed. Please check your credentials and host.") +``` + +### 3단계: `SmolagentsInstrumentor` 초기화[[step-3:-initialize-the-`smolagentsinstrumentor`]] + +애플리케이션 코드를 실행하기 전에 `SmolagentsInstrumentor`를 초기화하세요. + +```python +from openinference.instrumentation.smolagents import SmolagentsInstrumentor + +SmolagentsInstrumentor().instrument() +``` + +### 4단계: smolagent 실행[[step-4:-run-your-smolagent]] + +```python +from smolagents import ( + CodeAgent, + ToolCallingAgent, + WebSearchTool, + VisitWebpageTool, + InferenceClientModel, +) + +model = InferenceClientModel( + model_id="deepseek-ai/DeepSeek-R1-Distill-Qwen-32B" +) + +search_agent = ToolCallingAgent( + tools=[WebSearchTool(), VisitWebpageTool()], + model=model, + name="search_agent", + description="This is an agent that can do web search.", +) + +manager_agent = CodeAgent( + tools=[], + model=model, + managed_agents=[search_agent], +) +manager_agent.run( + "How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?" +) +``` + +### 5단계: Langfuse에서 추적 보기[[step-5:-view-traces-in-langfuse]] + +에이전트를 실행한 후, Langfuse의 smolagents 애플리케이션에서 생성된 추적 정보를 확인할 수 있습니다. AI 에이전트의 디버깅과 최적화에 도움이 되는 LLM 상호작용의 상세한 세부 과정을 살펴볼 수 있습니다. + +![smolagents example trace](https://langfuse.com/images/cookbook/integration-smolagents/smolagent_example_trace.png) + +_[Langfuse의 추적 예시](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_