Tiếng Việt
AITracer

Hướng dẫn bắt đầu nhanh

Tích hợp AITracer chỉ với 3 dòng code. Thời gian cần thiết: khoảng 5 phút

1Tạo tài khoản và lấy API Key

Trước tiên, tạo tài khoản AITracer và lấy API key của bạn.

  1. Tạo tài khoản tại AITracer (miễn phí)
  2. Đăng nhập vào dashboard
  3. Vào "Cài đặt" -> "API Keys" và tạo key mới
  4. Sao chép API key đã được tạo (at-xxxx...)
Bảo mật API key của bạn
Chúng tôi khuyến nghị quản lý API key qua biến môi trường và không hardcode trong mã nguồn.

2Cài đặt SDK

Cài đặt SDK cho ngôn ngữ lập trình của bạn.

Python
PHP
TypeScript

Cài đặt bằng pip:

pip install aitracer

Yêu cầu Python 3.8 trở lên.

Cài đặt bằng Composer:

composer require haro/aitracer

Yêu cầu PHP 8.0 trở lên.

Cài đặt bằng npm hoặc yarn:

# npm
npm install @haro/aitracer

# yarn
yarn add @haro/aitracer

Yêu cầu Node.js 18 trở lên.

3Tích hợp vào code

Chỉ cần bọc LLM client hiện tại của bạn với AITracer để tự động ghi log tất cả các yêu cầu.

Python
PHP
TypeScript

OpenAI

from aitracer import AITracer
from openai import OpenAI

tracer = AITracer(api_key="at-xxxx", project="my-project")
client = tracer.wrap_openai(OpenAI())

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Anthropic

from aitracer import AITracer
from anthropic import Anthropic

tracer = AITracer(api_key="at-xxxx", project="my-project")
client = tracer.wrap_anthropic(Anthropic())

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

Google Gemini

from aitracer import AITracer
import google.generativeai as genai

tracer = AITracer(api_key="at-xxxx", project="my-project")
model = tracer.wrap_gemini(genai.GenerativeModel("gemini-pro"))

response = model.generate_content("Hello!")

LangChain

from aitracer.integrations.langchain import AITracerCallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

# Thiết lập callback handler cho LangChain
handler = AITracerCallbackHandler(api_key="at-xxxx", project="my-project")

llm = ChatOpenAI(model="gpt-4", callbacks=[handler])
response = llm.invoke([HumanMessage(content="Hello!")])

OpenAI

<?php
use AITracer\AITracer;
use OpenAI;

$tracer = new AITracer(['api_key' => 'at-xxxx', 'project' => 'my-project']);
$client = $tracer->wrapOpenAI(OpenAI::client('your-openai-key'));

$response = $client->chat()->create([
    'model' => 'gpt-4',
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!']
    ]
]);

Anthropic

<?php
use AITracer\AITracer;
use Anthropic\Anthropic;

$tracer = new AITracer(['api_key' => 'at-xxxx', 'project' => 'my-project']);
$client = $tracer->wrapAnthropic(Anthropic::client('your-anthropic-key'));

$response = $client->messages()->create([
    'model' => 'claude-sonnet-4-20250514',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => 'Hello!']
    ]
]);

Google Gemini

<?php
use AITracer\AITracer;
use Gemini\Client as GeminiClient;

$tracer = new AITracer(['api_key' => 'at-xxxx', 'project' => 'my-project']);
$client = $tracer->wrapGemini(GeminiClient::factory()->withApiKey('your-gemini-key')->make());

$response = $client->geminiPro()->generateContent('Hello!');

OpenAI

import { AITracer } from '@haro/aitracer';
import OpenAI from 'openai';

const tracer = new AITracer({ apiKey: 'at-xxxx', projectId: 'my-project' });
const openai = new OpenAI();

const start = Date.now();
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Ghi log yêu cầu
await tracer.log({
  model: 'gpt-4',
  provider: 'openai',
  inputData: { messages: [{ role: 'user', content: 'Hello!' }] },
  outputData: response.choices[0].message,
  inputTokens: response.usage?.prompt_tokens,
  outputTokens: response.usage?.completion_tokens,
  latencyMs: Date.now() - start
});

Anthropic

import { AITracer } from '@haro/aitracer';
import Anthropic from '@anthropic-ai/sdk';

const tracer = new AITracer({ apiKey: 'at-xxxx', projectId: 'my-project' });
const anthropic = new Anthropic();

const start = Date.now();
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Ghi log yêu cầu
await tracer.log({
  model: 'claude-sonnet-4-20250514',
  provider: 'anthropic',
  inputData: { messages: [{ role: 'user', content: 'Hello!' }] },
  outputData: response.content,
  inputTokens: response.usage.input_tokens,
  outputTokens: response.usage.output_tokens,
  latencyMs: Date.now() - start
});
Sử dụng biến môi trường
Nếu bạn thiết lập AITRACER_API_KEYAITRACER_PROJECT, bạn có thể bỏ qua các tham số này.

4Xác nhận hoạt động

Sau khi chạy code, kiểm tra dashboard AITracer để xác nhận log của bạn.

  1. Truy cập Dashboard
  2. Mở tab "Logs"
  3. Nếu bạn thấy yêu cầu vừa thực hiện, bạn đã hoàn tất!
Tích hợp hoàn tất!
Tất cả các cuộc gọi LLM của bạn giờ đây được tự động ghi log. Bạn có thể giám sát số token, chi phí và độ trễ theo thời gian thực.

Cài đặt theo nhà cung cấp

