import{s as ht,n as _t,o as vt}from"../chunks/scheduler.78382b47.js";import{S as Tt,i as $t,e as o,s as i,c as f,h as bt,a as s,d as n,b as r,f as se,g as c,j as p,k as le,l,m as a,n as u,t as g,o as h,p as _}from"../chunks/index.6dd35eb6.js";import{C as yt,H as y,E as Ct}from"../chunks/MermaidChart.svelte_svelte_type_style_lang.fed9dfe4.js";import{D as Be}from"../chunks/Docstring.32e826ec.js";import{C as kt}from"../chunks/CodeBlock.af1ec02e.js";function xt(Se){let b,pe,re,de,C,me,k,fe,x,Ae=`Cartridges are a prompt-learning method that stores a compressed long-context representation as a parameterized KV-cache
prefix. The core idea comes from the paper
<a href="https://huggingface.co/papers/2506.06266" rel="nofollow">Cartridges: Lightweight and general-purpose long context representations via self-study</a>.`,ce,w,De=`For a high-level overview and motivation, see the blog post
<a href="https://hazyresearch.stanford.edu/blog/2025-06-08-cartridges" rel="nofollow">Cartridges: Storing long contexts in tiny caches with self-study</a>.`,ue,M,ge,z,qe="Both Prefix Tuning and Cartridges are served by injecting <code>past_key_values</code> (a prefix KV cache) into the base model.",he,L,Ye=`<li>Prefix Tuning learns virtual token embeddings (and optionally an MLP projection) and produces a KV prefix.</li> <li>Cartridges learn the KV prefix itself directly (the per-layer key/value vectors for <code>p</code> virtual tokens), and are
designed to be initialized from real prefill KV (for example, the first <code>p</code> tokens of a corpus/system prompt).</li>`,_e,J,Oe=`The paper also recommends freezing the first token as an attention sink for stability (<code>num_frozen_tokens=1</code> is the
default).`,ve,H,Te,V,et="Load a trained CARTRIDGE adapter and run generation:",$e,E,be,U,tt="If you need to create and initialize a cartridge before training, see the initialization options below.",ye,I,Ce,P,nt="The paper discusses a few practical initialization strategies:",ke,j,at=`<li>Random KV (default): create a <code>CartridgeConfig</code> and start training. This initializes the KV prefix randomly.</li> <li>KV from the first tokens of a prompt/corpus: use <code>initialize_kv_prefix_from_text(model, tokenizer, text=...)</code>. This
runs a prefill on <code>text</code> and copies the resulting KV cache for the first <code>num_virtual_tokens</code> into the adapter.</li> <li>KV from an existing cache: use <code>initialize_kv_prefix_from_past_key_values(model, past_key_values=...)</code> if you already
have a <code>past_key_values</code> object from a base-model prefill.</li>`,xe,R,we,G,it=`The Cartridges paper proposes a SELF-STUDY distillation objective (a frozen base model provides teacher logits; the
CARTRIDGE adapter is trained so the student matches the teacher’s next-token distribution over the target segment).
PEFT keeps training logic out of the core library; see
<code>https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study</code> for a reference workflow.
The example scripts use the frozen base model as the teacher and the adapted model as the student, so both share the
same underlying checkpoint.`,Me,N,ze,Z,rt="To concatenate independently trained cartridges into a single adapter, use <code>compose_cartridge_adapters(...)</code>.",Le,F,Je,m,K,Pe,S,ot="Configuration for CARTRIDGE, a KV-cache-parameterized prefix adapter.",je,A,st=`This is similar to prefix-tuning in how it is served (as <code>past_key_values</code>), but it stores the KV cache directly as
trainable parameters instead of learning it via an MLP projection.`,Re,D,lt=`Initialization:
The Cartridges paper discusses multiple initialization options. In PEFT, initialization is a <em>separate</em> step
from constructing the adapter config:`,Ge,q,pt=`<li><p><strong>Random KV initialization (paper option 2)</strong>: Create the adapter via <code>get_peft_model(...)</code>. The CARTRIDGE
prompt encoder parameters are randomly initialized by PyTorch.</p></li> <li><p><strong>KV derived from the first tokens of a prompt/corpus (paper option 3)</strong>: Run a no-grad prefill on the <em>base
model</em> and copy the first <code>num_virtual_tokens</code> cached KV tokens into the adapter. PEFT provides utilities for
this (importable from <code>peft</code> or from <code>peft.tuners.cartridge.utils</code>):</p> <ul><li><code>initialize_kv_prefix_from_text(model, tokenizer, text=...)</code></li> <li><code>initialize_kv_prefix_from_past_key_values(model, past_key_values=...)</code></li></ul> <p>If you already have a flattened KV-prefix tensor, you can load it directly via the prompt encoder’s
<code>load_prompt_embeddings(...)</code> method.</p></li>`,He,Q,Ve,d,W,Ne,Y,dt="A parameterized prefix KV cache.",Ze,O,mt="The parameters are stored in the same flattened layout as <code>PrefixEncoder</code> output: `[num_virtual_tokens, num_layers",Fe,ee,ft="<li>2 * token_dim]<code>, where </code>token_dim<code>is per-head hidden size times number of heads (after any GQA adjustment performed by</code>_prepare_prompt_learning_config`).</li>",Ke,te,ct=`If <code>num_frozen_tokens &gt; 0</code>, the first <code>num_frozen_tokens</code> virtual tokens are stored as a non-trainable parameter,
and the remaining tokens are trainable.`,Qe,T,X,We,ne,ut="Load the flattened prompt embeddings saved by PEFT (<code>prompt_embeddings</code>).",Xe,ae,gt=`PEFT saves prompt-learning adapters as a single <code>prompt_embeddings</code> tensor. For CARTRIDGE, we split that tensor
into frozen and trainable segments according to <code>self.num_frozen_tokens</code>.`,Ee,B,Ue,oe,Ie;return C=new yt({props:{containerStyle:"float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"}}),k=new y({props:{title:"Cartridges",local:"cartridges",headingTag:"h1"}}),M=new y({props:{title:"How Cartridges differ from Prefix Tuning",local:"how-cartridges-differ-from-prefix-tuning",headingTag:"h2"}}),H=new y({props:{title:"Usage (inference)",local:"usage-inference",headingTag:"h2"}}),E=new kt({props:{code:"ZnJvbSUyMHRyYW5zZm9ybWVycyUyMGltcG9ydCUyMEF1dG9Nb2RlbEZvckNhdXNhbExNJTJDJTIwQXV0b1Rva2VuaXplciUwQSUwQWZyb20lMjBwZWZ0JTIwaW1wb3J0JTIwUGVmdE1vZGVsJTBBJTBBbW9kZWxfaWQlMjAlM0QlMjAlMjJRd2VuJTJGUXdlbjIuNS0wLjVCLUluc3RydWN0JTIyJTBBYWRhcHRlcl9wYXRoJTIwJTNEJTIwJTIycGF0aCUyRnRvJTJGY2FydHJpZGdlX2FkYXB0ZXIlMjIlMEElMEFiYXNlJTIwJTNEJTIwQXV0b01vZGVsRm9yQ2F1c2FsTE0uZnJvbV9wcmV0cmFpbmVkKG1vZGVsX2lkKSUwQW1vZGVsJTIwJTNEJTIwUGVmdE1vZGVsLmZyb21fcHJldHJhaW5lZChiYXNlJTJDJTIwYWRhcHRlcl9wYXRoKSUwQSUwQXRvayUyMCUzRCUyMEF1dG9Ub2tlbml6ZXIuZnJvbV9wcmV0cmFpbmVkKG1vZGVsX2lkKSUwQWlmJTIwdG9rLnBhZF90b2tlbiUyMGlzJTIwTm9uZSUzQSUwQSUyMCUyMCUyMCUyMHRvay5wYWRfdG9rZW4lMjAlM0QlMjB0b2suZW9zX3Rva2VuJTBBJTBBb3V0JTIwJTNEJTIwbW9kZWwuZ2VuZXJhdGUoKip0b2soJTIyUXVlc3Rpb24lMjBhYm91dCUyMHRoZSUyMGNvcnB1cyUzQSUyMiUyQyUyMHJldHVybl90ZW5zb3JzJTNEJTIycHQlMjIpJTJDJTIwbWF4X25ld190b2tlbnMlM0Q2NCklMEFwcmludCh0b2suZGVjb2RlKG91dCU1QjAlNUQlMkMlMjBza2lwX3NwZWNpYWxfdG9rZW5zJTNEVHJ1ZSkp",highlighted:`<span class="hljs-keyword">from</span> transformers <span class="hljs-keyword">import</span> AutoModelForCausalLM, AutoTokenizer

<span class="hljs-keyword">from</span> peft <span class="hljs-keyword">import</span> PeftModel

model_id = <span class="hljs-string">&quot;Qwen/Qwen2.5-0.5B-Instruct&quot;</span>
adapter_path = <span class="hljs-string">&quot;path/to/cartridge_adapter&quot;</span>

base = AutoModelForCausalLM.from_pretrained(model_id)
model = PeftModel.from_pretrained(base, adapter_path)

tok = AutoTokenizer.from_pretrained(model_id)
<span class="hljs-keyword">if</span> tok.pad_token <span class="hljs-keyword">is</span> <span class="hljs-literal">None</span>:
    tok.pad_token = tok.eos_token

out = model.generate(**tok(<span class="hljs-string">&quot;Question about the corpus:&quot;</span>, return_tensors=<span class="hljs-string">&quot;pt&quot;</span>), max_new_tokens=<span class="hljs-number">64</span>)
<span class="hljs-built_in">print</span>(tok.decode(out[<span class="hljs-number">0</span>], skip_special_tokens=<span class="hljs-literal">True</span>))`,wrap:!1}}),I=new y({props:{title:"Initialization options",local:"initialization-options",headingTag:"h2"}}),R=new y({props:{title:"Training",local:"training",headingTag:"h2"}}),N=new y({props:{title:"Composition",local:"composition",headingTag:"h2"}}),F=new y({props:{title:"CartridgeConfig",local:"peft.CartridgeConfig",headingTag:"h2"}}),K=new Be({props:{name:"class peft.CartridgeConfig",anchor:"peft.CartridgeConfig",parameters:[{name:"task_type",val:": Optional[Union[str, TaskType]] = None"},{name:"peft_type",val:": Optional[Union[str, PeftType]] = None"},{name:"auto_mapping",val:": Optional[dict] = None"},{name:"peft_version",val:": Optional[str] = None"},{name:"base_model_name_or_path",val:": Optional[str] = None"},{name:"revision",val:": Optional[str] = None"},{name:"inference_mode",val:": bool = False"},{name:"num_virtual_tokens",val:": int = None"},{name:"token_dim",val:": int = None"},{name:"num_transformer_submodules",val:": Optional[int] = None"},{name:"num_attention_heads",val:": Optional[int] = None"},{name:"num_layers",val:": Optional[int] = None"},{name:"modules_to_save",val:": Optional[list[str]] = None"},{name:"num_frozen_tokens",val:": int = 1"}],parametersDescription:[{anchor:"peft.CartridgeConfig.num_frozen_tokens",description:`<strong>num_frozen_tokens</strong> (<code>int</code>, defaults to 1) &#x2014;
Number of <em>prefix</em> tokens at the start of the cartridge to keep frozen (no gradients). The Cartridges paper
recommends freezing the first token as an attention sink for stability (set this to <code>1</code>), as many LLMs use
early tokens as attention sinks and changing them can harm training.`,name:"num_frozen_tokens"}],source:"https://github.com/huggingface/peft/blob/main/src/peft/tuners/cartridge/config.py#L22"}}),Q=new y({props:{title:"CartridgeEncoder",local:"peft.CartridgeEncoder",headingTag:"h2"}}),W=new Be({props:{name:"class peft.CartridgeEncoder",anchor:"peft.CartridgeEncoder",parameters:[{name:"config",val:""}],source:"https://github.com/huggingface/peft/blob/main/src/peft/tuners/cartridge/model.py#L20"}}),X=new Be({props:{name:"load_prompt_embeddings",anchor:"peft.CartridgeEncoder.load_prompt_embeddings",parameters:[{name:"prompt_embeddings",val:": torch.Tensor"}],source:"https://github.com/huggingface/peft/blob/main/src/peft/tuners/cartridge/model.py#L89"}}),B=new Ct({props:{source:"https://github.com/huggingface/peft/blob/main/docs/source/package_reference/cartridges.md"}}),{c(){b=o("meta"),pe=i(),re=o("p"),de=i(),f(C.$$.fragment),me=i(),f(k.$$.fragment),fe=i(),x=o("p"),x.innerHTML=Ae,ce=i(),w=o("p"),w.innerHTML=De,ue=i(),f(M.$$.fragment),ge=i(),z=o("p"),z.innerHTML=qe,he=i(),L=o("ul"),L.innerHTML=Ye,_e=i(),J=o("p"),J.innerHTML=Oe,ve=i(),f(H.$$.fragment),Te=i(),V=o("p"),V.textContent=et,$e=i(),f(E.$$.fragment),be=i(),U=o("p"),U.textContent=tt,ye=i(),f(I.$$.fragment),Ce=i(),P=o("p"),P.textContent=nt,ke=i(),j=o("ul"),j.innerHTML=at,xe=i(),f(R.$$.fragment),we=i(),G=o("p"),G.innerHTML=it,Me=i(),f(N.$$.fragment),ze=i(),Z=o("p"),Z.innerHTML=rt,Le=i(),f(F.$$.fragment),Je=i(),m=o("div"),f(K.$$.fragment),Pe=i(),S=o("p"),S.textContent=ot,je=i(),A=o("p"),A.innerHTML=st,Re=i(),D=o("p"),D.innerHTML=lt,Ge=i(),q=o("ul"),q.innerHTML=pt,He=i(),f(Q.$$.fragment),Ve=i(),d=o("div"),f(W.$$.fragment),Ne=i(),Y=o("p"),Y.textContent=dt,Ze=i(),O=o("p"),O.innerHTML=mt,Fe=i(),ee=o("ul"),ee.innerHTML=ft,Ke=i(),te=o("p"),te.innerHTML=ct,Qe=i(),T=o("div"),f(X.$$.fragment),We=i(),ne=o("p"),ne.innerHTML=ut,Xe=i(),ae=o("p"),ae.innerHTML=gt,Ee=i(),f(B.$$.fragment),Ue=i(),oe=o("p"),this.h()},l(e){const t=bt("svelte-u9bgzb",document.head);b=s(t,"META",{name:!0,content:!0}),t.forEach(n),pe=r(e),re=s(e,"P",{}),se(re).forEach(n),de=r(e),c(C.$$.fragment,e),me=r(e),c(k.$$.fragment,e),fe=r(e),x=s(e,"P",{"data-svelte-h":!0}),p(x)!=="svelte-1ue0q2l"&&(x.innerHTML=Ae),ce=r(e),w=s(e,"P",{"data-svelte-h":!0}),p(w)!=="svelte-1ccf9yz"&&(w.innerHTML=De),ue=r(e),c(M.$$.fragment,e),ge=r(e),z=s(e,"P",{"data-svelte-h":!0}),p(z)!=="svelte-1methk8"&&(z.innerHTML=qe),he=r(e),L=s(e,"UL",{"data-svelte-h":!0}),p(L)!=="svelte-l51p19"&&(L.innerHTML=Ye),_e=r(e),J=s(e,"P",{"data-svelte-h":!0}),p(J)!=="svelte-tw9ms1"&&(J.innerHTML=Oe),ve=r(e),c(H.$$.fragment,e),Te=r(e),V=s(e,"P",{"data-svelte-h":!0}),p(V)!=="svelte-1f49056"&&(V.textContent=et),$e=r(e),c(E.$$.fragment,e),be=r(e),U=s(e,"P",{"data-svelte-h":!0}),p(U)!=="svelte-eirdc"&&(U.textContent=tt),ye=r(e),c(I.$$.fragment,e),Ce=r(e),P=s(e,"P",{"data-svelte-h":!0}),p(P)!=="svelte-1tx3woq"&&(P.textContent=nt),ke=r(e),j=s(e,"UL",{"data-svelte-h":!0}),p(j)!=="svelte-yoz2sq"&&(j.innerHTML=at),xe=r(e),c(R.$$.fragment,e),we=r(e),G=s(e,"P",{"data-svelte-h":!0}),p(G)!=="svelte-us044p"&&(G.innerHTML=it),Me=r(e),c(N.$$.fragment,e),ze=r(e),Z=s(e,"P",{"data-svelte-h":!0}),p(Z)!=="svelte-9bqgqk"&&(Z.innerHTML=rt),Le=r(e),c(F.$$.fragment,e),Je=r(e),m=s(e,"DIV",{class:!0});var $=se(m);c(K.$$.fragment,$),Pe=r($),S=s($,"P",{"data-svelte-h":!0}),p(S)!=="svelte-m1k6m8"&&(S.textContent=ot),je=r($),A=s($,"P",{"data-svelte-h":!0}),p(A)!=="svelte-1fwlkbd"&&(A.innerHTML=st),Re=r($),D=s($,"P",{"data-svelte-h":!0}),p(D)!=="svelte-1t4yuz7"&&(D.innerHTML=lt),Ge=r($),q=s($,"UL",{"data-svelte-h":!0}),p(q)!=="svelte-14tlo6"&&(q.innerHTML=pt),$.forEach(n),He=r(e),c(Q.$$.fragment,e),Ve=r(e),d=s(e,"DIV",{class:!0});var v=se(d);c(W.$$.fragment,v),Ne=r(v),Y=s(v,"P",{"data-svelte-h":!0}),p(Y)!=="svelte-15wlh3z"&&(Y.textContent=dt),Ze=r(v),O=s(v,"P",{"data-svelte-h":!0}),p(O)!=="svelte-1p64bxy"&&(O.innerHTML=mt),Fe=r(v),ee=s(v,"UL",{"data-svelte-h":!0}),p(ee)!=="svelte-1aiut84"&&(ee.innerHTML=ft),Ke=r(v),te=s(v,"P",{"data-svelte-h":!0}),p(te)!=="svelte-rd7tj0"&&(te.innerHTML=ct),Qe=r(v),T=s(v,"DIV",{class:!0});var ie=se(T);c(X.$$.fragment,ie),We=r(ie),ne=s(ie,"P",{"data-svelte-h":!0}),p(ne)!=="svelte-1v859eu"&&(ne.innerHTML=ut),Xe=r(ie),ae=s(ie,"P",{"data-svelte-h":!0}),p(ae)!=="svelte-1h2mh0j"&&(ae.innerHTML=gt),ie.forEach(n),v.forEach(n),Ee=r(e),c(B.$$.fragment,e),Ue=r(e),oe=s(e,"P",{}),se(oe).forEach(n),this.h()},h(){le(b,"name","hf:doc:metadata"),le(b,"content",wt),le(m,"class","docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8"),le(T,"class","docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8"),le(d,"class","docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8")},m(e,t){l(document.head,b),a(e,pe,t),a(e,re,t),a(e,de,t),u(C,e,t),a(e,me,t),u(k,e,t),a(e,fe,t),a(e,x,t),a(e,ce,t),a(e,w,t),a(e,ue,t),u(M,e,t),a(e,ge,t),a(e,z,t),a(e,he,t),a(e,L,t),a(e,_e,t),a(e,J,t),a(e,ve,t),u(H,e,t),a(e,Te,t),a(e,V,t),a(e,$e,t),u(E,e,t),a(e,be,t),a(e,U,t),a(e,ye,t),u(I,e,t),a(e,Ce,t),a(e,P,t),a(e,ke,t),a(e,j,t),a(e,xe,t),u(R,e,t),a(e,we,t),a(e,G,t),a(e,Me,t),u(N,e,t),a(e,ze,t),a(e,Z,t),a(e,Le,t),u(F,e,t),a(e,Je,t),a(e,m,t),u(K,m,null),l(m,Pe),l(m,S),l(m,je),l(m,A),l(m,Re),l(m,D),l(m,Ge),l(m,q),a(e,He,t),u(Q,e,t),a(e,Ve,t),a(e,d,t),u(W,d,null),l(d,Ne),l(d,Y),l(d,Ze),l(d,O),l(d,Fe),l(d,ee),l(d,Ke),l(d,te),l(d,Qe),l(d,T),u(X,T,null),l(T,We),l(T,ne),l(T,Xe),l(T,ae),a(e,Ee,t),u(B,e,t),a(e,Ue,t),a(e,oe,t),Ie=!0},p:_t,i(e){Ie||(g(C.$$.fragment,e),g(k.$$.fragment,e),g(M.$$.fragment,e),g(H.$$.fragment,e),g(E.$$.fragment,e),g(I.$$.fragment,e),g(R.$$.fragment,e),g(N.$$.fragment,e),g(F.$$.fragment,e),g(K.$$.fragment,e),g(Q.$$.fragment,e),g(W.$$.fragment,e),g(X.$$.fragment,e),g(B.$$.fragment,e),Ie=!0)},o(e){h(C.$$.fragment,e),h(k.$$.fragment,e),h(M.$$.fragment,e),h(H.$$.fragment,e),h(E.$$.fragment,e),h(I.$$.fragment,e),h(R.$$.fragment,e),h(N.$$.fragment,e),h(F.$$.fragment,e),h(K.$$.fragment,e),h(Q.$$.fragment,e),h(W.$$.fragment,e),h(X.$$.fragment,e),h(B.$$.fragment,e),Ie=!1},d(e){e&&(n(pe),n(re),n(de),n(me),n(fe),n(x),n(ce),n(w),n(ue),n(ge),n(z),n(he),n(L),n(_e),n(J),n(ve),n(Te),n(V),n($e),n(be),n(U),n(ye),n(Ce),n(P),n(ke),n(j),n(xe),n(we),n(G),n(Me),n(ze),n(Z),n(Le),n(Je),n(m),n(He),n(Ve),n(d),n(Ee),n(Ue),n(oe)),n(b),_(C,e),_(k,e),_(M,e),_(H,e),_(E,e),_(I,e),_(R,e),_(N,e),_(F,e),_(K),_(Q,e),_(W),_(X),_(B,e)}}}const wt='{"title":"Cartridges","local":"cartridges","sections":[{"title":"How Cartridges differ from Prefix Tuning","local":"how-cartridges-differ-from-prefix-tuning","sections":[],"depth":2},{"title":"Usage (inference)","local":"usage-inference","sections":[],"depth":2},{"title":"Initialization options","local":"initialization-options","sections":[],"depth":2},{"title":"Training","local":"training","sections":[],"depth":2},{"title":"Composition","local":"composition","sections":[],"depth":2},{"title":"CartridgeConfig","local":"peft.CartridgeConfig","sections":[],"depth":2},{"title":"CartridgeEncoder","local":"peft.CartridgeEncoder","sections":[],"depth":2}],"depth":1}';function Mt(Se){return vt(()=>{new URLSearchParams(window.location.search).get("fw")}),[]}class Et extends Tt{constructor(b){super(),$t(this,b,Mt,xt,ht,{})}}export{Et as component};
