Yerel A-hisse veri havuzu oluşturma rehberi

Yerel A-hisse veri havuzu

Yerel bir A-hisse veri havuzu, Çin anakarası hisse senedi piyasasının geçmiş verilerinin, bir satıcı uç noktasına tek sayfalık çağrılar yapmak yerine, kendi diskinizde sütun tabanlı Parquet dosyaları olarak tutulmasıdır; bu dosyalar DuckDB veya Polars ile okunabilir. ashare-lake, bu havuzu oluşturan, verileri güncel tutan günlük bir iş akışını ve bir yapay zeka aracısının sorgulama yapmasına olanak tanıyan bir Model Context Protocol sunucusunu içeren açık kaynaklı bir projedir. İki tasarım tercihi, bu projeyi burada ele almaya değer kılmaktadır: borsadan çıkarılan şirket isimleri korunmakta ve temel veriler geçmiş bir tarihteki durumlarıyla okunabilmektedir.

Bir yapay zeka ajanının neden yerel bir A-hisse veri gölüne ihtiyacı vardır

Yerel bir kopyası olmadan Çin hisse senetleri üzerinde araştırma yapan bir ajanın önünde iki yol vardır. Ya finans sayfalarını tarayarak bağlam penceresini HTML kodlarına harcar ve gelecek ay kimsenin doğrulayamayacağı rakamlar üretir ya da kayıt zorunluluğu olan bir veri sağlayıcısını arayarak satır sınırlamalarına takılır ve her sonucu bir hesaba bağlamak zorunda kalır.

Ölçek, hafife alınan kısımdır. Kendi veri ambarımız ABD piyasa verilerini dakika bazlı çözünürlükte tutmaktadır ve sıradan bir haftalık veri şu şekildedir:

SELECT toDate(toTimeZone(window_start, 'America/New_York')) AS session,
       formatDateTime(toDate(toTimeZone(window_start, 'America/New_York')), '%b %e') AS session_label,
       uniqExact(ticker) AS tickers_count,
       round(count() / 1000000, 2) AS minute_bars_millions
FROM global_markets.delayed_stocks_minute_aggs
WHERE toDate(toTimeZone(window_start, 'America/New_York')) >= toDate('2026-07-20')
  AND toDate(toTimeZone(window_start, 'America/New_York')) <= toDate('2026-07-24')
GROUP BY session, session_label
ORDER BY session

Jul 20 tarihinde piyasa verileri, 11737 adet sembol üzerinde 1.79 milyon adet dakika bazlı bar üretmiştir; paneldeki diğer dört seans da benzer bir yapıdadır. Tek bir ulusal piyasa, bir hafta, tek bir çözünürlük. Başka bir piyasa için on yıllık günlük barlar, temel veriler, endeks üyeliği ve para akışı kayıtları da aynı yapıdadır ve bu verileri HTTP üzerinden çağırmak bir ajanın çalışma kapasitesini tüketir.

Yerel bir veri gölü aynı anda iki şeyi değiştirir. Okuma işlemleri bir kota yerine dosya taramasına dönüşür ve bugün yazılan bir sorgu altı ay sonra aynı satırları döndürür; bu da bir geriye dönük testin (backtest) denetlenebilir olması için gereken şarttır. Yapay zeka ajanları için piyasa verisi becerileri ve piyasa verileri üzerinde SQL API kullanımı hakkındaki notlarımız, ABD verileri için de aynı argümanı sunmaktadır.

Kurulum ve sürüm sabitleme

Python 3.10 veya daha yeni bir sürüm gereklidir. Sürümü sabitleyin: 27 Temmuz ile 2 Ağustos 2026 tarihleri arasında altı farklı sürüm yayınlanmıştır; bir aracının kurulum betiği içinde sabitlenmemiş bir kurulum, sürekli değişen bir hedeftir. Kod, rootSunc/ashare-lake adresinde Apache 2.0 lisansı altında yer almaktadır.

