Sync ar, ko, and pt-BR docs for Anthropic usage metrics updates.

Translate UsageMetrics semantics and Anthropic cache token accounting changes in crews, flows, and llms concept pages.
2026-08-10 08:21:54 +00:00 · 2026-08-07 00:24:59 +05:30
parent e192c96cd2
commit e36aeef7cf
9 changed files with 107 additions and 0 deletions
--- a/docs/edge/ar/concepts/crews.mdx
+++ b/docs/edge/ar/concepts/crews.mdx
@@ -172,6 +172,8 @@ class YourCrewName:

 بعد تنفيذ الطاقم، يمكنك الوصول إلى خاصية `usage_metrics` لعرض مقاييس استخدام نموذج اللغة (LLM) لجميع المهام المنفذة.

+`total_tokens` هو الإجمالي المفوتر (`prompt_tokens + completion_tokens`). حقول التفصيل مثل `cached_prompt_tokens` و`cache_creation_tokens` تصف أجزاءً مُدرجة بالفعل ضمن تلك الإجماليات ولا تُضاف مرة أخرى إلى `total_tokens`. راجع قسم **UsageMetrics field semantics** في توثيق مفهوم Flows للحصول على العقد الكامل.
+
 ```python Code
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
 crew.kickoff()
--- a/docs/edge/ar/concepts/flows.mdx
+++ b/docs/edge/ar/concepts/flows.mdx
@@ -266,6 +266,24 @@ print(flow.usage_metrics)
  كلما احتجت إلى الإجمالي **الكامل** للتوكنات لتنفيذ التدفق.
 </Note>

+### دلالات حقول UsageMetrics
+
+يستخدم كائن [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد عقدًا محايدًا للمزود:
+
+| الحقل | المعنى |
+| --- | --- |
+| `total_tokens` | الإجمالي المفوتر: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | إجمالي رموز الإدخال/المطالبة المفوترة للطلب |
+| `completion_tokens` | رموز الإخراج/الإكمال المفوترة للطلب |
+| `cached_prompt_tokens` | جزء قراءة الذاكرة المؤقتة من رموز المطالبة (تفصيل فقط) |
+| `cache_creation_tokens` | جزء كتابة الذاكرة المؤقتة من رموز المطالبة (تفصيل فقط، Anthropic) |
+| `reasoning_tokens` | جزء التفكير/الاستدلال حيث يبلّغ المزود عنه بشكل منفصل (تفصيل فقط) |
+| `successful_requests` | عدد استدعاءات LLM المُجمّعة |
+
+حقول التفصيل مثل `cached_prompt_tokens` و`cache_creation_tokens` و`reasoning_tokens` **لا تُضاف** فوق `total_tokens` — بل تصف أجزاءً مُدرجة بالفعل ضمن `prompt_tokens` أو `completion_tokens`.
+
+بالنسبة إلى Anthropic، تُدمج عدادات قراءة وكتابة الذاكرة المؤقتة ضمن `prompt_tokens`، لذا تنعكس أعباء العمل المخزنة مؤقتًا بالكامل في `total_tokens`. يُدرج مزودو OpenAI الرموز المخزنة مؤقتًا بالفعل داخل `prompt_tokens`؛ يعرض CrewAI الجزء المخزن مؤقتًا بشكل منفصل للوضوح.
+
 كل حقل في [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد هو مجموع جميع استدعاءات نموذج اللغة التي حدثت خلال استدعاء واحد لـ `flow.kickoff()`. تتم إعادة تعيين العدادات عند الاستدعاء التالي لـ `kickoff()` (وفي كل تكرار من `kickoff_for_each`)، لذلك لن تتكرر العدّات عبر التشغيلات المتتالية. يمكن قراءة هذه الخاصية بأمان في أي وقت بعد اكتمال `kickoff()`؛ قراءتها أثناء التنفيذ تُرجع المجموع الجزئي المتراكم حتى تلك اللحظة.

 ## إدارة حالة التدفق
--- a/docs/edge/ar/concepts/llms.mdx
+++ b/docs/edge/ar/concepts/llms.mdx
@@ -392,6 +392,22 @@ mode: "wide"
    - تتبع استخدام الرموز
    - محادثات استخدام أدوات متعددة الأدوار

+    **استخدام الرموز والتخزين المؤقت للمطالبة:**
+
+    يُبلّغ Anthropic عن الإدخال المفوتر في عدادات منفصلة — `input_tokens` (غير المخزن مؤقتًا)، و`cache_read_input_tokens`، و`cache_creation_input_tokens`. يدمج CrewAI الثلاثة ضمن `prompt_tokens` (و`input_tokens` الأصلي في استجابات المزود) بحيث يعكس `total_tokens` الاستخدام المفوتر الكامل على أعباء العمل المخزنة مؤقتًا.
+
+    يسجّل `cached_prompt_tokens` جزء قراءة الذاكرة المؤقتة كتفصيل فقط؛ وهو مُدرج بالفعل ضمن `prompt_tokens` ولا يجب إضافته مرة أخرى إلى `total_tokens`. يسجّل `cache_creation_tokens` عمليات الكتابة في الذاكرة المؤقتة بنفس الطريقة.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    راجع قسم **UsageMetrics field semantics** في توثيق مفهوم Flows
+    للحصول على العقد المحايد للمزود المستخدم في `crew.usage_metrics`
+    و`flow.usage_metrics`.
+
    **ملاحظات مهمة:**
    - `max_tokens` معامل **مطلوب** لجميع نماذج Anthropic
    - يستخدم Claude `stop_sequences` بدلاً من `stop`
--- a/docs/edge/ko/concepts/crews.mdx
+++ b/docs/edge/ko/concepts/crews.mdx
@@ -324,6 +324,8 @@ crew는 메모리(단기, 장기 및 엔티티 메모리)를 활용하여 시간

 crew 실행 후, `usage_metrics` 속성에 접근하여 crew가 실행한 모든 작업에 대한 언어 모델(LLM) 사용 메트릭을 확인할 수 있습니다. 이를 통해 운영 효율성과 개선이 필요한 영역에 대한 인사이트를 얻을 수 있습니다.

+`total_tokens`는 청구된 총합(`prompt_tokens + completion_tokens`)입니다. `cached_prompt_tokens` 및 `cache_creation_tokens`와 같은 breakdown 필드는 이미 해당 총합에 포함된 부분 집합을 설명하며 `total_tokens` 위에 다시 더하지 않습니다. 전체 계약은 Flows 개념 문서의 **UsageMetrics field semantics** 섹션을 참조하세요.
+
 ```python Code
 # Access the crew's usage metrics
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
--- a/docs/edge/ko/concepts/flows.mdx
+++ b/docs/edge/ko/concepts/flows.mdx
@@ -261,6 +261,24 @@ print(flow.usage_metrics)
  **전체** 토큰 집계가 필요할 때는 항상 `flow.usage_metrics`를 사용하십시오.
 </Note>

