量子随机采样器

Quick start

Run the built-in urandom-over-gRPC example server

pip install qr-sampler python examples/servers/simple_urandom_server.py --address 0.0.0.0:50051

qr-sampler

Plug any randomness source into LLM token sampling.

qr-sampler is an engine-agnostic framework that replaces standard pseudorandom token sampling with entropy from external sources — quantum random number generators (QRNGs), processor timing jitter, hardware noise, or any source you connect via gRPC or Python plugin. The core sampling pipeline has zero inference-engine dependencies; thin engine adapters integrate it with vLLM, vLLM-Metal, or any engine that supports logits processing.

pip install qr-sampler

---

Why qr-sampler?

Standard LLM inference uses pseudorandom number generators (PRNGs) for token sampling. PRNGs are deterministic — given the same seed, they produce the same output every time. qr-sampler replaces this with true randomness from physical processes:

• Quantum RNGs — photon detectors, vacuum fluctuation devices, or any hardware QRNG over gRPC
• Hardware noise — 63 thermal, timing, microarch, and GPU noise sources via OpenEntropy
• Processor timing jitter — CPU clock variations as an entropy source (experimental)
• Your own source — implement the EntropySource ABC or connect any hardware via the gRPC protocol
• OS entropy — os.urandom() as a fallback or baseline

Start vLLM — qr-sampler registers automatically via entry points

vllm serve Qwen/Qwen2.5-1.5B-Instruct --dtype half --max-model-len 8192 --gpu-memory-utilization 0.80

Configure the entropy source via environment variables:

`qr-sampler list`

Browse available components:

qr-sampler list engines              # Engine profiles (vllm, vllm_metal)
qr-sampler list models --engine vllm # Known-working models for an engine
qr-sampler list entropy-sources      # All entropy source profiles
qr-sampler list amplifiers           # Signal amplification algorithms
qr-sampler list samplers             # Temperature strategies
qr-sampler list presets              # Preset bundles (creative_sampling, normal_t1)

`qr-sampler info`

Detailed information about a specific component:

qr-sampler info engine vllm
qr-sampler info entropy quantum_grpc
qr-sampler info amplifier zscore_mean
qr-sampler info sampler edt
qr-sampler info preset creative_sampling

`qr-sampler validate`

Check stack compatibility before deploying:

```bash

Point qr-sampler at it

export QR_ENTROPY_SOURCE_TYPE=quantum_grpc export QR_GRPC_SERVER_ADDRESS=localhost:50051

Three transport modes:

| Mode | `QR_GRPC_MODE` | Latency | Best for |
|---|---|---|---|
| **Unary** | `unary` | ~1-2ms | Simplicity, debugging |
| **Server streaming** | `server_streaming` | ~0.5-1ms | Middle ground |
| **Bidirectional** | `bidi_streaming` | ~50-100us (same machine) | Production, lowest latency |

For co-located hardware, use Unix domain sockets:

The gRPC client is protocol-agnostic. It uses configurable method paths and generic protobuf wire-format encoding. The only requirement is that your proto puts the byte count as field 1 in the request and the random bytes as field 1 in the response. Configure custom protos via QR_GRPC_METHOD_PATH and QR_GRPC_STREAM_METHOD_PATH.

Circuit breaker

The gRPC client includes an adaptive circuit breaker:

• Tracks rolling P99 latency over the last 100 requests
• Sets timeout to max(5ms, P99 * 1.5) (configurable via QR_CB_* env vars)
• Opens after 3 consecutive failures, enters half-open state after 10s
• Falls back to QR_FALLBACK_MODE when the circuit is open

Controlling qr-sampler from the UI

A pre-built filter function injects qr-sampler per-request parameters into every chat message via the Open WebUI Valves system. This lets you adjust temperature, top-k, top-p, sample count, and other sampling parameters from the admin panel.

To set it up:

1. Go to Admin Panel > Functions in Open WebUI.
2. Click Import and select examples/open-webui/qr_sampler_filter.json.
3. Toggle the function to Global.
4. Click the gear icon to adjust parameters.

See examples/open-webui/README.md for the full guide.

Open WebUI is entirely optional. qr-sampler works the same way with direct API calls, curl, Python clients, or any OpenAI-compatible tool.

---

1. Validate your stack (optional)

The CLI checks compatibility of engines, models, entropy sources, and amplifiers before you deploy:

```bash pip install qr-sampler[cli]

Edit .env — set HF_TOKEN if using a gated model

docker compose up --build ```

With a config file

qr-sampler validate --config stack.yaml ```

Exit codes: 0 = all known-working, 1 = untested combinations (warnings), 2 = incompatible or missing.

From a config file