• pip install ashare-lake==0.5.0, Ağustos 2026 başı itibarıyla güncel sürümü kurar.
• asl --version, yüklü olan derlemeyi yazdırır.
• asl config init --data-root /path/to/ashare-lake, veri kök dizininiz doldurulmuş şekilde paketlenmiş örnek TOML dosyasını oluşturur; depo (repository) indirme işlemi gerektirmez. --config çıktı yolunu belirler, --force ise üzerine yazar.
• asl doctor, herhangi bir veri transferi gerçekleşmeden önce kontrollerini çevrimdışı olarak çalıştırır.
• asl servers test, yukarı yönlü fiyat teklifi (quote) sunucularını tarar. asl sources, her bir kaynağı; --vantage parametresi ile cn, overseas veya local seçeneklerinden biriyle test eder.

Burada durun. Bir sonraki komut geçmişe dönük veri yükleme (backfill) işlemidir ve okuma yaparken başlatılacak bir süreç değildir.

Geriye dönük veri yükleme (backfill) işlevi

asl init dizin yapısını oluşturur ve geçmiş verileri doldurur. Projenin dokümantasyonuna göre tam bir çalışma saatler süren duvar saati süresine ve diskte birkaç GB alana ihtiyaç duyar; ayrıca asl servers test tarafından doğrulanan, yukarı yönlü bir Tongdaxin fiyat sağlayıcısına canlı bağlantı gerektirir. asl init --profile quick bunun yerine son üç yılı dakikalar içinde kapsar ve bu zaman aralığında işlem görmüş, piyasadan ayrılmış olanlar dahil tüm hisse isimlerini korur. asl run daily sonrasındaki artımlı iş yüküdür, asl status --datasets veri seti bazında kapsamı ve güncelliği raporlar, asl serve ise 127.0.0.1:8787 adresinde salt okunur bir gösterge paneli sunar.

Depo hiçbir veri içermez. Her bir Parquet dosyası kendi makinenizde oluşturulur; her satırda, verinin hangi kaynaktan üretildiğini ve ne zaman alındığını kaydeden satır düzeyinde bir köken bilgisi bulunur.

39 veri seti nedir?

Bu veri setleri, referans verilerden dışa doğru katmanlı bir yapıdadır: 36 adet derlenmiş tablo ve üç adet türetilmiş tablo.

• Referans: enstrümanlar, 2016 ile 2027 yıllarını kapsayan bir işlem takvimi, işlem durumu.
• Piyasa verileri: günlük barlar, endeks barları, bir dakikalık ve beş dakikalık barlar, işlem kayıtları (trade ticks), emtia barları, düzeltme katsayıları, kottan çıkma olayları.
• Kurumsal olaylar: kurumsal aksiyonlar, duyuru endeksi, bilanço açıklama takvimi.
• Temel veriler ve değerleme: finansal tablo kalemleri, değerleme metrikleri, analist konsensüsü.
• Sermaye akışı: fon akışı, kredili işlem, kuzey yönlü akışlar ve varlıklar, büyük emir bildirimlerine ilişkin dragon-tiger tahtası, blok işlemler, kurumsal varlıklar.
• Yapı ve sektör: sektör üyeleri, endeks bileşenleri, endüstri üyeleri, endüstri endeksi.
• Makro: makro göstergeler, piyasa genişliği, ekonomik takvim.
• Duyarlılık ve rotasyon: duyarlılık skorları, popülerlik sıralaması (hot rank), sektör barları, sektör fon akışı, haber başlıkları, flaş haber akışı.
• Risk ve uyum: hisse kilit açılış takvimi, düzenleyici kurum olayları.

Bir veri setinin nerede konumlandığı, yazarın neye önem verdiğini gösterir. Düzeltme katsayıları ve kottan çıkma olayları, bir ekte değil, günlük barların yanında piyasa verileri katmanında yer alır; bu yerleşim, geçmiş veriler üzerinde fikirlerini test eden herkes için projenin en değerli kısmını oluşturur.

Yerel bir veri havuzu hayatta kalma yanlılığını nasıl yönetir