+### UsageMetrics 필드 의미
+
+반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) 객체는 제공자 중립 계약을 사용합니다:
+
+| 필드 | 의미 |
+| --- | --- |
+| `total_tokens` | 청구된 총합: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | 요청에 대해 청구된 전체 입력/프롬프트 토큰 |
+| `completion_tokens` | 요청에 대해 청구된 출력/완료 토큰 |
+| `cached_prompt_tokens` | 프롬프트 토큰 중 캐시 읽기 부분 집합 (breakdown 전용) |
+| `cache_creation_tokens` | 프롬프트 토큰 중 캐시 쓰기 부분 집합 (breakdown 전용, Anthropic) |
+| `reasoning_tokens` | 제공자가 별도로 보고하는 추론/사고 부분 집합 (breakdown 전용) |
+| `successful_requests` | 집계된 LLM 호출 수 |
+
+`cached_prompt_tokens`, `cache_creation_tokens`, `reasoning_tokens`와 같은 breakdown 필드는 `total_tokens` **위에 추가되지 않습니다** — 이미 `prompt_tokens` 또는 `completion_tokens`에 포함된 부분을 설명합니다.
+
+Anthropic의 경우 캐시 읽기 및 쓰기 카운터가 `prompt_tokens`에 포함되므로, 캐시된 워크로드가 `total_tokens`에 완전히 반영됩니다. OpenAI 스타일 제공자는 캐시된 입력을 이미 `prompt_tokens`에 포함합니다. CrewAI는 가시성을 위해 캐시된 부분을 별도로 표시합니다.
+
 반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py)의 각 항목은 단일 `flow.kickoff()` 실행 동안 발생한 모든 LLM 호출의 합계입니다. 다음 `kickoff()` 호출(및 `kickoff_for_each`의 각 반복)에서 카운터가 초기화되므로 연속 실행이 이중으로 집계되지 않습니다. 이 속성은 `kickoff()` 완료 후 언제든지 안전하게 읽을 수 있으며, 실행 중에 읽으면 그 시점까지 누적된 부분 합계를 반환합니다.

 ## 플로우 상태 관리
