Why YuE's effective_config Emits a cfg_negative String and Who Consumes It

The cfg_negative string emitted by YuE's effective_config method acts as a metadata flag that records which negative classifier-free-guidance (CFG) strategy was applied during music generation, consumed by the CLI, JSON artifact exporters, and test suites to ensure reproducibility and auditability.

The YuE music generation system (multimodal-art-projection/YuE) uses the effective_config method in src/yue2/pipeline.py to snapshot exact runtime parameters for every generation request. Among these parameters, the cfg_negative field serves a specific purpose: it documents whether the negative CFG utilized only the instruction prompt or both the instruction and chain-of-thought content. This metadata travels through the entire pipeline, enabling precise debugging and configuration tracking.

What cfg_negative Represents in YuE

The cfg_negative field captures the negative classifier-free-guidance mode applied during inference. Classifier-free guidance requires both a positive and negative prompt to steer generation, and YuE varies its negative strategy based on whether chain-of-thought reasoning is enabled.

The field contains one of two string values that indicate the exact policy used:

• "instruction_only" — Indicates the request's chain-of-thought (cot) is turned off, meaning only the instruction part of the prompt is used for constructing the negative CFG.

• "same_instruction_and_exact_abc" — Indicates the request's cot is on, meaning the negative CFG incorporates both the instruction and the exact ABC (music notation) prompt content.

How effective_config Generates cfg_negative in pipeline.py

The logic that assigns these values resides in src/yue2/pipeline.py around lines 369-370 within the effective_config method. When constructing the configuration dictionary, the method inspects the request object's cot attribute to determine the appropriate negative guidance strategy.

If the request disables chain-of-thought, the method assigns "instruction_only" to ensure the negative prompt remains minimal. If chain-of-thought is active, it assigns "same_instruction_and_exact_abc" to include the full musical context in the negative guidance. This ensures the configuration precisely reflects the runtime decision made by the pipeline.

Downstream Consumers of cfg_negative

Once effective_config builds the configuration dictionary, the cfg_negative string propagates through several system components that rely on this metadata for logging, validation, and reproducibility.

Artifact Serialization and result.json

When a generation completes, the resulting SongResult object contains the full config dictionary, including cfg_negative. This dictionary is serialized to JSON format (e.g., in the result.json file saved by save_artifacts as documented in docs/generation.md). External tools, dashboards, and downstream scripts consume this file to record exactly which guidance strategy was applied for a given output.

CLI and Example Scripts

The YuE CLI (src/yue2/cli.py) and example scripts such as main/skills/yue2-music/scripts/run_yue2.py and listen.py read the cfg_negative field for user-facing display and logging. When verbose mode is enabled, these tools print the configuration to help users understand why particular outputs differ based on their chain-of-thought settings.

Integration Testing

Test suites such as test_progress_integration.py consume the cfg_negative field to verify that the pipeline produces correct configuration values for different request modes. These assertions ensure that the CFG strategy remains consistent across software versions and that the metadata correctly reflects the active generation parameters.

Accessing cfg_negative in Practice

You can inspect the cfg_negative value both before and after generation using YuE's Python API.

To check the configuration before generating:

from yue2.pipeline import Pipeline

pipe = Pipeline()
request = pipe._request(style="classical", lyrics="...")
cfg = pipe.effective_config(request)

print(cfg["cfg_negative"])

# Output: "instruction_only" (if request.cot == "off")

To retrieve the value from a completed generation result:

song = pipe(style="jazz", lyrics="...")
print(song.config["cfg_negative"])

# Output reflects the mode used for this specific generation

The CLI implementation in src/yue2/cli.py demonstrates verbose logging:

if args.verbose:
    cfg = pipe.effective_config(request)
    print(f"CFG negative mode: {cfg['cfg_negative']}")

Summary

• cfg_negative is a metadata string emitted by effective_config in src/yue2/pipeline.py that identifies the negative CFG strategy used during music generation.
• The value is determined by the chain-of-thought setting: "instruction_only" for cot off, and "same_instruction_and_exact_abc" for cot on.
• The string is stored in the SongResult config dictionary and serialized to JSON artifacts (e.g., result.json) for external auditing.
• Consumers include the CLI (src/yue2/cli.py), example scripts (run_yue2.py, listen.py), and integration tests that validate configuration correctness.
• The field enables reproducibility by allowing developers and automated systems to verify exactly which negative guidance policy was applied to any generated song.

Frequently Asked Questions

What does cfg_negative mean in YuE?

The cfg_negative field indicates which negative prompt strategy the classifier-free guidance mechanism used during generation. It records whether the negative CFG utilized only the instruction text ("instruction_only") or included both the instruction and the exact ABC music notation ("same_instruction_and_exact_abc"), depending on whether chain-of-thought reasoning was enabled.

How can I check the cfg_negative value after generation?

Access the config dictionary on the SongResult object returned by the pipeline. The cfg_negative key contains the string value. For persisted generations, inspect the result.json file created by save_artifacts, where this configuration metadata is stored alongside the audio output.

Why does cfg_negative change based on the chain-of-thought setting?

The effective_config method in src/yue2/pipeline.py sets cfg_negative based on the request.cot attribute. When chain-of-thought is disabled, the negative CFG only needs the instruction context to avoid confusing the model with unrelated musical content. When enabled, the negative prompt must include the full ABC context to properly contrast against the chain-of-thought reasoning path.

Which source files should I examine to understand cfg_negative implementation?

Start with src/yue2/pipeline.py (lines 369-370) to see the assignment logic in effective_config. For consumption examples, review src/yue2/cli.py for CLI logging, main/skills/yue2-music/scripts/run_yue2.py for artifact handling, and docs/generation.md for documentation on how configuration metadata is preserved with generated artifacts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}