Hayatta kalma yanlılığı (survivorship bias), bir çalışmanın evreni yalnızca bugün hâlâ işlem gören isimlerden oluşturulduğunda ortaya çıkar. Birleşen, özel şirket statüsüne geçen veya borsa kotundan çıkarılan her şirket sessizce eksiktir ve kaybolan isimler nadiren kazananlardır.

Veri ambarımız, ABD piyasası için bu boşluğu ölçebilir; farklı bir alfabede aynı aritmetik. Her yıl için, Mart ayının ikinci haftasında bir dakikalık bar verisi basan her sembolü alın ve ardından bunların hangilerinin Temmuz 2026'nın son iki haftasında hâlâ işlem gördüğünü kontrol edin:

WITH on_tape_now AS (
    SELECT ticker
    FROM global_markets.delayed_stocks_minute_aggs
    WHERE toDate(toTimeZone(window_start, 'America/New_York')) >= toDate('2026-07-20')
      AND toDate(toTimeZone(window_start, 'America/New_York')) <= toDate('2026-07-31')
    GROUP BY ticker
),
cohort AS (
    SELECT toYear(toTimeZone(window_start, 'America/New_York')) AS cohort_year,
           ticker
    FROM global_markets.delayed_stocks_minute_aggs
    WHERE toYear(toTimeZone(window_start, 'America/New_York')) BETWEEN 2016 AND 2025
      AND toMonth(toTimeZone(window_start, 'America/New_York')) = 3
      AND toDayOfMonth(toTimeZone(window_start, 'America/New_York')) BETWEEN 10 AND 14
    GROUP BY cohort_year, ticker
)
SELECT c.cohort_year AS year,
       count() AS names_on_tape_count,
       countIf(n.ticker != '') AS still_trading_count,
       count() - countIf(n.ticker != '') AS gone_count,
       round(100 * countIf(n.ticker != '') / count(), 1) AS still_trading_pct
FROM cohort AS c
LEFT JOIN on_tape_now AS n ON c.ticker = n.ticker
GROUP BY year
ORDER BY year

2016 yılının o haftasında işlem gören 8101 sembolden 50.1% tanesi Temmuz 2026 sonunda hâlâ kayıtlardaydı, 4040 tanesi ise değildi. 2025 kohortu 86.7% değerini göstermektedir. Bugünün listelerinden oluşturulan bir taramayı bu 10 yıl boyunca geriye doğru çalıştırırsanız, zaman ilerledikçe piyasanın giderek genişleyen bir payının elendiğini görürsünüz.

Yaygın varsayım, kayıp isimlerin hepsinin düşük değerli hisseler (penny stocks) olduğudur. Mart 2021 kohortunu o ayki ortalama günlük dolar hacmine göre kademelere ayırdığımızda durumun böyle olmadığı görülür:

WITH on_tape_now AS (
    SELECT ticker
    FROM global_markets.delayed_stocks_minute_aggs
    WHERE toDate(toTimeZone(window_start, 'America/New_York')) >= toDate('2026-07-20')
      AND toDate(toTimeZone(window_start, 'America/New_York')) <= toDate('2026-07-31')
    GROUP BY ticker
),
march_2021 AS (
    SELECT ticker,
           sum(toFloat64(close) * toFloat64(volume))
             / uniqExact(toDate(toTimeZone(window_start, 'America/New_York'))) AS avg_daily_dollar_volume
    FROM global_markets.delayed_stocks_minute_aggs
    WHERE toDate(toTimeZone(window_start, 'America/New_York')) >= toDate('2021-03-01')
      AND toDate(toTimeZone(window_start, 'America/New_York')) <= toDate('2021-03-31')
    GROUP BY ticker
)
SELECT multiIf(d.avg_daily_dollar_volume >= 1000000000, '$1B or more',
               d.avg_daily_dollar_volume >= 100000000, '$100M to $1B',
               d.avg_daily_dollar_volume >= 10000000, '$10M to $100M',
               d.avg_daily_dollar_volume >= 1000000, '$1M to $10M',
               'under $1M') AS liquidity_bucket,
       count() AS names_count,
       countIf(n.ticker = '') AS gone_count,
       round(100 * countIf(n.ticker = '') / count(), 1) AS gone_pct
