Quick Start
Prerequisites
Before setting up the X For You algorithm, ensure your environment meets the following requirements:
- Python 3.10+: Required for the Phoenix (ML) models.
- Rust 1.75+: Required for the Home Mixer, Thunder, and Candidate Pipeline services.
- JAX with CUDA support: Recommended for running the Grok-based transformer models on GPU.
- Kafka: Required for the Thunder service to consume tweet events.
1. Environment Setup
Clone the repository and install the necessary dependencies for both the ML and service layers.
Python Environment
# Install Phoenix ranking and retrieval dependencies
pip install jax jaxlib dm-haiku
pip install git+https://github.com/xai-org/grok-1.git
Rust Services
# Build the orchestration and retrieval services
cargo build --release
2. Running the Phoenix Ranker (Python)
The Phoenix model is the core of the recommendation engine. You can initialize the Grok-based transformer to score candidates based on user history.
import jax
import jax.numpy as jnp
from grok import TransformerConfig
from phoenix.recsys_model import PhoenixRecsysModel, RecsysBatch
# 1. Configure the model (Grok-based architecture)
config = TransformerConfig(
emb_size=128,
num_layers=4,
num_q_heads=4,
num_kv_heads=4,
widening_factor=4
)
# 2. Initialize model and dummy inputs
model = PhoenixRecsysModel(config=config, model=config.make())
batch = RecsysBatch(
user_hashes=jnp.array([[123, 456]]),
history_post_hashes=jnp.zeros((1, 128, 2), dtype=jnp.int32),
# ... fill other batch fields
)
# 3. Perform scoring
# In practice, use hk.transform to manage JAX state
3. Launching the Data Pipeline (Rust)
The algorithm relies on Thunder for in-network content and Home Mixer for orchestration.
Start Thunder (In-Network Fetcher)
Thunder listens to Kafka for real-time tweet events and stores them in an in-memory PostStore.
./target/release/thunder \
--grpc-port 50051 \
--http-port 8080 \
--post-retention-seconds 86400 \
--kafka-group-id "for-you-consumer"
Start Home Mixer (The Orchestrator)
Home Mixer acts as the entry point, coordinating the retrieval of candidates and passing them to Phoenix for ranking.
./target/release/home-mixer \
--grpc-port 50052 \
--metrics-port 9090 \
--chunk-size 100
4. Making Your First Request
Once the services are running, you can request a "For You" feed by calling the ScoredPostsService via gRPC.
The Home Mixer will:
- Hydrate the Query: Look up the user's recent actions and features.
- Retrieve Candidates: Fetch posts from Thunder (In-Network) and Phoenix (Out-of-Network).
- Score and Rank: Use the Phoenix transformer to calculate engagement probabilities.
- Filter: Apply safety and variety filters.
Example gRPC call (using grpcurl)
grpcurl -plaintext \
-d '{"user_id": "12345", "count": 20}' \
localhost:50052 \
xai.home_mixer.pb.ScoredPostsService/GetScoredPosts
Next Steps
- Configure Ranking Weights: Adjust the engagement multipliers in the scoring layer to prioritize likes, replies, or shares.
- Custom Filtering: Modify
candidate-pipeline/filter.rsto implement custom exclusion logic or community safety standards. - Model Training: Refer to the Phoenix Retrieval Guide to learn how to train the two-tower retrieval model on your own interaction datasets.