Nhà cung cấp Phương thức SDK hỗ trợ
OpenAI tracer.wrap_openai(client) Python, PHP
Anthropic tracer.wrap_anthropic(client) Python, PHP
Google Gemini tracer.wrap_gemini(model) Python, PHP
LangChain AITracerCallbackHandler Python
Ghi log thủ công tracer.log() Python, PHP, TypeScript

Tùy chọn cấu hình

Bạn có thể chỉ định các tùy chọn sau khi khởi tạo:

Cài đặt cơ bản

Tùy chọn Kiểu Mô tả Mặc định
api_key string API key AITracer Biến môi trường AITRACER_API_KEY
project string Tên dự án (hướng dẫn chi tiết) None
enabled bool Bật/tắt ghi log true
base_url string API endpoint https://api.aitracer.co

Cài đặt gửi

Tùy chọn Kiểu Mô tả Mặc định
sync bool Chế độ đồng bộ (khuyến nghị cho Lambda/Cloud Functions) false
batch_size int Kích thước batch khi gửi bất đồng bộ 10
flush_interval float Khoảng thời gian tự động flush (giây, chế độ bất đồng bộ) 5.0
flush_on_exit bool Tự động flush khi thoát tiến trình true

Cài đặt PII (Thông tin cá nhân)

Tùy chọn Kiểu Mô tả Mặc định
pii_detection bool Bật/tắt phát hiện PII false
pii_action string Hành động khi phát hiện PII (mask, redact, hash, none) mask
pii_types array Loại PII cần phát hiện ["email", "phone", "credit_card", "ssn"]

Ví dụ cấu hình

from aitracer import AITracer

tracer = AITracer(
    api_key="at-xxxx",
    project="my-chatbot",

    # Cài đặt PII
    pii_detection=True,
    pii_action="mask",

    # Cài đặt gửi
    batch_size=20,
    flush_interval=10.0,

    # Chế độ đồng bộ (cho serverless)
    sync=False
)
Sử dụng Lambda / Cloud Functions?
Đặt sync=True cho môi trường serverless để tránh mất log.

Theo dõi phiên

Tổng hợp log theo phiên người dùng để trực quan hóa luồng hội thoại.

# Sử dụng lệnh with để quản lý phiên (tự động bắt đầu/kết thúc)
with tracer.session(
    session_id="session-abc123",
    user_id="user-456",
    metadata={"channel": "web", "device": "mobile"}
) as session:

    # Tất cả yêu cầu trong phiên tự động được nhóm lại
    response1 = client.chat.completions.create(...)
    response2 = client.chat.completions.create(...)

    # Ghi nhận phản hồi người dùng
    session.thumbs_up()  # Cho phản hồi cuối cùng

# Phiên tự động kết thúc khi thoát khỏi with block

Tính năng phân tích phiên:

Theo dõi người dùng ứng dụng

Tính năng Người dùng ứng dụng cho phép bạn theo dõi mức sử dụng ở cấp người dùng cuối của ứng dụng AI. Hiểu chi phí, mức sử dụng và mô hình hành vi theo từng người dùng để cải thiện chiến lược tính phí và trải nghiệm người dùng.

Có sẵn trên gói Starter trở lên
Phân tích người dùng ứng dụng có sẵn trên gói Starter và cao hơn.

Chỉ định user_id

Khi bắt đầu phiên với user_id, tất cả log của người dùng đó sẽ tự động được tổng hợp.

# Chỉ định người dùng trong phiên (khuyến nghị)
with tracer.session(
    session_id="session-abc123",
    user_id="user-456",       # ID người dùng của ứng dụng bạn
) as session:
    # Tất cả yêu cầu trong phiên này được liên kết với user-456
    response = client.chat.completions.create(...)

Ngoài ra, bạn có thể chỉ định theo từng yêu cầu qua metadata.

# Chỉ định user_id trong metadata
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    extra_body={
        "aitracer_metadata": {
            "user_id": "user-456"
        }
    }
)

Xem trong Dashboard

Truy cập menu "Người dùng ứng dụng" trong dashboard để xem danh sách và chi tiết người dùng.

Trường hợp sử dụng

Trường hợp sử dụng Mô tả
Tính phí theo mức sử dụng Theo dõi chi phí API theo người dùng để tính toán số tiền tính phí
Giới hạn tỷ lệ Xác định người dùng nặng và thiết kế chính sách giới hạn tỷ lệ
Điều tra lỗi Điều tra nguyên nhân lỗi cho người dùng cụ thể
Cải thiện trải nghiệm Xác định người dùng có độ trễ cao và cải thiện trải nghiệm của họ

Để biết thêm chi tiết, xem Hướng dẫn Dashboard - Phân tích người dùng ứng dụng.

Tính năng Tracing

Nhóm nhiều cuộc gọi API vào một trace duy nhất. Hữu ích cho RAG pipeline và xử lý nhiều bước.

# Nhóm nhiều cuộc gọi API vào một trace duy nhất
with tracer.trace("user-query-123") as trace:
    # Cuộc gọi API đầu tiên
    response1 = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Summarize this article..."}]
    )

    # Cuộc gọi API thứ hai (thuộc cùng trace)
    response2 = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": f"Translate: {response1.choices[0].message.content}"}]
    )

    # Thêm metadata
    trace.set_metadata({
        "user_id": "user-456",
        "feature": "summarization",
        "article_id": "article-789"
    })

Metadata tùy chỉnh

Đính kèm metadata tùy ý vào mỗi yêu cầu để tìm kiếm và lọc sau này.

# Đính kèm metadata theo yêu cầu
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "aitracer_metadata": {
            "user_id": "user-456",
            "session_id": "session-abc",
            "feature": "chat",
            "version": "2.0"
        }
    }
)

Metadata hỗ trợ tối đa 10 key, mỗi giá trị giới hạn 1000 ký tự.