FROM march_2021 AS d
LEFT JOIN on_tape_now AS n ON d.ticker = n.ticker
GROUP BY liquidity_bucket
ORDER BY min(d.avg_daily_dollar_volume)

under $1M kademesi, 3968 isimden 57.5%'i ile en büyük payı kaybetti. En yoğun işlem gören kademe bile bundan muaf değildi: Mart 2021'de günde $1B or more işlem gören 89 sembolden 3.4%'ü Temmuz 2026 sonuna kadar piyasadan ayrılmıştı. Birleşmeler, özel şirket statüsüne geçişler, iflaslar ve endeks çıkışlarının tamamı fiyat tablosunda aynı şekilde sonuçlanır: satırlar durur.

ashare-lake bunu birinci sınıf bir sorun olarak ele alır. Enstrüman veri seti, canlı olanlarla sınırlamak yerine borsa kotundan çıkarılan sembolleri de korur; bir delisting_events tablosu her ayrılan ismin nasıl sonuçlandığını kaydeder ve Python API'sindeki universe="all_a", bunları içeren tarihsel bir anlık görüntüyü (snapshot) çözümler. Projenin kendi belgeleri, 2016 ile 2021 yılları arasında sadece hayatta kalanları içeren bir geriye dönük test (backtest) ile kot dışı kalanları da içeren bir test arasında yaklaşık iki katlık bir fark olduğunu bildirmektedir. Bu, geriye dönük testlerde ileriye bakma yanlılığı notlarımızdaki tuzağın ayna görüntüsüdür: geleceği sessizce bilen bir evren.

Zaman noktasında okumalar

load("financial_statement_items", as_of="2018-04-30"), o tarihte veya öncesinde açıklanan her kalem için en son sürümü döndürür; daha sonra düzeltilmiş rakamı değil. Barlar bir adjust argümanı taşır: geriye dönük düzeltme için hfq, sorgu penceresi içinde normalize edilmiş qfq veya ham fiyatlar. Piyasanın henüz yayınlamadığı rakamlar üzerine kurgulanan bir faktör hiçbir şeyi ölçmez; bu, herhangi bir LLM tarafından üretilen alfa faktörü hattında kontrol edilmesi gereken ilk şeydir.

MCP sunucusu olarak kaydetme

Model Context Protocol, bir ajanın araçları nasıl kullanacağını belirleyen yöntemdir. asl mcp bu protokolü stdio üzerinden yürütür ve istemci süreci başlatır:

• claude mcp add ashare-lake -- asl mcp --config /abs/path/to/ashare-lake.toml
• Diğer tüm MCP istemcileri aynı iki unsuru kullanır: komut olarak asl ve argüman olarak mcp --config ile birlikte mutlak bir dosya yolu. İstemci süreci herhangi bir dizinden başlatabileceği için dosya yolu mutlak olmalıdır.

Veri setlerine göre değil, sorulara göre düzenlenmiş altı araç sunulmaktadır: nelerin mevcut olduğunu ve nasıl okunacağını gösteren describe_lake, bir ismi koda dönüştüren (borsadan çıkarılan isimler dahil) resolve_symbol, query_bars, as_of argümanına sahip query_fundamentals, diğer tüm işlemler için query_dataset ve veri setleri üzerinde tek bir salt okunur DuckDB SELECT sorgusu çalıştıran run_sql. Bir --live bayrağı, sunucunun sembol aramalarını ve düzeltilmemiş günlük bar verilerini, veri gölüne yazma yapmadan doğrudan ana kaynaktan yanıtlamasına olanak tanır.

Öncelikle bilinmesi gereken sınırlamalar