--- a/docs/edge/ko/concepts/llms.mdx
+++ b/docs/edge/ko/concepts/llms.mdx
@@ -270,6 +270,21 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
    )
    ```

+    **토큰 사용량 및 프롬프트 캐싱:**
+
+    Anthropic은 청구된 입력을 별도 카운터로 보고합니다 — `input_tokens`(캐시되지 않은 입력), `cache_read_input_tokens`, `cache_creation_input_tokens`. CrewAI는 세 값을 모두 `prompt_tokens`(및 제공자 응답의 네이티브 `input_tokens`)에 포함시켜 캐시된 워크로드에서 `total_tokens`가 전체 청구 사용량을 반영하도록 합니다.
+
+    `cached_prompt_tokens`는 캐시 읽기 부분을 breakdown으로만 기록합니다. 이미 `prompt_tokens`에 포함되어 있으므로 `total_tokens`에 다시 더하면 안 됩니다. `cache_creation_tokens`도 캐시 쓰기를 같은 방식으로 기록합니다.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    `crew.usage_metrics` 및 `flow.usage_metrics`에 사용되는 제공자 중립 계약은
+    Flows 개념 문서의 **UsageMetrics field semantics** 섹션을 참조하세요.
+
    현재 모델 ID와 기능은 Anthropic의 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 확인하고, 프로덕션에서 모델을 고정하기 전에 [모델 지원 중단 표](https://platform.claude.com/docs/en/about-claude/model-deprecations)를 검토하세요.
  </Accordion>

--- a/docs/edge/pt-BR/concepts/crews.mdx
+++ b/docs/edge/pt-BR/concepts/crews.mdx
@@ -322,6 +322,8 @@ Caches podem ser utilizados para armazenar resultados de execuções de ferramen

 Após a execução da crew, você pode acessar o atributo `usage_metrics` para visualizar as métricas de uso do modelo de linguagem (LLM) para todas as tasks executadas pela crew. Isso fornece insights sobre eficiência operacional e oportunidades de melhoria.

+`total_tokens` é o total faturado (`prompt_tokens + completion_tokens`). Campos de breakdown como `cached_prompt_tokens` e `cache_creation_tokens` descrevem subconjuntos já incluídos nesses totais e não são somados novamente a `total_tokens`. Consulte a seção **UsageMetrics field semantics** na documentação do conceito Flows para o contrato completo.
+
 ```python Code
 # Acessar as métricas de uso da crew
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
--- a/docs/edge/pt-BR/concepts/flows.mdx
+++ b/docs/edge/pt-BR/concepts/flows.mdx
@@ -260,6 +260,24 @@ print(flow.usage_metrics)
  rollup **completo** de tokens da execução do Flow.
 </Note>

+### Semântica dos campos UsageMetrics
+
+O objeto [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado usa um contrato neutro em relação ao provedor:
+
+| Campo | Significado |
+| --- | --- |
+| `total_tokens` | Total faturado: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | Total de tokens de entrada/prompt faturados para a requisição |
+| `completion_tokens` | Tokens de saída/conclusão faturados para a requisição |
+| `cached_prompt_tokens` | Subconjunto de leitura de cache dos tokens de prompt (apenas breakdown) |
+| `cache_creation_tokens` | Subconjunto de escrita de cache dos tokens de prompt (apenas breakdown, Anthropic) |
+| `reasoning_tokens` | Subconjunto de raciocínio/pensamento quando o provedor reporta separadamente (apenas breakdown) |
+| `successful_requests` | Número de chamadas LLM agregadas |
+
+Campos de breakdown como `cached_prompt_tokens`, `cache_creation_tokens` e `reasoning_tokens` **não** são somados sobre `total_tokens` — eles descrevem porções já incluídas em `prompt_tokens` ou `completion_tokens`.
+
+Para Anthropic, os contadores de leitura e escrita de cache são incorporados em `prompt_tokens`, de modo que workloads em cache são totalmente refletidos em `total_tokens`. Provedores no estilo OpenAI já incluem a entrada em cache dentro de `prompt_tokens`; o CrewAI expõe a porção em cache separadamente para visibilidade.
+
 Cada campo do [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado representa a soma de todas as chamadas de LLM feitas em uma única invocação de `flow.kickoff()`. Os contadores são resetados a cada novo `kickoff()` (e em cada iteração de `kickoff_for_each`), de modo que execuções sucessivas não duplicam o total. A propriedade é segura para ser lida em qualquer momento após o `kickoff()`; lê-la durante a execução retorna o total parcial acumulado até aquele instante.

 ## Gerenciamento de Estado em Flows
--- a/docs/edge/pt-BR/concepts/llms.mdx
+++ b/docs/edge/pt-BR/concepts/llms.mdx
@@ -270,6 +270,22 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
    )
    ```

+    **Uso de tokens e prompt caching:**
+
+    A Anthropic reporta a entrada faturada em contadores separados — `input_tokens` (não em cache), `cache_read_input_tokens` e `cache_creation_input_tokens`. O CrewAI incorpora os três em `prompt_tokens` (e no `input_tokens` nativo nas respostas do provedor) para que `total_tokens` reflita o uso faturado completo em workloads em cache.
+
+    `cached_prompt_tokens` registra a porção de leitura de cache apenas como breakdown; ela já está incluída em `prompt_tokens` e não deve ser somada novamente a `total_tokens`. `cache_creation_tokens` registra escritas de cache da mesma forma.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    Consulte a seção **UsageMetrics field semantics** na documentação do
+    conceito Flows para o contrato neutro em relação ao provedor usado por
+    `crew.usage_metrics` e `flow.usage_metrics`.
+
    Consulte a [visão geral dos modelos](https://platform.claude.com/docs/en/about-claude/models/overview) da Anthropic para obter IDs e capacidades atuais e revise a [tabela de descontinuação](https://platform.claude.com/docs/en/about-claude/model-deprecations) antes de fixar um modelo em produção.
  </Accordion>