qr-sampler build --config stack.yaml --output ./deploy ```

---

Process-wide via env var

QR_PRESET=creative_sampling python -m vllm serve Qwen/Qwen2.5-1.5B-Instruct

Configuration reference

All configuration is done via environment variables with the QR_ prefix. Per-request overrides use the qr_ prefix in extra_args.

Setting up your own entropy source

qr-sampler is designed to connect any randomness source to LLM token sampling. There are two approaches.

Configure the gRPC address

cd deploy

Edit .env: QR_GRPC_SERVER_ADDRESS=<your-server>:50051

docker compose up --build

Or configure directly via environment variables (bare-metal):

The template handles all gRPC boilerplate (unary + bidirectional streaming, health checks, graceful shutdown). You only write the hardware-specific code.

#### The gRPC protocol

message EntropyRequest { int32 bytes_needed = 1; int64 sequence_id = 2; }

message EntropyResponse { bytes data = 1; int64 sequence_id = 2; int64 generation_timestamp_ns = 3; string device_id = 4; }

Any language that supports gRPC can implement this server — Python, C++, Rust, Go, etc.

#### Just-in-time constraint

The entropy must be generated **after** the client sends the request, not from a pre-generated pool:

- No buffering or caching of previously generated bytes
- The physical measurement happens during the `generate()` call
- `generation_timestamp_ns` in the response proves freshness

This is critical for consciousness-research applications where the timing relationship between logit computation and entropy generation matters.

#### Deployment options

**systemd (Linux):**

**Unix domain sockets** (lowest latency for co-located hardware):

CLI reference

The CLI requires the [cli] extra: pip install qr-sampler[cli]

Per-token sampling pipeline

Engine adapter calls pipeline.sample_token(logits_1d)
  │
  ├─ Temperature strategy ─────── Compute per-token temperature
  │   (fixed or entropy-dependent)    from the logit distribution
  │
  ├─ Entropy source ───────────── Fetch fresh random bytes
  │   (gRPC / system / timing /       just-in-time, after logits exist
  │    openentropy / custom)
  │
  ├─ Signal amplification ─────── Convert 20,480 bytes → one float u ∈ (0,1)
  │   (z-score or ECDF)               via statistical aggregation
  │
  ├─ Token selector ───────────── top-k → softmax → top-p → CDF → select
  │   (CDF binary search with u)      token from probability distribution
  │
  └─ Force one-hot logits ─────── Set selected token to 0.0, all others to -inf
      (engine picks exactly              (returned as numpy; adapter converts
       this token)                        to engine-native tensor)

The core pipeline is importable and functional without vLLM, torch, or any engine package. Engine adapters convert between engine-native tensors and numpy, delegate to SamplingPipeline.sample_token(), and write the result back.

---

In your package's pyproject.toml

[project.entry-points."qr_sampler.entropy_sources"] lava_lamp = "my_package:LavaLampEntropySource" ```

The source is auto-discovered when qr-sampler starts. See Setting up your own entropy source below.

---

Approach B: Python plugin (in-process)

For entropy sources that don't need a separate server, implement the EntropySource ABC directly:

from qr_sampler.entropy.base import EntropySource
from qr_sampler.entropy.registry import register_entropy_source

@register_entropy_source("my_source")
class MyEntropySource(EntropySource):
    @property
    def name(self) -> str:
        return "my_source"

    @property
    def is_available(self) -> bool:
        return True

    def get_random_bytes(self, n: int) -> bytes:
        return my_hardware.read(n)

    def close(self) -> None:
        my_hardware.disconnect()

Register via entry points in your package's pyproject.toml:

[project.entry-points."qr_sampler.entropy_sources"]
my_source = "my_package.entropy:MyEntropySource"

Then set QR_ENTROPY_SOURCE_TYPE=my_source.

Plugin architecture

qr-sampler uses a registry + entry-points pattern for extensibility:

qr_sampler.entropy_sources          Third-party entropy sources
qr_sampler.engine_adapters          Third-party engine adapters
vllm.logits_processors              vLLM plugin registration

Each subsystem (entropy, amplification, temperature, engines) has its own registry with decorator-based registration for built-in implementations and entry-point discovery for third-party extensions. The pipeline never instantiates strategy classes directly — it always goes through the registry.

Adding new components

New engine adapter: Subclass EngineAdapter, implement get_pipeline(). Register with @EngineAdapterRegistry.register("name"). Add entry point under qr_sampler.engine_adapters.

New entropy source: Subclass EntropySource, implement name, is_available, get_random_bytes(), close(). Register with @register_entropy_source("name").

New signal amplifier: Subclass SignalAmplifier, implement amplify(raw_bytes) -> AmplificationResult. Register with @AmplifierRegistry.register("name").

New temperature strategy: Subclass TemperatureStrategy, implement compute_temperature(logits, config) -> TemperatureResult. Always compute Shannon entropy. Register with @TemperatureStrategyRegistry.register("name").

See CONTRIBUTING.md for detailed development instructions.

---