• Yalnızca A-hisseleri. Hong Kong veya ABD borsalarında işlem gören hisseler ya da Çin ana karası dışındaki hiçbir varlık kapsama dahil değildir.
• Kişisel bir proje. Sorun bildirimleri ve pull request talepleri "en iyi çaba" prensibiyle ele alınır; belgelerde açıkça belirtildiği üzere herhangi bir erişilebilirlik garantisi yoktur: Kaynak siteler değişiklik yapabilir veya bir IP adresi engellenebilir; bu durum, birisi yama uygulayana kadar veri alımının durmasına neden olur.
• Apache 2.0 lisansı kodu kapsar, veriyi değil. Her bir kaynak kendi kullanım şartlarını korur; geliştirici, oluşturduğunuz Parquet dosyalarını yeniden dağıtma veya satma hakkı tanımaz. Herhangi bir ticari kullanımdan önce kaynak şartlarını okuyun.
• Okuduğu kaynaklar için herhangi bir hesap veya token gerekmez; projenin cazibesi de kırılganlığı da buradan gelir.
• Windows desteği 0.3.0 sürümüyle gelmiş, Python alt sınırı ise 0.3.1 sürümünde 3.10'a yükseltilmiştir.

Sıkça Sorulan Sorular

Yerel bir A-hisse veri gölü oluşturmak için API anahtarına ihtiyaç var mı?

Bu projede gerek yoktur. Okuduğu yukarı yönlü kaynaklar herhangi bir kayıt veya token gerektirmez; veri gölünün kendisi ise doğrudan yerel makinenizde barınır. Her kaynak kendi kullanım koşullarını belirler; ticari bir çalışma öncesinde bu koşulların incelenmesi gerekir.

ashare-lake geçmiş veri yüklemesi ne kadar sürer?

Dokümantasyon, tam bir geçmiş veri yüklemesinin saatler süreceğini ve birkaç GB disk alanı gerektireceğini belirtmektedir; bu süreç boyunca yukarı yönlü bir fiyat sağlayıcıya aktif bir bağlantı zorunludur. asl init --profile quick son üç yılı dakikalar içinde kapsar ve o tarihten bu yana borsadan çıkarılmış hisseleri de içerir.

Yerel bir A-hisse veri gölü, borsadan çıkarılmış hisseleri içerir mi?

Evet, içerir. Borsadan çıkarılan semboller enstrüman veri setinde kalmaya devam eder, delisting_events tablosu her bir hissenin nasıl sonlandığını kaydeder ve universe="all_a" bunları içeren tarihsel bir anlık görüntü oluşturur. Yukarıdaki ABD piyasası ölçümümüz, sadece hayatta kalan hisselerden oluşan bir evrenin neleri dışarıda bıraktığını göstermektedir.

Bir yapay zeka ajanı ashare-lake üzerinde doğrudan sorgulama yapabilir mi?

Evet. asl mcp, Model Context Protocol üzerinden altı araç sunar; bunlardan biri salt okunur SQL aracıdır. Böylece ajan, veri kazıma yapmak yerine yerel Parquet dosyalarını sorgular. Aracı claude mcp add ashare-lake -- asl mcp --config /abs/path/to/ashare-lake.toml ile kaydedebilirsiniz.

ashare-lake, AkShare veya Baostock'un yerini mi alıyor?

Hayır. Bu kütüphanelerin üzerinde konumlanır. Söz konusu kütüphaneler veriyi yukarı yönlü kaynaklardan çeker; bu proje ise çekilen verileri depolar, sürümlerini yönetir ve satır düzeyinde köken bilgisi ile veri seti başına tek bir sözleşme yapısı kullanarak düzenlenmiş Parquet formatına dönüştürür.

Yukarıdaki her bir veri, gerçek piyasa verileri üzerinde çalıştırılmış, sürümlenmiş bir sorgudur. SQL kodunu görmek için herhangi bir paneli genişletin veya Strasmore terminali üzerinde kendi evreniniz için aynı hayatta kalma (survivorship) kontrolünü çalıştırın.