EcoLogits

repository·main·Indexed 43 days ago

https://github.com/mlco2/ecologits

A tool for tracking and estimating the energy consumption and environmental impacts (GHG emissions, water consumption, and mineral depletion) of generative AI models used via APIs. Version 0.11.1 provides integration support for providers including OpenAI, Anthropic, Cohere, Google GenAI, Hugging Face, and Mistral AI. It utilizes the ML.ENERGY Leaderboard benchmark and supports impact estimation for AI-generated videos.

Tokens
27K
Snippets
86
Records
124
Agent score
55%

What's inside EcoLogits

  1. Available evaluation methodologies in EcoLogits

    main

    EcoLogits currently supports the following evaluation methodologies for estimating environmental impacts:

    • LLM Inference: For assessing the impact of Large Language Model requests.
    • Video Generation: For assessing the impact of video generation tasks.

    Other methodologies such as Embeddings, Image Generation, and Multi-Modal are planned for future implementation.

  2. Understand the scope of EcoLogits environmental assessments

    main

    Unlike tools that focus primarily on model training, EcoLogits focuses on the inference phase of Generative AI, which can significantly overshadow training impacts when models are deployed at scale.

    EcoLogits uses a multi-criteria approach based on Life Cycle Assessment (LCA) to evaluate:

    • Carbon emissions
    • Abiotic resource depletion
    • Primary energy consumption

    It accounts for both usage impacts (electricity consumed during inference) and embodied impacts (the environmental cost of producing and transporting the hardware used for inference).

  3. How request water consumption footprint is modeled

    main

    The Water Consumption Footprint (WCF) for the usage phase is calculated using the methodology from Li et al. (2025). It considers both the on-site water usage of the data center and the off-site water usage associated with the local electricity mix.

    $$\text{WCF}^{\text{u}}\text{request} = E\text{server} \times [\text{WUE}\text{on-site} + \text{PUE} \times \text{WUE}\text{off-site}]$$

    Where:

    • $\text{WUE}_\text{on-site}$: Water Usage Effectiveness of the data center (assessed per provider).
    • $\text{WUE}_\text{off-site}$: Water Usage Effectiveness of the local electricity mix (averaged by country).
    • $\text{PUE}$: Power Usage Effectiveness.

    If country-specific off-site WUE data is unavailable, EcoLogits uses a world default value and reports a warning.

  4. How GPU energy consumption is modeled for LLM inference

    main

    EcoLogits estimates GPU energy consumption per output token using a parametric model derived from the ML.ENERGY Leaderboard (specifically targeting NVIDIA H100 80GB HBM3 GPUs).

    The model distinguishes between total parameters (used to calculate how many GPUs are needed to load the model) and active parameters ($P_{\text{active}}$) (used to estimate energy consumption per GPU).

    For Sparse Mixture-of-Experts (SMoE) models, $P_{\text{active}}$ is the number of active experts, whereas for dense models, $P_{\text{active}} = P_{\text{total}}$.

    The energy consumption per output token is modeled as a function of active parameters and batch size ($B$), following a linear-exponential form:

    $$f_E(P_{\text{active}}, B) = \alpha e^{\beta B} P_{\text{active}} + \gamma$$

    In current implementations, the batch size is assumed to be fixed at $B = 64$. The total GPU energy for a request is calculated as:

    $$E_{\text{GPU}}(#T_{\text{out}}, P_{\text{active}}) = #T_{\text{out}} \times f_E(P_{\text{active}}, 64)$$

    If the model requires multiple GPUs, this value is multiplied by the number of required GPUs.

  5. Access impact metrics and range values

    main

    The video_impacts function returns an ImpactsOutput object. You can access various metrics like energy, global warming potential (GWP), and water consumption.

    Because video impact values are often returned as RangeValue intervals, you can access the mean, min, and max values directly to get central estimates or bounds.

    # Accessing specific metrics
    print(impacts.energy.value)       # Direct electricity consumption, in kWh
    print(impacts.gwp.value)          # Global warming potential, in kgCO2eq
    print(impacts.adpe.value)         # Abiotic resource depletion, in kgSbeq
    print(impacts.pe.value)           # Primary energy, in MJ
    print(impacts.wcf.value)          # Water consumption footprint, in L
    
    # Accessing phase-specific impacts
    print(impacts.usage.gwp.value)    # Usage phase only
    print(impacts.embodied.gwp.value) # Embodied phase only
    
    # Accessing RangeValue components
    print(impacts.gwp.value.mean) # Central estimate
    print(impacts.gwp.value.min)  # Lower bound
    print(impacts.gwp.value.max)  # Upper bound
  6. Follow EcoLogits documentation standards

    main

    When contributing code or documentation, adhere to these styles:

    Code Documentation

    • Use Google-style docstrings.
    • Follow PEP 257 guidelines.
    • Ensure all public functions, classes, and methods are well-documented.

    General Documentation

    • Use a clear, concise, and approachable tone.
    • Provide short, simple, and self-contained code examples.
    • Ensure all examples are complete and runnable.
  7. Difference between EcoLogits and CodeCarbon

    main

    Choosing between EcoLogits and CodeCarbon depends on your level of control over the execution environment:

    • Use CodeCarbon when you control the execution environment (e.g., running models on your laptop, your own server, or your own cloud instances). It is suitable for measuring energy consumption and carbon emissions for training, fine-tuning, or inference.
    • Use EcoLogits when you do not have access to the execution environment because the model is managed by a third-party provider (e.g., using an API). It is designed to estimate the environmental impacts of inference workloads for GenAI services.

    The two tools are complementary and can be used together for a comprehensive view of environmental impacts across different deployment scenarios.

  8. Understand modeling assumptions and limitations

    main

    EcoLogits makes several assumptions to enable environmental impact estimation for LLMs. Users should be aware of these constraints:

    Model Assumptions

    • Infrastructure: Assumes models are deployed with a vLLM backend and quantized to 16 bits.
    • Capabilities: Only accounts for text-to-text generation (no multi-modality).
    • Proprietary Models: Since technical details are often undisclosed, EcoLogits relies on parameter count estimations.

    Hardware Assumptions

    • GPU Type: Assumes models run on NVIDIA H100 GPUs with 80GB of memory.
    • Server Type: Assumes base servers are similar to AWS p5.48xlarge instances.
    • Exclusions: Does not account for TPUs, other accelerators, networking, storage primitives, or infrastructure overheads.

    Data Center & Impact Factor Assumptions

    • Metrics: Uses PUE (Power Usage Effectiveness) and WUE (Water Usage Effectiveness).
    • Electricity Mix: Uses averaged impact factors per country (GWP from Our World in Data, ADPe/PE from ADEME).
    • Limitations: Does not account for local electricity generation specific to a data center or the specific cooling methods used.
  9. Estimate environmental impact for Video Generation

    main

    Video generation impact estimation is performed using the video_impacts function. Unlike Chat Completions, video impact estimation does not require installing provider-specific SDK extras.

    Supported providers for video impact estimation include:

    • ByteDance
    • Google (Gemini)
    • Kling AI
    • OpenAI
    • Runway
  10. How latency is estimated in the EcoLogits Calculator

    main

    The EcoLogits Calculator uses model and provider throughput data from OpenRouter to estimate execution duration. This provides more accurate environmental impact estimates based on expected latency.

    Important: This latency estimation method applies only to the web-based Calculator. The EcoLogits Python library does not use this method; it relies on direct latency measurements from the user's actual requests.

  11. Modeling usage impacts for video generation

    main

    Usage impacts are estimated by calculating the generation latency and the power draw of the hardware configuration. The process involves:

    1. Latency Estimation: Uses model-specific regressions based on spatiotemporal volume ($T = \frac{W \times H \times F}{1000}$), where $W$ is width, $H$ is height, and $F$ is frame count (calculated at 24 fps).
    2. Energy Consumption: Calculated as $E_{\text{server}} = \frac{\Delta T}{3600} \times P_{\text{server}}$, where $P_{\text{server}}$ is the power of the full machine in kW.
    3. Data Center Overhead: The server energy is multiplied by the Power Usage Effectiveness (PUE) to get $E_{\text{request}} = \text{PUE} \times E_{\text{server}}$.
    4. Environmental Impact: The electricity consumption is multiplied by the country-specific electricity-mix factor ($F_{\text{em}}$).

    Water Consumption Footprint (WCF) for usage phase is calculated using: $$\text{WCF}^{\text{u}}{\text{request}} = E{\text{server}} \times [\text{WUE}{\text{on-site}} + \text{PUE} \times \text{WUE}{\text{off-site}}]$$